{ "openapi": "3.1.0", "info": { "title": "AgenticRail Public API", "version": "1.2.7", "summary": "Deterministic sequence enforcement for AI agents. ALLOW / DENY / HALT, with a signed receipt for every decision.", "description": "AgenticRail is a pre-execution enforcement layer. An agent calls `POST /v1/evaluate` BEFORE it runs each step of a sequence; the gate returns `ALLOW` or `DENY` and seals an Ed25519-signed receipt of that decision. It enforces strict step order, replay protection (nonce + timestamp freshness), and sequence sealing at the final step. A sequence is only finished, and its record only complete, once the final step of its declared order is ALLOWED: that call returns `sealed: true`, the sequence closes to any further step, and its report reads `SEALED`. Until then the record can only say what happened so far, so run every sequence to its last declared step.\n\nWhat it is not: AgenticRail does not run your step for you, and an `ALLOW` does not assert that the downstream action succeeded. It is an enforcement layer, not an execution runtime.\n\nEvidence design: receipts are Ed25519-signed over the canonical JSON of the receipt with the `signature` field removed. The durable report ships the raw signature alongside the exact `signed_canonical` preimage, so any third party can run `ed25519_verify(pubkey, signed_canonical, signature)` offline with no callback to AgenticRail. Public keys are published at https://agenticrail.nz/spec/receipt-public-keys.json\n\nTimestamps: `ts_ms` is supplied by the caller (or, if omitted, taken from the gate's clock) and covered by the signature, so it cannot be altered after signing without breaking verification. The gate refuses any timestamp more than 300 seconds from its own clock (STALE_TIMESTAMP), so the asserted time is bounded. It is not an independently attested time — no RFC 3161 token is issued. A receipt is a record of when AgenticRail observed a step, not proof of when it occurred.", "termsOfService": "https://agenticrail.nz/api-terms/", "contact": { "name": "AgenticRail (TUARA KURI LIMITED)", "email": "hello@agenticrail.nz", "url": "https://agenticrail.nz/docs/" }, "license": { "name": "Method may be freely implemented. Text (c) 2026 TUARA KURI LIMITED.", "url": "https://agenticrail.nz/api-terms/" } }, "externalDocs": { "description": "Developer documentation and the enforcement specification", "url": "https://agenticrail.nz/docs/" }, "servers": [ { "url": "https://api.agenticrail.nz", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "enforcement", "description": "Pre-execution gate decisions" }, { "name": "evidence", "description": "Verifiable records of what was enforced" }, { "name": "operational", "description": "Health and latency helpers" } ], "paths": { "/v1/evaluate": { "post": { "operationId": "evaluateStep", "tags": [ "enforcement" ], "summary": "Evaluate one agent step before it runs", "description": "Call this BEFORE executing a step. If the response is `DENY`, do not run the step.\n\nChecks run in two phases. **Phase 1, evaluated together (several can be reported at once):** timestamp more than 300 seconds from the gate's clock (`STALE_TIMESTAMP`), `step` not equal to `function` (`FUNCTION_STEP_MISMATCH`), action type not permitted for the step (`ACTION_NOT_ALLOWED`), and a `RECORD_RESULT` at `boundary` whose `attestation.witnessed_pack_id` does not bind to the last allowed receipt (`ARTIFACT_UNBOUND`). **Phase 2, only if phase 1 found nothing:** step not in the sequence's declared step order (`UNKNOWN_STEP`), then sequence already sealed (`SEALED_SEQUENCE`), a `step_order` different from the one the sequence was locked to on its first call (`STEP_ORDER_MISMATCH`), nonce reused (`REPLAY_NONCE`), step out of order (`SEQUENCE_VIOLATION`). Otherwise `ALLOW`.\n\nBecause phase 1 runs first, a wrong `action_type` is reported as `ACTION_NOT_ALLOWED` even when the step would also be unknown or out of order. Every DENY carries what would have worked (see the response schema).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluateRequest" }, "example": { "sequence_id": "order-4471", "step": "intake", "function": "intake", "action_type": "CHECK_STATE", "action": "receive_customer_request", "inputs": { "signal": "new order" }, "nonce": "6f1c9a2e-6b4d-4a17-9a7e-0f2b1d3c4e5a", "ts_ms": 1785487358119 } } } }, "responses": { "200": { "description": "A decision was reached. Without `deny_status`, this is returned for both ALLOW and DENY — read the `decision` field, not the HTTP status. With `deny_status=409`, only ALLOW returns 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluateResponse" } } } }, "409": { "description": "Returned only when the request carried `deny_status=409` and the decision was not ALLOW. The body is the same EvaluateResponse a 200 would have carried, with its signed receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "deny_status", "in": "query", "required": false, "description": "Optional. Set to `409` to receive HTTP 409 on any non-ALLOW decision instead of 200. For callers that only read the HTTP status -- shell scripts with `curl --fail`, schedulers, CI steps, no-code webhook steps -- which would otherwise read a DENY as success and run the next step. The response body, receipt and signature are identical either way; only the status changes. Any other value is refused with 400. Omit it and behaviour is unchanged (the SDKs and the MCP server read `decision` and do not send it).", "schema": { "type": "string", "enum": [ "409" ] } } ] } }, "/v1/report": { "post": { "operationId": "getReport", "tags": [ "evidence" ], "summary": "Generate the verifiable enforcement report for a sequence", "description": "Returns the durable evidence for a sequence: every enforcement decision, each receipt's raw `signature` and the exact `signed_canonical` preimage it was computed over, the `prev_receipt_hash` chain verdict, and an independent-archive comparison.\n\nThis is the surface that supports offline verification. The synchronous `/v1/evaluate` response deliberately carries signature metadata only; the raw signature surfaces here.\n\nA human-readable version of the same evidence is at https://report.agenticrail.nz/report", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRequest" }, "example": { "sequence_id": "order-4471", "format": "json" } } } }, "responses": { "200": { "description": "The enforcement report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [] }, {} ] } }, "/v1/warm": { "post": { "operationId": "warmSequence", "tags": [ "operational" ], "summary": "Pre-warm a sequence's enforcement state", "description": "Advisory only. Reduces cold-start latency on the first evaluate for a sequence. Always returns 200 and never blocks or affects an enforcement decision. Measured benefit in isolation is modest (~9%).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sequence_id" ], "properties": { "sequence_id": { "type": "string" }, "model_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Always returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } } }, "example": { "ok": true } } } } }, "security": [ { "bearerAuth": [] }, {} ] } }, "/v1/health": { "get": { "operationId": "health", "tags": [ "operational" ], "summary": "Liveness check", "security": [], "responses": { "200": { "description": "Service is up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" }, "now": { "type": "integer", "description": "Server time, epoch milliseconds." } } }, "example": { "ok": true, "service": "agenticrail-wrapper", "now": 1785487362545 } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "`Authorization: Bearer `. Optional.\n\nAn UNRECOGNISED identity is served on the public demo lane rather than refused: no header at all, a string that cannot be a key, or a well-formed prefix that was never issued. The call runs, the receipt is real, and the response carries `lane`, `lane_reason` and `lane_notice` saying so.\n\nA KNOWN identity presented wrongly is still refused: a wrong secret on a real prefix returns 401, and a revoked key returns 403.\n\nThe public demo key `DEMO-AGENTICRAIL-PUBLIC-2026` is real, rate-limited to 300 requests per minute, and forces every `sequence_id` to carry a `demo-` prefix. Sequences on the demo lane are readable by anyone holding the sequence id, so do not put anything private in `attestation`." } }, "schemas": { "EvaluateRequest": { "type": "object", "required": [ "sequence_id", "step", "action_type" ], "properties": { "sequence_id": { "type": "string", "description": "Stable identifier for this run. All steps of one sequence share it." }, "step": { "type": "string", "description": "The step being attempted. Must equal `function`." }, "function": { "type": "string", "description": "Optional; defaults to `step`. If sent, must equal `step` (else `FUNCTION_STEP_MISMATCH`)." }, "action_type": { "type": "string", "description": "What kind of action this is. Each function permits a specific set.", "enum": [ "CHECK_STATE", "SELECT_NEXT_STEP", "PAUSE_CYCLE", "RECORD_RESULT" ] }, "action": { "type": "string", "description": "Human-readable label for the action. Recorded, not enforced." }, "inputs": { "type": "object", "description": "Optional step inputs. Screened for prompt-injection patterns before enforcement. NEVER stored in the receipt: the receipt carries only `payload_hash`, a SHA-256 of the whole request. Use `attestation` for anything that must be kept as evidence.", "additionalProperties": true }, "nonce": { "type": "string", "format": "uuid", "description": "Optional; generated by the gate if absent. If sent, unique per step: reuse is refused with `REPLAY_NONCE`." }, "ts_ms": { "type": "integer", "description": "Optional. Caller's timestamp, epoch milliseconds. If sent, refused with `STALE_TIMESTAMP` when more than 300 seconds from server time in either direction. If absent, the gate's own clock is used and the freshness check is skipped." }, "step_order": { "type": "array", "items": { "type": "string" }, "description": "Optional, but send it on every call, identical each time, for your own process. The sequence's declared step order; one step is a valid sequence. It is LOCKED on the sequence's first permitted call (a refused call locks nothing): a different list later is refused `STEP_ORDER_MISMATCH` and the refusal returns `locked_step_order`. Omit to use the default MSMD spine: intake, disruption, instability, state_read, internal_driver, execution, boundary, settle. Not an array, or empty: 400." }, "attestation": { "type": "object", "description": "Required for a `RECORD_RESULT` at the `boundary` step. Binds the recorded result to a specific prior receipt.", "properties": { "witnessed_pack_id": { "type": "string", "description": "Must equal the last ALLOWED, durably-written receipt's `pack_id`, which is then re-fetched and re-checked. Mismatch is refused with `ARTIFACT_UNBOUND`." } } } } }, "EvaluateResponse": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "ALLOW", "DENY" ], "description": "The enforcement decision. `HALT` is a status, not a decision: a halted request is refused at the boundary before enforcement and therefore produces no receipt." }, "lane": { "type": "string", "enum": [ "public-demo" ], "description": "Present ONLY when the caller was moved to the public demo lane because the credential presented was not recognised. Absent on an authenticated call, and absent when the demo key was presented deliberately -- so its presence always means this is not the lane the caller asked for." }, "lane_reason": { "type": "string", "enum": [ "no_key_supplied", "key_format_invalid", "key_not_registered" ], "description": "Why the caller landed on the demo lane." }, "lane_notice": { "type": "string", "description": "Human-readable notice: the sequence is `demo-` prefixed and its report can be read by anyone with the sequence id." }, "execution_submitted": { "type": "boolean", "description": "Whether the executor was handed the step. This is the EXECUTOR outcome and is NOT signed into the receipt. Do not confuse it with the receipt's `executed` field, which means only that the decision was ALLOW." }, "sealed": { "type": "boolean", "enum": [ true ], "description": "Present ONLY on the ALLOW that closes the sequence, i.e. the final step of its declared order. Never sent on a DENY or on an intermediate step, so its absence means the sequence is still open. Once sealed, any further call on the same sequence_id is refused with `SEALED_SEQUENCE`. A sealed sequence is the finished record: it can be read whole from the report, which shows `seal_status: SEALED`." }, "seal_notice": { "type": "string", "description": "Human-readable notice sent with `sealed: true`: the sequence is closed, and where to read its report." }, "pack_id": { "type": "string", "description": "This decision's receipt identifier (sha256)." }, "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/DenialCode" }, "description": "Empty on ALLOW. On DENY, every rule that refused the step; phase-1 checks can report more than one at once." }, "sequence_id": { "type": "string" }, "step": { "type": "string" }, "function": { "type": "string" }, "action_type": { "type": "string" }, "model_id": { "type": "string", "description": "Always `client:`." }, "result": { "type": "object", "description": "Executor outcome detail. `status` is `submitted` on ALLOW, `skipped` on DENY.", "additionalProperties": true }, "receipt": { "$ref": "#/components/schemas/ReceiptMetadata" }, "log": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": [ "string", "null" ] } } }, "allowed_action_types": { "type": "array", "items": { "type": "string" }, "description": "DENY with `ACTION_NOT_ALLOWED` only: the action types this step would have accepted. Not signed." }, "next_expected_step": { "type": "string", "description": "DENY with `SEQUENCE_VIOLATION` only: the step the sequence is waiting for. Not signed." }, "locked_step_order": { "type": "array", "items": { "type": "string" }, "description": "DENY with `STEP_ORDER_MISMATCH` only: the order this sequence was locked to on its first call. Resend this list. Not signed." }, "expected_step_order": { "type": "array", "items": { "type": "string" }, "description": "DENY with `UNKNOWN_STEP` only: the step order the step had to appear in. Not signed." }, "step_order_source": { "type": "string", "enum": [ "caller", "msmd_spine" ], "description": "With `expected_step_order`: whether that order was the caller's `step_order` or the built-in MSMD spine (used when `step_order` was absent). Not signed." }, "sequence_scope_notice": { "type": "string", "description": "Present when the sequence was scoped differently from what the caller may expect. Not signed." } } }, "ReceiptMetadata": { "type": "object", "description": "Signature METADATA only. The raw signature is deliberately never echoed here — retrieve it, with its `signed_canonical` preimage, from `POST /v1/report`. Two surfaces on purpose: the synchronous path stays lean, the report is the evidence.", "properties": { "pack_id": { "type": "string" }, "key_id": { "type": "string", "description": "Selects the verification key. Active: `k2_2026-06-07_ed25519`." }, "signature": { "type": "null", "description": "Always null here by design. See the description of this schema." }, "signature_alg": { "type": "string", "enum": [ "Ed25519", "HMAC-SHA256" ] }, "payload_hash": { "type": "string" }, "prev_receipt_id": { "type": [ "string", "null" ], "description": "Anchor: the `pack_id` of the last ALLOWED receipt. Null before the first ALLOW in a sequence, which is legitimate — a denied opening step and the retry after it both carry null. Chain verification resolves predecessors by this anchor, never by position." }, "prev_receipt_hash": { "type": [ "string", "null" ], "description": "sha256 of the predecessor's full canonical JSON, signature included. An identifier reference and a content hash are different things; this is the content hash." }, "decision_index": { "type": [ "integer", "null" ], "minimum": 1, "description": "This decision's position among every decision in the sequence, counted from 1 across ALLOW and DENY alike, and signed into the receipt (added 2026-10-08). The prev_receipt chain runs through ALLOWED receipts only, so nothing links to a DENY; the numbering is what makes a removed receipt of either decision visible as a missing number. Keep it with your own copy of each response and you can name a missing receipt without reading ours. Null if the number could not be reserved." }, "ts_ms": { "type": "integer" }, "version": { "type": "string", "enum": [ "slp8_receipt_v2", "slp8_receipt_v3" ] }, "attestation": { "type": [ "object", "null" ], "additionalProperties": true } } }, "DenialCode": { "type": "string", "description": "Why a step was refused.", "enum": [ "UNKNOWN_STEP", "ACTION_NOT_ALLOWED", "FUNCTION_STEP_MISMATCH", "SEALED_SEQUENCE", "REPLAY_NONCE", "SEQUENCE_VIOLATION", "STALE_TIMESTAMP", "ARTIFACT_UNBOUND", "STEP_ORDER_MISMATCH" ] }, "ReportRequest": { "type": "object", "required": [ "sequence_id" ], "properties": { "sequence_id": { "type": "string" }, "model_id": { "type": "string" }, "format": { "type": "string", "enum": [ "json", "html" ], "default": "json" } } }, "Report": { "type": "object", "properties": { "report_version": { "type": "string" }, "report_hash": { "type": "string" }, "generated_at": { "type": "integer" }, "sequence_id": { "type": "string" }, "model_id": { "type": "string" }, "verification_status": { "type": "string", "enum": [ "VERIFIED_INTACT", "CHAIN_BROKEN", "RECORD_INCOMPLETE", "SIGNATURE_INVALID" ], "description": "Recomputed fresh on every call, never stored. RECORD_INCOMPLETE (added 2026-10-08): every chain link holds but one or more numbered receipts are absent, named in `decision_index.missing`. CHAIN_BROKEN takes precedence over it." }, "seal_status": { "type": "string", "enum": [ "OPEN", "SEALED" ] }, "signatures": { "type": "object", "additionalProperties": true }, "hash_chain": { "type": "object", "additionalProperties": true }, "decision_index": { "type": "object", "description": "Whether the signed decision numbers run unbroken from 1 (added 2026-10-08). `status` is `complete`, `gaps` (with `missing`, and `duplicates` if any), `not_applicable` (the receipts predate the field) or `not_checked` (a partial listing). A missing number is an absent receipt, never written or removed; the report does not say which. Receipts missing after the highest number present cannot be seen by this check.", "additionalProperties": true }, "independent_archive": { "type": "object", "description": "Verdict from comparing against a separate write-once archive bucket held under a different credential. Answers verdict-only and never returns archived bytes. Includes `archived_at`, the storage service's own upload stamp — corroboration, explicitly not a cryptographically attested timestamp.", "additionalProperties": true }, "verification": { "type": "object", "description": "How to verify this report yourself, including the public key reference and the timestamp caveat.", "additionalProperties": true }, "summary": { "type": "object", "additionalProperties": true }, "enforcement_log": { "type": "array", "description": "One entry per decision, each carrying the raw `signature` (base64), the exact `signed_canonical` preimage, `key_id` and `signature_alg`, plus `third_party_verifiable` so an Ed25519 receipt is distinguishable from a legacy server-side-only one. This is a presentation projection: `prev_receipt_id` is not a field here, and `chain_integrity` is the authoritative block for linkage.", "items": { "type": "object", "additionalProperties": true } }, "chain_integrity": { "type": "array", "description": "Authoritative per-receipt linkage verdicts.", "items": { "type": "object", "additionalProperties": true } }, "enforcement_summary": { "type": "string", "description": "Deterministic plain-language summary of the enforcement record, composed from the counts in this document. NO LANGUAGE MODEL IS INVOLVED: the same inputs always produce byte-identical text, so this field reproduces like the rest of the report. It states what the record establishes (the order steps were permitted in, and that the record has not changed since it was written) alongside what it does not (that a permitted step's downstream work ran, or that timestamps are independently attested). Replaced an LLM-written `compliance_narrative` on 2026-08-07." } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } }, "responses": { "BadRequest": { "description": "Refused before evaluation, so no receipt is written: malformed JSON (`invalid_json`); a missing or malformed field (`invalid_request`, with a message naming it: no `sequence_id`, `step` or `action_type`, a `step_order` that is not a non-empty list, a non-numeric `ts_ms`, a keyed `sequence_id` starting `demo-`, an unrecognised `deny_status`); or a payload rejected by input screening (oversized, over-nested, or containing prompt-injection patterns).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_json", "message": "Body is not valid JSON" } } } }, "Unauthorized": { "description": "The credential was RECOGNISED but presented wrongly -- a wrong secret on a real key prefix. An unrecognised credential is not refused; it is served on the public demo lane. A revoked key returns 403, not 401.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "missing_bearer_token", "message": "Authorization: Bearer required" } } } }, "RateLimited": { "description": "Rate limit exceeded. The public demo key allows 300 requests per minute per IP. Keys are limited per minute by plan: developer 120, growth 3,000, scale 30,000. There is no monthly quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "A KNOWN credential that may not be used: the key is revoked (`key_disabled`) or the client account is disabled (`client_disabled`). Never a fallback to the demo lane.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "missing_bearer_token", "message": "Authorization: Bearer required" } } } } } } }