API Reference

A thin API that turns decisions into portable records, then publishes into HRIS, ATS, VMS, ERP, CLM and source-to-pay systems via adapters.

Core endpoints Authentication Platform metadata Operations OpenAPI 3.1 (JSON)

The machine-readable contract is generated from the same registry as this page, so the two cannot disagree. It is self-contained (every schema embedded, no remote references), so it loads straight into Postman or a client generator. The reference sandbox implements it exactly; the production service is in build. A conformance pack runs the contract's fourteen claims against any deployment URL; the sandbox passes it in CI.

Authentication

Client credentials, scoped tokens

Every request carries Authorization: Bearer <token>. Production clients get the token from the OAuth 2.0 client-credentials grant; it lives an hour and carries only the scopes the client was granted. Personal sandbox keys from developer access are accepted as bearer tokens too and carry every scope. Destination credentials are never sent by the caller: they are held per tenant and injected by the adapter.

Method	Path	Summary	Request	Response
POST	/oauth/token	Exchange client credentials for a short-lived, scoped bearer token.	TokenRequest	TokenResponse

Get a token

POST /v1/oauth/token Authorization: Basic base64(client_id:client_secret) Content-Type: application/x-www-form-urlencoded grant_type=client_credentials &scope=intents:write publish 200 { "access_token": "...", "token_type": "Bearer", "expires_in": 3600, "scope": "intents:write publish" }

Errors

401 Missing, invalid or expired token: request a new one. The token endpoint answers invalid_client for a wrong id or secret.

403 insufficient_scope: the token lacks the scope the route needs; the response names it.

400 unsupported_grant_type or invalid_scope at the token endpoint (RFC 6749 section 5.2).

Scopes

Scope	Routes it unlocks
intents:read	GET /intent/{intent_id}, GET /intent/{intent_id}/timeline
intents:write	POST /intent, PATCH /intent/{intent_id}, POST /plan, POST /preflight, POST /enrichment-request
publish	POST /publish
reconcile	POST /reconcile
passthrough	POST /passthrough
destinations:read	GET /platforms, GET /destinations, GET /destinations/{id}/capabilities

Core

Intent → Plan → Preflight → Publish

Method	Path	Summary	Request	Response
POST	/intent	Create an intent record (returns intent_id).	IntentCreateRequest	IntentRecord
PATCH	/intent/{intent_id}	Patch diagnostics/routing/admin fields.	IntentPatchRequest	IntentRecord
POST	/plan	Apply Channel Map to determine target destination(s).	PlanGenerateRequest	PlanGenerateResponse
POST	/preflight	Validate required fields and transforms; returns enrichment gaps.	PreflightRequest	PreflightResponse
POST	/publish	Idempotent publish via adapter; records external IDs.	PublishRequest	PublishResponse

Example flow (pseudo) expand

POST /intent → { intent_id } PATCH /intent/{intent_id} → attach diagnostics/routing/admin POST /plan → select destination(s) via Channel Map POST /preflight → missing_fields[] (if any) POST /publish → external_id + receipts

Method	Path	Purpose
GET	/platforms	List platforms and doc availability.
GET	/destinations	List connected tenants (“linked accounts”).
GET	/destinations/{id}/capabilities	Capability matrix + required fields per object/op.

Passthrough

Use when a platform field/endpoint isn’t in the canonical model. Still anchors the call to the Intent ID and timeline.

POST /passthrough

Reconciliation

Detect drift when humans change the destination system directly. Produces a report and can trigger follow-up actions.

POST /reconcile

Webhooks (back-sync)

Update intent state when a destination object changes (cancelled, updated rate, status changed).

POST /webhooks/{platform}

Enrichment loop

If preflight fails due to missing platform-required fields, emit an enrichment request back to Triage/Intake.

POST /enrichment-request