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{ "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").
bashcurl -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{ "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{ "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.
bashcurl -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{ "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{ "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{ "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{ "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{ "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{ "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{ "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{"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.
bashcurl -X POST https://hookstream.io/v1/collections/col_c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4/backfill \ -H "X-API-Key: $HOOKSTREAM_API_KEY"
json{ "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{ "status": "running", "progress": 800, "total": 1250, "started_at": "2026-03-01T15:00:00Z", "completed_at": null, "error": null }