AgenticRail Operational API

openapi: 3.2.0
info:
  title: AgenticRail Public Operational 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: operational
  description: Health and latency helpers
paths:
  /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 <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/