Records API

A small, secondary surface for reading records on demand — most integrations should prefer the change feed or webhooks to stay in sync, and use this API for point lookups.

List records of one resource type

GET /api/v1/records/:resourceType[?identifier=<system>|<value>][&_limit=][&_offset=][&org=<slug>]

• :resourceType — one of patient, encounter, condition, coverage, procedure, observation, assessment, care-plan. An unknown resource type returns 400 { "code": "invalid-request" }.
• identifier — optional business-identifier lookup, formatted as <system>|<value>, e.g. identifier=urn:michels:pid|1234567. When present, the response contains only the record matching that identifier.
• _limit — page size. Defaults to 50, capped at 200.
• _offset — pagination offset. Defaults to 0.
• org — optional; scopes results to one organization by slug, same semantics as the change feed's org parameter.

Response:

{ "records": [/* RecordListItem[] */], "total": 1 }

Fetch one record by id

GET /api/v1/records/:resourceType/:canonicalId

Returns a single RecordListItem, or 404 { "code": "not-found" } if canonicalId doesn't exist for that resource type, or 400 { "code": "invalid-request" } for an unknown resourceType.

Record shape

Every item — from either route — has the same shape:

{
  "id": "f3024f2e-0583-4759-a9b8-c534e6763391",
  "resourceType": "patient",
  "version": 1,
  "payload": {/* the resource payload, same shape as a change event's "record" */},
  "updatedAt": "2026-07-14T04:32:56.082Z",
  "orgSlug": "default",
  "identifiers": [{ "system": "urn:michels:pid", "value": "1234567" }]
}

payload is the resource-type-specific shape documented in Data types — the same shape embedded as record in change-feed events, so code that already handles change-feed events can reuse the same parsing logic here.

Worked example

1. List a page of patient records with a valid token:

   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
   }

2. The same request with a missing token returns the shared authentication failure shape instead (see Authentication):

   curl "https://sync.example.com/api/v1/records/patient?_limit=2"

   { "code": "unauthorized" }