API reference

All responses are JSON. Errors use RFC 7807 Problem Details. Read endpoints require a per-tenant JWT (Authorization: Bearer …, verified via JWKS); ingest uses endpoint HMAC instead.

Health

GET /healthz — liveness.
GET /readyz — readiness (DB reachable).

`GET /v1/contract`

The version/schema lattice consumers floor-pin:

{
  "contract_name": "atlas",
  "version": "x.y.z",
  "deployment_mode": "saas",
  "canonical_schema_version": "…",
  "envelope_schema_version": "…",
  "canonical_entities": ["customer", "order", "job", "estimate", "…"],
  "envelope_dialects": ["synergy_sha256", "…"]
}

See Contract.

`GET /v1/entities/{type}`

Paginated canonical entity list. Query: limit (≤ 200), offset.

{ "rows": [ { /* entity */ } ], "limit": 50, "offset": 0 }

`GET /v1/entities/{type}/{id}`

One canonical entity by id. Returns the entity object.

`GET /v1/entities/{type}/{id}/cross-references`

The cross-system “where is this” view — references, per-field provenance, and open drift. See Data model.

{ "references": [ … ], "provenance": [ … ], "openDrift": [ … ] }

`POST /v1/mappings/dry-run`

Preview a mapping without persisting. Body: { document, mapping_id } or { document, spec } (exactly one of mapping_id / spec). Returns { ok, output }. See Mapping.

`GET /v1/adapters`

The connector capability surface — one manifest per adapter, with each entity’s read/write lane. See Connectors.

`POST /v1/ingest/{endpoint_id}`

Deliver a source event/envelope. Authenticated by endpoint HMAC (X-Synergy-Signature: sha256=<hex>), not the JWT. Returns { envelope_id, duplicate }; 202 for a new delivery, 200 for an idempotent replay. See Ingest.

`POST /v1/write-back`

Push a canonical entity out to a source system.

// body — supply entity_id (stored) or canonical (caller-built)
{ "system": "tharstern", "entity_type": "order", "entity_id": "ord_…" }

// 200 OK
{
  "system": "tharstern",
  "entity_type": "order",
  "external_id": "T-10293",
  "created": true,        // true = create, false = update-in-place
  "lane": "green"         // the write-lane the push ran on
}

Atlas gates the push on the connector’s write-lane: green pushes; amber needs the connection’s writes_enabled; red/unknown is refused (409). The external id is recorded so a later push updates in place.