API Reference

The Catalogian REST API lets you query sources, delta events, and row-level changes. All endpoints require authentication via API key.

Authentication

API keys are created in the dashboard under Source Settings → API Keys. Pass the key as a Bearer token:

Authorization: Bearer <key>

Scopes:

• read — default scope, access sources and delta events
• read:rows — required for delta rows endpoint (full row data)

Source-scoped keys

A source-scoped key (cat_src_...) automatically resolves to its source — no source ID needed in the URL. Use the source slug anywhere a :id appears:

GET /v1/sources/my-product-catalog/snapshot-rows
Authorization: Bearer cat_src_...

Tip: GET /v1/sources with a source-scoped key returns only the scoped source — no source ID or slug param needed.

List sources

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

Response:

[
  {
    "id": "cmmfyryl30005ygld7m5596gm",
    "name": "My Product Feed",
    "type": "http",
    "status": "active",
    "keyField": "id",
    "format": "csv",
    "url": "https://...",
    "lastCheckedAt": "2026-03-08T20:00:00.000Z",
    "checkIntervalMinutes": 60
  }
]

Get delta events

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-03-08T20:00:00.000Z",
      "newCount": 14,
      "changedCount": 3,
      "deletedCount": 0,
      "unchangedCount": 49983,
      "totalCount": 50000,
      "isNoChange": false,
      "newKeys": ["sku-9001", "sku-9002"],
      "changedKeys": ["sku-1234"],
      "deletedKeys": []
    }
  ]
}

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 read:rows 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.

Errors

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