API reference

Caller-owned entity registration, entity-type discovery and sequence admission. The API key supplies tenant, lane and integration association. HTTP 202 describes admission, not completed execution. Schemas cover transport shapes; handler checks and Zod refinements are described per operation. Browser, pairing, health and management interfaces are outside this public-v1 reference.

Generated from the registered public-v1 routes and their schemas. Edit source contracts and operation descriptions, then regenerate; do not edit this page directly.

Download the OpenAPI specification for the complete nested transport shapes. Use the machine API guide for the registration-to-execution flow.

Authentication and interpretation

Use your administrator-provided HTTPS API origin. Send Authorization: Bearer <api-key> or X-API-Key: <api-key>; the latter takes precedence if both are supplied. The key supplies tenant, lane and integration association. Request fields cannot change that identity.

Scope checks, policy bindings, input-contract validation and execution ownership are runtime checks. JSON schemas do not express all of them. Framework authentication, rate-limit and validation errors can have different shapes from handler errors. HTTP 202 does not mean work has completed.

Enqueue and entity routes configure standard/premium/enterprise limits of 300/1000/5000 requests per minute per key, with an IP fallback. entity-types/{entityType}/statuses and association/entity-counts fall under the platform’s blanket limit of 1,000 requests per minute per client IP.

Count associated entities

GET /api/public/v1/association/entity-counts — required scope: read_entities

Count entities owned by the authenticated integration association within its lane, grouped by entity type. Associations with no entities return an empty counts array.

Schema source: Authored from TypeScript return shape; not runtime validation.

Responses

Status	Meaning
200	Association identity and counts by entity type.
401	Authentication failed.
403	Lane or scope refused.
404	The API key has no integration association.
429	Rate limit exceeded; inspect response headers.

Successful response fields:

Field	Type	Required	Default
associationId	string	yes
counts	array	yes

Admit a sequence

POST /api/public/v1/enqueue — required scope: enqueue

Start offered work for a registered entity under its pinned policy. HTTP 202 means admission was accepted; it does not mean the sequence or external effects have completed. Use the concrete sequence_id offered by the entity response. executed_by is an audit label; the key remains the authenticated caller.

Schema source: Fastify route schema.

• Supply entity_id or external_id, plus sequence_id or sequence_code. UUID selectors must have valid UUID v4 format.
• Sequence selection, policy availability, input contracts, execution ownership and association/lane context are validated by the handler.
• After an uncertain response, inspect execution evidence before retrying; no blanket idempotency guarantee is made.

Request body

Field	Type	Required	Default
entity_id	string	no
external_id	string	no
entity_type	string	yes
sequence_id	string	no
sequence_code	string	no
starting_parameters	object	no
executed_by	string	no

Admit offered invoice work

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

Responses

Status	Meaning
202	Sequence admission accepted; execution has not necessarily completed.
400	Missing selector or invalid UUID.
401	Authentication failed.
403	Scope or admission refused.
404	Entity or permitted sequence not found.
409	Conflicting execution ownership or context.
422	Sequence input or policy validation failed.
429	Rate limit exceeded; inspect response headers.
500	Unexpected admission error; inspect evidence before retrying.

Successful response fields:

Field	Type	Required	Default
success	boolean	yes
message	string	yes
entity_id	string	yes
external_id	string	yes
sequence_id	string	yes
sequence_code	string	yes
tenant_id	string	yes
run_id	string	no

Register an entity

POST /api/public/v1/entities — required scope: enqueue

Register a caller-owned external entity under the authenticated lane and integration association. Published policy bindings determine its matrix or composite tracks. Initial status selection must be valid for the bound policy. registration_context records evidence and does not confer access.

Schema source: Fastify route schema.

• The external identifier is scoped to entity type, lane and integration association.
• Initial status codes are checked against the bound policy. Composite role selection and status validation occur in the handler.

Request body

Field	Type	Required	Default
external_id	string	yes
entity_type	string	yes
initial_status_code	string	no
initial_status_codes	object	no
description	string	no
metadata	object	no
registration_context	object	no

Register an invoice

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

Responses

Status	Meaning
201	Entity registered with its policy context.
400	Invalid registration request.
401	Authentication failed.
403	Default Response
409	Entity is already registered.
422	Invalid policy or initial status context.
429	Rate limit exceeded; inspect response headers.
500	Default Response

