AgenticRail Evidence API

openapi: 3.2.0
info:
  title: AgenticRail Public Evidence 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.


    What 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.


    Evidence 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


    Timestamps: `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/
servers:
- url: https://api.agenticrail.nz
  description: Production
security:
- bearerAuth: []
tags:
- name: Evidence
  description: Verifiable records of what was enforced
paths:
  /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.


        This is the surface that supports offline verification. The synchronous `/v1/evaluate` response deliberately carries signature metadata only; the raw signature surfaces here.


        A 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: []
      - {}
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    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.'
  responses:
    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 <token> required'
    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 <token> 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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <your-key>`. Optional.


        An 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.


        A KNOWN identity presented wrongly is still refused: a wrong secret on a real prefix returns 401, and a revoked key returns 403.


        The 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`.'
externalDocs:
  description: Developer documentation and the enforcement specification
  url: https://agenticrail.nz/docs/