Docs/Reference

REST API reference

The REST API lets you query published records together with their provenance, inspect runs, assets and sources, and read change feeds. All responses are JSON.

Base URL and authentication

The base URL is https://api.synchronoid.com/v1. Create a token in the control room under Settings, API tokens. Send it in the Authorization header.

terminal

$ curl -s https://api.synchronoid.com/v1/runs?limit=2 \
    -H "Authorization: Bearer syn_live_9aF3..."

Tokens belong to one workspace and have a scope: read or read_write. Tokens that start with syn_test_ work against the dev environment. Never put a token in browser code.

Pagination

List endpoints return at most limit items (default 50, maximum 200) and a cursor for the next page.

response

{
  "data": [ ... ],
  "next_cursor": "cur_7Hq2",
  "has_more": true
}

Pass ?cursor=cur_7Hq2 to get the next page. When has_more is false, you have reached the end.

Errors

Errors use standard HTTP status codes and a JSON body.

response, 404

{
  "error": {
    "code": "SYN-4040",
    "message": "Asset not found: companies_old",
    "request_id": "req_5b1e0c"
  }
}

Status	Meaning
400	Invalid parameter or body.
401	Missing or invalid token (`SYN-4010`).
403	Token scope is too small.
404	Object not found.
409	Conflict, for example a run already started with the same key.
429	Too many requests. See below.
5xx	Server error. Retry with backoff. Include `request_id` when you contact support.

Runs

Method and path	Description
`GET /runs`	List runs. Filters: `status`, `asset`, `since`.
`GET /runs/{id}`	Get one run with its steps.
`POST /runs`	Start a run for an asset or pipeline.
`POST /runs/{id}/replay`	Replay a run. Body: `{"from_layer": "raw"}`.

GET /v1/runs/run_8f3a21

{
  "id": "run_8f3a21",
  "asset": "companies_current",
  "status": "succeeded",
  "attempts": 2,
  "started_at": "2026-10-28T02:00:01Z",
  "duration_ms": 134210,
  "steps": [
    {"name": "company_profiles", "status": "succeeded", "attempts": 2}
  ]
}

Assets and sources

Method and path	Description
`GET /assets`	List assets with layer, freshness and last run.
`GET /assets/{name}`	Get one asset, including partition status.
`GET /sources`	List sources.
`GET /sources/{name}`	Get one source with its rate limit usage.
`POST /sources/{name}/pause`	Pause a source. Needs `read_write`.
`POST /sources/{name}/resume`	Resume a source.

GET /v1/sources/company_registry

{
  "name": "company_registry",
  "state": "active",
  "rate_limit": {"per_minute": 120, "used_last_5m_avg": 87, "queued": 14},
  "last_success_at": "2026-10-28T02:03:11Z"
}

Records with provenance

Read records from the published layer. Add include=provenance to see where each field came from.

Method and path	Description
`GET /assets/{name}/records`	List records. Filters: `updated_since`, `filter[field]=value`.
`GET /assets/{name}/records/{key}`	Get one record by key.
`GET /assets/{name}/records/{key}/history`	Change history of one record.

terminal

$ curl -s "https://api.synchronoid.com/v1/assets/companies_current/records/c-104392?include=provenance" \
    -H "Authorization: Bearer $SYN_TOKEN"

response

{
  "key": {"org_id": "c-104392"},
  "values": {"name": "Acme Holdings", "address": "48 Mill Lane, Leeds"},
  "provenance": {
    "name":    {"source": "company_registry", "fetched_at": "2026-10-28T02:03:11Z", "run_id": "run_8f3a21"},
    "address": {"source": "company_registry", "fetched_at": "2026-10-28T02:03:11Z", "run_id": "run_8f3a21"}
  }
}

Change feed

Method and path	Description
`GET /feeds`	List subscriptions.
`GET /feeds/{name}/events`	Read events. Parameters: `cursor`, `since`, `limit`, `type`.

Delivery behavior and webhook verification are explained in Change feeds.

API rate limits

The API limits requests per token.

Plan	Limit
Explorer	60 requests per minute
Team	600 requests per minute
Enterprise	Agreed in the contract

Each response has the headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. When you get 429, wait for the number of seconds in Retry-After and then try again. This is separate from the request budgets of your sources.