> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections

Instant Database — sync webhook data into queryable collections with schema inference.

Collections are part of hookstream's Instant Database feature. A collection automatically syncs events from a source into a queryable table using a `primary_key_path` for upsert (last-write-wins). Collections support schema inference from record samples, full-text search, NDJSON/CSV export, and batch backfill from existing events.

## List Collections

GET `/v1/collections`

List all collections.

**Authentication:** API key or session cookie.

```json 200 OK
{
  "collections": [
    {
      "id": "col_c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
      "name": "Orders",
      "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "primary_key_path": "data.id",
      "record_count": 1250,
      "created_at": "2026-02-28T10:00:00Z"
    }
  ]
}
```

## Create Collection

POST `/v1/collections`

Create a new collection linked to a source.

**Authentication:** API key or session cookie.

### Body Parameters

Display name for the collection.

URL-safe slug for the collection (e.g., `"orders"`).

Source to sync events from.

Dot-notation path to the primary key field in the event body (e.g., `"data.id"`).

```bash cURL
curl -X POST https://hookstream.io/v1/collections \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Orders",
    "slug": "orders",
    "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "primary_key_path": "data.id"
  }'
```

```json 201 Created
{
  "collection": {
    "id": "col_c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
    "name": "Orders",
    "slug": "orders",
    "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "primary_key_path": "data.id",
    "record_count": 0,
    "created_at": "2026-03-01T12:00:00Z"
  }
}
```

## Retrieve Collection

GET `/v1/collections/:id`

Get a single collection by ID.

**Authentication:** API key or session cookie.

```json 200 OK
{
  "id": "col_c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
  "name": "Orders",
  "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "primary_key_path": "data.id",
  "record_count": 1250,
  "created_at": "2026-02-28T10:00:00Z",
  "updated_at": "2026-03-01T14:00:00Z"
}
```

## Update Collection

PATCH `/v1/collections/:id`

Update a collection's name or description.

**Authentication:** API key or session cookie.

```bash cURL
curl -X PATCH https://hookstream.io/v1/collections/col_c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4 \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "All Orders"}'
```

```json 200 OK
{
  "id": "col_c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
  "name": "All Orders",
  "updated_at": "2026-03-01T15:00:00Z"
}
```

## Delete Collection

DELETE `/v1/collections/:id`

Delete a collection and all its synced records.

**Authentication:** API key or session cookie.

```json 200 OK
{ "success": true }
```

## List Records

GET `/v1/collections/:id/records`

List records in a collection with optional search and pagination.

**Authentication:** API key or session cookie.

### Query Parameters

Cursor for pagination.

Number of results to return (max 100).

Full-text search across record data.

```json 200 OK
{
  "records": [
    {
      "id": "rec_001",
      "primary_key": "ord_abc123",
      "data": {
        "type": "order.created",
        "data": { "id": "ord_abc123", "amount": 4999 }
      },
      "source_event_at": "2026-03-01T14:00:00Z",
      "synced_at": "2026-03-01T14:00:01Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

## Retrieve Record

GET `/v1/collections/:id/records/:key`

Get a single record by its record key.

**Authentication:** API key or session cookie.

```json 200 OK
{
  "record": {
    "id": "rec_001",
    "collection_id": "col_c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
    "record_key": "ord_abc123",
    "data": {
      "type": "order.created",
      "data": { "id": "ord_abc123", "amount": 4999 }
    },
    "source_event_at": "2026-03-01T14:00:00Z",
    "synced_at": "2026-03-01T14:00:01Z"
  }
}
```

## Record Changelog

GET `/v1/collections/:id/records/:key/changelog`

Get the change history for a specific record.

**Authentication:** API key or session cookie.

### Query Parameters

Number of changelog entries to return (max 100).

```json 200 OK
{
  "changelog": [
    {
      "id": "cl_001",
      "collection_id": "col_c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
      "record_key": "ord_abc123",
      "event_id": "evt_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
      "created_at": "2026-03-01T14:00:01Z"
    }
  ]
}
```

## Collection Stats

GET `/v1/collections/:id/stats`

Get collection statistics (record count, size, last sync).

**Authentication:** API key or session cookie.

```json 200 OK
{
  "record_count": 1250,
  "changelog_entries": 3420,
  "last_sync_at": "2026-03-01T14:30:00Z"
}
```

## Infer Schema

GET `/v1/collections/:id/schema`

Infer JSON schema from a sample of up to 200 records in the collection.

**Authentication:** API key or session cookie.

Schema inference runs on-demand against a rolling sample — there is no stored schema. Sampling 200 records is fast (tens of milliseconds) and avoids stale schemas as your data shape evolves.

```json 200 OK
{
  "fields": [
    { "name": "type", "type": "string", "nullable": false },
    { "name": "data.id", "type": "string", "nullable": false },
    { "name": "data.amount", "type": "number", "nullable": false }
  ],
  "sample_count": 200
}
```

## Export Records

GET `/v1/collections/:id/export`

Export all collection records as NDJSON or CSV.

**Authentication:** API key or session cookie.

### Query Parameters

Export format: `json` (NDJSON) or `csv`.

```text 200 OK
{"primary_key":"ord_abc123","data":{"type":"order.created","data":{"id":"ord_abc123","amount":4999}}}
{"primary_key":"ord_def456","data":{"type":"order.updated","data":{"id":"ord_def456","amount":7500}}}
```

## Start Backfill

POST `/v1/collections/:id/backfill`

Start a backfill job to sync existing events into the collection.

**Authentication:** API key or session cookie.

```bash cURL
curl -X POST https://hookstream.io/v1/collections/col_c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4/backfill \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"
```

```json 200 OK
{
  "status": "running",
  "total": 1250,
  "message": "Backfill started"
}
```

## Check Backfill Status

GET `/v1/collections/:id/backfill`

Check the status and progress of a backfill job.

**Authentication:** API key or session cookie.

```json 200 OK
{
  "status": "running",
  "progress": 800,
  "total": 1250,
  "started_at": "2026-03-01T15:00:00Z",
  "completed_at": null,
  "error": null
}
```