The Catalogian REST API lets you query sources, delta events, and row-level changes. Account endpoints authenticate with an API key (cat_live_*); the dashboard itself uses your signed-in session. No account? The anonymous ingest flow needs no key at all: see Anonymous ingest below.
No account needed. POST /v1/ephemeral/ingest with a data URL (or a multipart file upload) and Catalogian returns a session token, a source, and the first delta:
curl -X POST https://api.catalogian.com/v1/ephemeral/ingest \
-H "Content-Type: application/json" \
-d '{"url": "https://catalogian.com/demo/outdoor-life.csv"}'The first ingest returns the session token (cat_eph_...) exactly once: save it, later responses never echo it. The session holds for 24 hours unless the record is kept. Free: 10,000 rows indexed per record, 3 ingests per session, 50 MCP tool calls per session.
Using the token: for MCP, put it on the MCP URL as the ?token= parameter, https://api.catalogian.com/v1/mcp?token=cat_eph_YOUR_SESSION_TOKEN. Ephemeral session tokens do not work in the Authorization: Bearer header on MCP. On the ephemeral routes themselves the Bearer header does work: send it to GET /v1/ephemeral/session for record details, or with a revision POST to /v1/ephemeral/ingest. The token does not authenticate any other REST endpoint.
Ingest errors:
| Status | Code | Meaning |
|---|---|---|
| 413 | FILE_TOO_LARGE | Payload too large (the 520 MB upload cap; the body carries limitBytes). Compress it with gzip and try again. A decompressed-size ceiling answers the same status with PAYLOAD_TOO_LARGE. |
| 422 | NO_KEY_FIELD | No candidate key column exists; nothing was ingested |
| 422 | DUPLICATE_KEY | The key column repeats a value (the body carries field and duplicateValue) |
Account keys are created in the dashboard under Settings → Developers; record-scoped keys live on a record's Connect tab (Record API Keys). Pass the key as a Bearer token:
Authorization: Bearer <key>
Scopes:
full: everything, including creating records and managing keysread: sources, delta events, row data, and downloadsdownload: snapshot exports onlyRecord-scoped keys
A record-scoped key (cat_src_...) automatically resolves to its record, no record ID needed in the URL. Use the record slug anywhere a :id appears:
GET /v1/sources/west-coast-earthquakes/snapshot-rows Authorization: Bearer cat_src_...
Tip: GET /v1/sources with a record-scoped key returns only the scoped record, no ID or slug param needed.
GET https://api.catalogian.com/v1/sources Authorization: Bearer <key>
Response:
[
{
"id": "cmmfyryl30005ygld7m5596gm",
"name": "West Coast Earthquakes",
"type": "http",
"status": "active",
"keyField": "id",
"format": "csv",
"url": "https://catalogian.com/demo/outdoor-life.csv",
"lastCheckedAt": "2026-09-28T20:00:00.000Z",
"checkIntervalMinutes": 60
}
]GET https://api.catalogian.com/v1/sources/:id/delta Authorization: Bearer <key>
Query parameters:
| Param | Description |
|---|---|
since | ISO 8601 timestamp — only return events after this time |
limit | Max results (default 50, max 200) |
cursor | Pagination cursor from previous response |
keysLimit | Max keys per category (default 100, max 1000) |
Response:
{
"sourceId": "cmmfyryl30005ygld7m5596gm",
"count": 2,
"hasMore": false,
"nextCursor": null,
"events": [
{
"id": "evt_01j...",
"detectedAt": "2026-09-28T20:00:00.000Z",
"newCount": 5,
"changedCount": 3,
"deletedCount": 1,
"unchangedCount": 193,
"totalCount": 202,
"isNoChange": false,
"newKeys": ["nc75443740", "nc75443741"],
"changedKeys": ["nc75443737"],
"deletedKeys": ["nc75443001"]
}
]
}GET https://api.catalogian.com/v1/sources/:id/delta/latest Authorization: Bearer <key>
Same response shape as above but returns a single event object, not an array.
Changed row data — before/after values for each affected row.
GET https://api.catalogian.com/v1/sources/:id/delta/:deltaEventId/rows Authorization: Bearer <key> (requires the read or full scope)
Query parameters:
| Param | Description |
|---|---|
changeType | new | changed | deleted |
limit | Max results per page |
cursor | Pagination cursor from previous response |
Response includes before/after values for each changed row.
Standard HTTP status codes. Error body:
{ "error": "Human-readable message" }| Status | Meaning |
|---|---|
| 401 | Unauthorized — missing or invalid API key |
| 403 | Forbidden — API key lacks required scope |
| 404 | Not Found — source or event doesn't exist |
| 429 | Too Many Requests — rate limit exceeded |