API Reference

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.

Anonymous ingest

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:

StatusCodeMeaning
413FILE_TOO_LARGEPayload 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.
422NO_KEY_FIELDNo candidate key column exists; nothing was ingested
422DUPLICATE_KEYThe key column repeats a value (the body carries field and duplicateValue)

Authentication

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 keys
  • • read: sources, delta events, row data, and downloads
  • • download: snapshot exports only

Record-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.

List sources

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 delta events

GET https://api.catalogian.com/v1/sources/:id/delta
Authorization: Bearer <key>

Query parameters:

ParamDescription
sinceISO 8601 timestamp — only return events after this time
limitMax results (default 50, max 200)
cursorPagination cursor from previous response
keysLimitMax 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 latest delta event

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.

Get delta rows

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:

ParamDescription
changeTypenew | changed | deleted
limitMax results per page
cursorPagination cursor from previous response

Response includes before/after values for each changed row.

Errors

Standard HTTP status codes. Error body:

{ "error": "Human-readable message" }
StatusMeaning
401Unauthorized — missing or invalid API key
403Forbidden — API key lacks required scope
404Not Found — source or event doesn't exist
429Too Many Requests — rate limit exceeded