{ "openapi": "3.1.0", "info": { "title": "Amon Sul public machine API", "version": "1", "description": "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." }, "components": { "securitySchemes": { "BearerKey": { "type": "http", "scheme": "bearer", "description": "Machine API key supplied as Authorization: Bearer ." }, "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Alternative API-key header. If both headers are present, X-API-Key takes precedence." } }, "schemas": {} }, "paths": { "/api/public/v1/association/entity-counts": { "get": { "operationId": "getAssociationEntityCounts", "summary": "Count associated entities", "tags": [ "Machine API" ], "description": "Count entities owned by the authenticated integration association within its lane, grouped by entity type. Associations with no entities return an empty counts array.", "responses": { "200": { "description": "Association identity and counts by entity type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "associationId": { "type": "string" }, "counts": { "type": "array", "items": { "type": "object", "properties": { "entityType": { "type": "string" }, "count": { "type": "number" } }, "required": [ "entityType", "count" ] } } }, "required": [ "associationId", "counts" ], "description": "Association identity and counts by entity type." } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Authentication failed." } } } }, "403": { "description": "Lane or scope refused.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Lane or scope refused." } } } }, "404": { "description": "The API key has no integration association.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "The API key has no integration association." } } } }, "429": { "description": "Rate limit exceeded; inspect response headers.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Rate limit exceeded; inspect response headers." } } } } }, "x-required-scope": "read_entities", "x-schema-source": "Authored from TypeScript return shape; not runtime validation" } }, "/api/public/v1/enqueue": { "post": { "operationId": "enqueueSequence", "summary": "Admit a sequence", "tags": [ "Machine API" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_id": { "type": "string" }, "external_id": { "type": "string" }, "entity_type": { "type": "string" }, "sequence_id": { "type": "string" }, "sequence_code": { "type": "string" }, "starting_parameters": { "type": "object", "additionalProperties": true }, "executed_by": { "type": "string" } }, "required": [ "entity_type" ] }, "examples": { "invoice": { "summary": "Admit offered invoice work", "value": { "external_id": "INV-001", "entity_type": "invoice", "sequence_id": "00000000-0000-4000-8000-000000000001", "starting_parameters": { "invoice_number": "INV-001" } } } } } } }, "responses": { "202": { "description": "Sequence admission accepted; execution has not necessarily completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "entity_id": { "type": "string" }, "external_id": { "type": "string" }, "sequence_id": { "type": "string" }, "sequence_code": { "type": "string" }, "tenant_id": { "type": "string" }, "run_id": { "type": "string" } }, "required": [ "success", "message", "entity_id", "external_id", "sequence_id", "sequence_code", "tenant_id" ], "description": "Sequence admission accepted; execution has not necessarily completed." } } } }, "400": { "description": "Missing selector or invalid UUID.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "description": "Missing selector or invalid UUID." } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Authentication failed." } } } }, "403": { "description": "Scope or admission refused.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "description": "Scope or admission refused." } } } }, "404": { "description": "Entity or permitted sequence not found.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "description": "Entity or permitted sequence not found." } } } }, "409": { "description": "Conflicting execution ownership or context.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "description": "Conflicting execution ownership or context." } } } }, "422": { "description": "Sequence input or policy validation failed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "description": "Sequence input or policy validation failed." } } } }, "429": { "description": "Rate limit exceeded; inspect response headers.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Rate limit exceeded; inspect response headers." } } } }, "500": { "description": "Unexpected admission error; inspect evidence before retrying.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "description": "Unexpected admission error; inspect evidence before retrying." } } } } }, "x-required-scope": "enqueue", "x-schema-source": "Fastify route schema", "x-runtime-constraints": [ "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." ] } }, "/api/public/v1/entities": { "post": { "operationId": "registerEntity", "summary": "Register an entity", "tags": [ "Machine API" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": "string" }, "entity_type": { "type": "string" }, "initial_status_code": { "type": "string" }, "initial_status_codes": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1 } }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "registration_context": { "type": "object", "additionalProperties": true } }, "required": [ "external_id", "entity_type" ] }, "examples": { "invoice": { "summary": "Register an invoice", "value": { "external_id": "INV-001", "entity_type": "invoice", "description": "Invoice awaiting review", "metadata": { "sourceRecordId": "INV-001" } } } } } } }, "responses": { "201": { "description": "Entity registered with its policy context.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "entity_id": { "type": "string" }, "external_id": { "type": "string" }, "entity_type": { "type": "string" }, "status": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "matrix": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "matrix_id": { "type": "string" }, "matrix_code": { "type": "string" }, "version": { "type": "number" }, "current_status": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "available_sequences": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "required": [ "success", "entity_id", "external_id", "entity_type", "status", "matrix" ], "description": "Entity registered with its policy context." } } } }, "400": { "description": "Invalid registration request.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Invalid registration request." } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Authentication failed." } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "409": { "description": "Entity is already registered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "description": "Entity is already registered." } } } }, "422": { "description": "Invalid policy or initial status context.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "description": "Invalid policy or initial status context." } } } }, "429": { "description": "Rate limit exceeded; inspect response headers.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Rate limit exceeded; inspect response headers." } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "x-required-scope": "enqueue", "x-schema-source": "Fastify route schema", "x-runtime-constraints": [ "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." ] } }, "/api/public/v1/entities/batch": { "post": { "operationId": "registerEntitiesBatch", "summary": "Register entities in a batch", "tags": [ "Machine API" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "external_id": { "type": "string" }, "entity_type": { "type": "string" }, "initial_status_code": { "type": "string" }, "initial_status_codes": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1 } }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "registration_context": { "type": "object", "additionalProperties": true } }, "required": [ "external_id", "entity_type" ] } } }, "required": [ "entities" ], "additionalProperties": false }, "examples": { "invoices": { "summary": "Register two invoices", "value": { "entities": [ { "external_id": "INV-001", "entity_type": "invoice", "description": "Invoice awaiting review" }, { "external_id": "INV-002", "entity_type": "invoice", "description": "Invoice awaiting review" } ] } } } } } }, "responses": { "200": { "description": "One result per row, in request order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "observed_at": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "integer" }, "body": { "type": "object", "additionalProperties": true } }, "required": [ "status", "body" ] } } }, "required": [ "observed_at", "results" ], "description": "One result per row, in request order." } } } }, "400": { "description": "Invalid registration request.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Invalid registration request." } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Authentication failed." } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "429": { "description": "Rate limit exceeded; inspect response headers.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Rate limit exceeded; inspect response headers." } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "x-required-scope": "enqueue", "x-schema-source": "Fastify route schema", "x-runtime-constraints": [ "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." ] } }, "/api/public/v1/entities/{identifier}": { "get": { "operationId": "getEntity", "summary": "Read entity and offered work", "tags": [ "Machine API" ], "description": "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.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "entity_type", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "identifier", "required": true } ], "responses": { "200": { "description": "Entity identity, policy state and offered sequences.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_id": { "type": "string" }, "external_id": { "type": "string" }, "entity_type": { "type": "string" }, "current_status": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "available_sequences": { "type": "array", "items": { "type": "object", "properties": { "sequence_id": { "type": "string" }, "sequence_code": { "type": "string" }, "sequence_name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "input_contract": { "type": "object", "properties": { "$schema": { "enum": [ "https://json-schema.org/draft/2020-12/schema" ] }, "type": { "enum": [ "object" ] }, "properties": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } }, "required": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "enum": [ false ] } }, "required": [ "$schema", "type", "properties", "required", "additionalProperties" ], "additionalProperties": false }, "role": { "type": "string" }, "matrix_id": { "type": "string" }, "matrix_code": { "type": "string" }, "matrix_version": { "type": "number" }, "preserves_status": { "type": "boolean" }, "available": { "type": "boolean" }, "blocked_reason": { "type": [ "null", "string" ] } }, "required": [ "sequence_id", "sequence_code", "sequence_name", "description", "input_contract", "role", "matrix_id", "matrix_code", "matrix_version", "preserves_status", "available", "blocked_reason" ] } }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "matrix_id": { "type": "string" }, "matrix_code": { "type": "string" }, "version": { "type": "number" }, "current_status": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "available_sequences": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "workflow_state": { "type": "object", "additionalProperties": false, "properties": { "observed_at": { "type": "string", "format": "date-time" }, "processing": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "run_id": { "type": "string" }, "sequence_code": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" } }, "required": [ "run_id", "sequence_code", "started_at" ] }, { "type": "null" } ] }, "latest_terminal_event": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "observed_at", "processing", "latest_terminal_event" ] } }, "required": [ "entity_id", "external_id", "entity_type", "current_status", "available_sequences" ], "description": "Entity identity, policy state and offered sequences." } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Authentication failed." } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "404": { "description": "Entity not found in the authenticated context.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "description": "Entity not found in the authenticated context." } } } }, "429": { "description": "Rate limit exceeded; inspect response headers.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Rate limit exceeded; inspect response headers." } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "x-required-scope": "read_entities", "x-schema-source": "Fastify route schema", "x-runtime-constraints": [ "External identifiers require entity_type. Entity lookup is lane, type and association scoped." ] } }, "/api/public/v1/entities/{identifier}/history": { "get": { "operationId": "getEntityHistory", "summary": "Read execution history", "tags": [ "Machine API" ], "description": "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.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "entity_type", "required": false }, { "schema": { "type": "number", "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "number", "default": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "identifier", "required": true } ], "responses": { "200": { "description": "History records and pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_id": { "type": "string" }, "external_id": { "type": "string" }, "entity_type": { "type": "string" }, "current_status": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sequence_code": { "type": [ "null", "string" ] }, "action_code": { "type": [ "null", "string" ] }, "action_name": { "type": [ "null", "string" ] }, "action_type": { "type": [ "null", "string" ] }, "execution_status": { "type": "string" }, "severity": { "type": "string" }, "message": { "type": [ "null", "string" ] }, "executed_by": { "type": [ "null", "string" ] }, "executed_at": { "type": "string" }, "execution_time_ms": { "type": [ "null", "number" ] } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" } } } }, "required": [ "entity_id", "external_id", "entity_type", "current_status", "history", "pagination" ], "description": "History records and pagination." } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Authentication failed." } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "404": { "description": "Entity not found in the authenticated context.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "description": "Entity not found in the authenticated context." } } } }, "429": { "description": "Rate limit exceeded; inspect response headers.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Rate limit exceeded; inspect response headers." } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "x-required-scope": "read_entities", "x-schema-source": "Fastify route schema", "x-runtime-constraints": [ "External identifiers require entity_type. Entity lookup is lane, type and association scoped." ] } }, "/api/public/v1/entity-types/{entityType}/statuses": { "get": { "operationId": "getEntityTypeStatuses", "summary": "Read permitted entity statuses", "tags": [ "Machine API" ], "description": "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.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "entityType", "required": true } ], "responses": { "200": { "description": "Entity type and permitted tracks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entityType": { "type": "string", "minLength": 1 }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "roleSlug": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "roleName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "matrixCode": { "type": "string", "minLength": 1 }, "matrixVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "statuses": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isInitial": { "type": "boolean" }, "isTerminal": { "type": "boolean" } }, "required": [ "code", "name", "description", "isInitial", "isTerminal" ], "additionalProperties": false } }, "statusCodes": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "roleSlug", "roleName", "matrixCode", "matrixVersion", "statuses", "statusCodes" ], "additionalProperties": false } } }, "required": [ "entityType", "tracks" ], "additionalProperties": false, "description": "Entity type and permitted tracks." } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Authentication failed." } } } }, "403": { "description": "Scope or authenticated context refused.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Scope or authenticated context refused." } } } }, "404": { "description": "Entity type does not exist in the authenticated lane.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Entity type does not exist in the authenticated lane." } } } }, "429": { "description": "Rate limit exceeded; inspect response headers.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Rate limit exceeded; inspect response headers." } } } } }, "x-required-scope": "read_entities", "x-schema-source": "Zod EntityTypeStatusesResponseSchema; refinements described in prose" } } }, "security": [ { "BearerKey": [] }, { "ApiKey": [] } ] }