Skip to main content

Getting started

Connect your application to the Rosetta Sync API in five steps. You need the base URL and a bearer token from your Rosetta operator (see Authentication).

Step 1 — Store your credentials​

export ROSETTA_SYNC_TOKEN="<token from your operator>"   # never commit this

Step 2 — Verify connectivity​

GET /health is unauthenticated — use it to confirm the base URL is reachable before sending your token anywhere:

curl https://sync.example.com/health
{ "status": "ok" }

Step 3 — Fetch your first records page​

curl -H "Authorization: Bearer $ROSETTA_SYNC_TOKEN" \
  "https://sync.example.com/api/v1/records/patient?_limit=2"
{
  "records": [
    {
      "id": "f3024f2e-0583-4759-a9b8-c534e6763391",
      "resourceType": "patient",
      "version": 1,
      "payload": {
        "identifiers": [{ "system": "urn:michels:pid", "value": "1234567" }],
        "familyName": "Mueller",
        "givenNames": ["Anna"],
        "birthDate": "1980-05-01",
        "gender": "female"
      },
      "updatedAt": "2026-07-14T04:32:56.082Z",
      "orgSlug": "default",
      "identifiers": [{ "system": "urn:michels:pid", "value": "1234567" }]
    }
  ],
  "total": 1
}

See Records API for pagination, identifier lookups, and the other resource types, and Data types for the full field reference behind payload.

Step 4 — Poll the change feed​

The records API is a point-lookup surface; most integrations stay in sync by polling the change feed instead. Start from since=0 for an initial backfill:

curl -H "Authorization: Bearer $ROSETTA_SYNC_TOKEN" \
  "https://sync.example.com/api/v1/changes?since=0&limit=100"
{
  "events": [
    {
      "sequence": 1,
      "resourceType": "patient",
      "canonicalId": "f3024f2e-0583-4759-a9b8-c534e6763391",
      "operation": "create",
      "version": 1,
      "occurredAt": "2026-07-14T04:32:56.082Z",
      "orgSlug": "default",
      "record": {
        "identifiers": [{ "system": "urn:michels:pid", "value": "1234567" }],
        "familyName": "Mueller",
        "givenNames": ["Anna"],
        "birthDate": "1980-05-01",
        "gender": "female"
      }
    }
  ],
  "nextSince": 1
}

Persist nextSince (here, 1) as your cursor and pass it back as since on your next call. See Change Feed for ordering and idempotency guarantees.

Step 5 — (Optional) Subscribe to webhooks instead of polling​

If you'd rather receive events by push than poll on an interval, register a webhook subscription once and verify each signed delivery — see Webhooks.

Next steps​

  • Authentication — token provisioning, header format, and the 401 failure shape.
  • Records API — on-demand reads by id or business identifier.
  • Change Feed — the full event shape, ordering, and idempotency rules.
  • Webhooks — subscriptions, signature verification, retries, and backoff.
  • Data types — the field reference, enum values, and worked examples for every resource type's payload shape.
  • API Reference — the full per-resource-type schema, in this site's navigation.