Successful response fields:

Field	Type	Required	Default
success	boolean	yes
entity_id	string	yes
external_id	string	yes
entity_type	string	yes
status	object	yes
matrix	object	yes
tracks	array	no

Register entities in a batch

POST /api/public/v1/entities/batch — required scope: enqueue

Register up to 500 caller-owned entities in one call. Each row is a POST /entities body and is judged on its own. The answer lists one { status, body } per row, in request order: 201 with the registered entity, 409 when it is already registered, or 422 for an invalid policy or initial status context. A 422 row leaves nothing behind. Anything unexpected rolls back the whole batch with 500.

Schema source: Fastify route schema.

• Each row follows the POST /entities rules; a row’s status is 201, 409 or 422.
• The batch is one request against the registration rate limit.

Request body

Field	Type	Required	Default
entities	array	yes

entities holds 1-500 registration bodies, each with the fields of Register an entity.

Register two invoices

{
  "entities": [
    {
      "external_id": "INV-001",
      "entity_type": "invoice",
      "description": "Invoice awaiting review"
    },
    {
      "external_id": "INV-002",
      "entity_type": "invoice",
      "description": "Invoice awaiting review"
    }
  ]
}

Responses

Status	Meaning
200	One result per row, in request order.
400	Invalid registration request.
401	Authentication failed.
403	Default Response
429	Rate limit exceeded; inspect response headers.
500	Default Response

Successful response fields:

Field	Type	Required	Default
observed_at	string	yes
results	array	yes

Read entity and offered work

GET /api/public/v1/entities/{identifier} — required scope: read_entities

Use the internal entity UUID, or an external identifier with entity_type. Reads preserve key lane and association ownership. Choose an available concrete sequence_id from the offered sequences; sequence codes can be ambiguous across tracks.

Schema source: Fastify route schema.

• External identifiers require entity_type. Entity lookup is lane, type and association scoped.

Parameters

Name	Location	Required	Type / default
entity_type	query	no	string
identifier	path	yes	string

Responses

Status	Meaning
200	Entity identity, policy state and offered sequences.
400	Default Response
401	Authentication failed.
403	Default Response
404	Entity not found in the authenticated context.
429	Rate limit exceeded; inspect response headers.
500	Default Response

Successful response fields:

Field	Type	Required	Default
entity_id	string	yes
external_id	string	yes
entity_type	string	yes
current_status	object	yes
available_sequences	array	yes
tracks	array	no
workflow_state	object	no

Read execution history

GET /api/public/v1/entities/{identifier}/history — required scope: read_entities

Read paginated action execution history for a permitted entity. Use entity_type with an external identifier. History defaults to limit 50 and offset 0. This endpoint describes recorded evidence and does not authorize execution.

Schema source: Fastify route schema.

• External identifiers require entity_type. Entity lookup is lane, type and association scoped.

Parameters

Name	Location	Required	Type / default
entity_type	query	no	string
limit	query	no	number / 50
offset	query	no	number / 0
identifier	path	yes	string

Responses

Status	Meaning
200	History records and pagination.
400	Default Response
401	Authentication failed.
403	Default Response
404	Entity not found in the authenticated context.
429	Rate limit exceeded; inspect response headers.
500	Default Response

Successful response fields:

Field	Type	Required	Default
entity_id	string	yes
external_id	string	yes
entity_type	string	yes
current_status	object	yes
history	array	yes
pagination	object	yes

Read permitted entity statuses

GET /api/public/v1/entity-types/{entityType}/statuses — required scope: read_entities

Read the exact entity type and its lane-resolved track/status catalog. Existing types without a binding can return an empty tracks array. Track statusCodes must mirror statuses in order.

Schema source: Zod EntityTypeStatusesResponseSchema; refinements described in prose.

Parameters

Name	Location	Required	Type / default
entityType	path	yes	string

Responses

Status	Meaning
200	Entity type and permitted tracks.
401	Authentication failed.
403	Scope or authenticated context refused.
404	Entity type does not exist in the authenticated lane.
429	Rate limit exceeded; inspect response headers.

Successful response fields:

Field	Type	Required	Default
entityType	string	yes
tracks	array	yes