Machine API

Use your administrator-provided HTTPS origin with /api/public/v1. These routes register caller-owned entities and admit configured work. Browser and managed-pairing APIs have separate authentication and are outside this reference.

See the generated API reference for payload fields, response shapes and the downloadable OpenAPI specification.

Machine authentication and scope

Send Authorization: Bearer <api-key>. The authenticated key supplies the tenant, lane, and managed integration association. A body field or browser lane switch cannot change that context. A key must have each route’s required scope. Production and test key classifications must agree with their stored lane.

Method and path below /api/public/v1	Scope	Purpose
GET /entity-types/:entityType/statuses	read_entities	Exact entity type’s permitted status catalog
GET /association/entity-counts	read_entities	Counts for the authenticated association in its lane
POST /entities	enqueue	Register an external entity under the lane binding
POST /entities/batch	enqueue	Register up to 500 entities in one call
GET /entities/:identifier	read_entities	Entity status/tracks, policy context, and available sequences
GET /entities/:identifier/history	read_entities	Paginated execution history
POST /enqueue	enqueue	Admit a sequence for a registered entity

Send POST /entities/batch a body of { "entities": [ … ] } holding 1-500 registration bodies. The answer is 200 with observed_at and one { status, body } per row, in order. A row is 201, 409 or 422 on its own; anything unexpected rolls back the whole batch with 500. The batch counts as one request against the rate limit.

GET /health sits at the service root, outside that route group. A health probe does not establish that a specific policy, tenant, or external destination works.

Register an entity

First read the entity type’s statuses and tracks with GET /entity-types/:entityType/statuses and confirm the entity type has the expected published binding in the key’s lane. Registration requires external_id and entity_type:

{
  "external_id": "INV-001",
  "entity_type": "invoice",
  "description": "Invoice awaiting review",
  "metadata": { "sourceRecordId": "INV-001" }
}

Optional initial_status_code or composite initial_status_codes select valid initial context; they are validated against the bound policy. Optional registration_context records caller-supplied registration evidence. It does not confer permissions or change authenticated provenance.

A successful registration returns HTTP 201 with entity_id, external identity, status, and policy information; composite registration also exposes tracks. An existing registration returns 409. Missing or invalid policy/status context returns a validation error rather than inventing a workflow.

Read offered work

Use the returned UUID as :identifier, or an external identifier with the entity_type query parameter. The entity response describes available sequences, including sequence_id, sequence_code, input contract, matrix/version context, role, available, and blocked_reason.

Choose the offered concrete sequence_id. A sequence code is a compatibility selector and may be ambiguous across composite tracks. A blocked sequence needs its prerequisite resolved; its displayed name is not an execution credential.

History uses /history, with entity_type where needed and limit / offset (defaults 50 / 0). Its response includes history and pagination. There is no /entities/:id/logs endpoint in this route registration.

Start a sequence

{
  "external_id": "INV-001",
  "entity_type": "invoice",
  "sequence_id": "00000000-0000-4000-8000-000000000001",
  "starting_parameters": { "invoice_number": "INV-001" }
}

Replace the UUID and parameters with those offered by the entity response. Supply entity_id or external_id, and sequence_id or sequence_code. starting_parameters contains the sequence-start input object. The entity’s pinned policy supplies the matrix; enqueue does not take action_matrix_code. Optional executed_by is an audit label; the authenticated key remains recorded.

HTTP 202 means admission was accepted. The response contains success, message, entity identity, concrete sequence identity, tenant_id, and run_id. It does not mean the sequence or its external effects have completed.

Status	Enqueue interpretation
400	Missing identifier/selector or invalid UUID
403	Scope or admission refused
404	Entity or permitted sequence not found in the authenticated context
409	Conflicting execution ownership or context
422	Sequence input or policy validation failed
429	Rate limit exceeded
500	Unexpected admission error; inspect evidence before repeating

Errors use a string error and may contain details, validation fields, or a lane rejection code. Framework authentication and validation errors may have their own shape. Do not assume every error is { error: { code, message } }.

Enqueue and entity routes configure per-key limits of 300, 1000, or 5000 requests per minute for standard, premium, or enterprise keys, with an IP fallback when key context is absent. The catalog, status and count routes fall under the platform’s blanket limit of 1,000 requests per minute per client IP.

Continue with the integration guide. Examples were checked against request schemas; they were not sent to a live API during this documentation review.