AxioRank Audit API

openapi: 3.2.0
info:
  title: AxioRank Gateway Audit API
  version: 1.0.0
  description: 'The runtime governance API behind every AxioRank SDK. Call it directly from any language. All requests authenticate with a bearer token and send/receive JSON.


    The SDKs (`@axiorank/sdk`, `axiorank` on PyPI) are thin wrappers over these endpoints. The canonical base path is `/api/v1`; the unversioned `/api/...` paths remain as aliases.'
  contact:
    name: AxioRank
    url: https://axiorank.com
servers:
- url: https://app.axiorank.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Audit
paths:
  /api/v1/audit/export:
    get:
      operationId: exportAuditLogs
      summary: Export audit logs (SIEM)
      description: Stream redacted audit-log rows as newline-delimited JSON (`application/x-ndjson`), one row per line, keyset-paginated by `(created_at, id)`. Follow the `x-axiorank-next-cursor` response header to page. Requires the `logs:read` scope and a Pro plan or above (`siemExport`).
      security:
      - bearerAuth: []
      parameters:
      - name: from
        in: query
        required: false
        schema:
          type: string
        description: ISO timestamp for the start of the window.
      - name: to
        in: query
        required: false
        schema:
          type: string
        description: ISO timestamp for the end of the window.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          maxLength: 512
        description: Opaque keyset cursor from the previous page.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 5000
          default: 1000
      - name: source
        in: query
        required: false
        schema:
          type: string
          enum:
          - sdk
          - mcp
          - coding-agent
          - browser-agent
      - name: decision
        in: query
        required: false
        schema:
          type: string
          enum:
          - allow
          - deny
          - hold
      responses:
        '200':
          description: NDJSON stream of redacted audit rows.
          headers:
            x-axiorank-next-cursor:
              schema:
                type: string
              description: Cursor for the next page; absent on the last page.
          content:
            application/x-ndjson:
              schema:
                type: string
        '400':
          description: Invalid query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing `logs:read` scope or plan does not include SIEM export.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Audit
  /api/v1/audit/public-key:
    get:
      operationId: auditPublicKey
      summary: Transparency-log public keys (JWKS)
      description: 'The Ed25519 public keys (active + retired) that sign audit receipts and signed tree heads. PUBLIC and unauthenticated by design: pin a key by `kid` out-of-band, then verify a receipt against it offline with the open-source `@axiorank/audit-verify` package. That independence from AxioRank is the whole point.'
      security: []
      responses:
        '200':
          description: A JWKS of the log signing keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicKeyResponse'
      tags:
      - Audit
  /api/v1/audit/verify-receipt:
    post:
      operationId: verifyAuditReceipt
      summary: Verify an audit receipt
      description: 'Convenience verifier: POST a receipt and get the per-check result. This is NOT the trust anchor - the authoritative path is the open-source verifier run against a key you pinned out-of-band, which needs no trust in this endpoint. Public and rate-limited.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditReceipt'
      responses:
        '200':
          description: The verification result (per-check + overall).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyReceiptResponse'
        '400':
          description: Malformed or oversized receipt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Audit
  /api/v1/audit/checkpoints/{seq}:
    get:
      operationId: auditCheckpoint
      summary: Signed tree head for a checkpoint
      description: Fetch the signed tree head (STH) for one of your workspace's sealed checkpoints by its sequence number. A monitor pins the STH series over time to detect a retroactive edit. Requires the `logs:read` scope; the workspace is taken from the key, so an STH series is never cross-tenant.
      security:
      - bearerAuth: []
      parameters:
      - name: seq
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: The signed tree head for that checkpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedTreeHead'
        '400':
          description: Invalid checkpoint sequence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown checkpoint, or it predates the Merkle upgrade.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Audit
  /api/v1/audit/receipt/{auditLogId}:
    get:
      operationId: auditReceipt
      summary: Issue an offline-verifiable receipt for an audit row
      description: 'Issue a self-contained receipt for one of your workspace''s audit rows: inclusion proof + signed tree head + signed provenance, verifiable offline with `@axiorank/audit-verify`. Requires the `logs:read` scope; the workspace is taken from the key. Returns an envelope with `status` (ok, pending_seal, purged, unavailable) and, when ok, the `receipt`.'
      security:
      - bearerAuth: []
      parameters:
      - name: auditLogId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The receipt envelope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                    - pending_seal
                    - purged
                    - unavailable
                  receipt:
                    $ref: '#/components/schemas/AuditReceipt'
                required:
                - status
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Audit
  /api/v1/audit/log/{logId}/checkpoints:
    get:
      operationId: listLogCheckpoints
      summary: Public checkpoint series for a monitored log
      description: 'PUBLIC, unauthenticated: the signed-tree-head series for a workspace that opted into public monitoring, keyed by its opaque log id. Anyone can pull the series and independently watch for equivocation or rollback (the `@axiorank/log-watchdog` daemon does this). Only hashes, counts, timestamps, signatures, and witness records are exposed, never audit content.'
      security: []
      parameters:
      - name: logId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: after
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: A page of checkpoints, ascending by sequence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicCheckpointList'
        '404':
          description: Unknown log id, or monitoring is not enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Audit
  /api/v1/audit/log/{logId}/checkpoints/latest:
    get:
      operationId: latestLogCheckpoint
      summary: Latest head for a monitored log
      description: 'PUBLIC, unauthenticated: the current head for an opted-in workspace''s log. A monitor fetches this each interval; a seq that goes backward, or a changed root/signature at a known seq, signals equivocation.'
      security: []
      parameters:
      - name: logId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The current head.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicCheckpoint'
        '404':
          description: Unknown log id, or no checkpoints sealed yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Audit
  /api/v1/audit/log/{logId}/checkpoints/{seq}:
    get:
      operationId: logCheckpointBySeq
      summary: One checkpoint by sequence for a monitored log
      description: 'PUBLIC, unauthenticated: re-fetch a specific head a monitor pinned earlier and confirm it is byte-identical.'
      security: []
      parameters:
      - name: logId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: seq
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: The checkpoint at that sequence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicCheckpoint'
        '400':
          description: Invalid checkpoint sequence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown log id or checkpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Audit
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    VerifyReceiptResponse:
      type: object
      properties:
        ok:
          type: boolean
        checks:
          type:
          - object
          - 'null'
          properties:
            leaf:
              type: boolean
              description: leafHash matches SHA-256(0x00 ‖ rowHash).
            rowBinding:
              type:
              - boolean
              - 'null'
              description: Null unless the row is supplied.
            inclusion:
              type: boolean
              description: Proof folds to the signed Merkle root.
            sthSignature:
              type: boolean
              description: Tree-head signature verifies.
            provenance:
              type:
              - boolean
              - 'null'
              description: Provenance token verifies (null if none).
            approver:
              type:
              - boolean
              - 'null'
              description: Every human-approval signature verifies (null if none present).
        reason:
          type: string
          description: Present only when ok is false.
      required:
      - ok
      - checks
    PublicCheckpoint:
      type: object
      description: 'A public checkpoint head: the signed tree head plus its chain fields and witnesses.'
      properties:
        seq:
          type: integer
        signedTreeHead:
          oneOf:
          - $ref: '#/components/schemas/SignedTreeHead'
          - type: 'null'
          description: The stored signed tree head, or null for a legacy checkpoint.
        checkpointHash:
          type: string
        batchHash:
          type: string
        prevHash:
          type: string
        rowCount:
          type: integer
        fromTs:
          type: string
          format: date-time
        toTs:
          type: string
          format: date-time
        purged:
          type: boolean
          description: Rows purged under retention; the signed head still proves the window.
        witnesses:
          type: array
          items:
            $ref: '#/components/schemas/WitnessRecord'
      required:
      - seq
      - checkpointHash
      - batchHash
      - prevHash
      - rowCount
      - fromTs
      - toTs
      - purged
      - witnesses
    PublicCheckpointList:
      type: object
      properties:
        logId:
          type: string
          format: uuid
        checkpoints:
          type: array
          items:
            $ref: '#/components/schemas/PublicCheckpoint'
      required:
      - logId
      - checkpoints
    PublicKeyResponse:
      type: object
      description: JWKS of the transparency-log signing keys (active + retired). Pin a key by kid.
      properties:
        keys:
          type: array
          items:
            type: object
            properties:
              kid:
                type: string
              kty:
                type: string
                enum:
                - OKP
              crv:
                type: string
                enum:
                - Ed25519
              x:
                type: string
              alg:
                type: string
                enum:
                - EdDSA
              use:
                type: string
                enum:
                - sth
                - provenance
                - approver
                - tool-log-sth
              status:
                type: string
                enum:
                - active
                - retired
            required:
            - kid
            - kty
            - crv
            - x
      required:
      - keys
    AuditReceipt:
      type: object
      description: A self-contained, offline-verifiable proof for one audit row.
      properties:
        version:
          type: integer
          enum:
          - 1
        auditLogId:
          type: string
          format: uuid
        workspaceId:
          type: string
          format: uuid
        rowHash:
          type: string
          description: Hex SHA-256 over the row's immutable fields.
        leafHash:
          type: string
        leafIndex:
          type: integer
        treeSize:
          type: integer
        inclusionPath:
          type: array
          items:
            type: object
            properties:
              dir:
                type: string
                enum:
                - L
                - R
              hash:
                type: string
            required:
            - dir
            - hash
        signedTreeHead:
          $ref: '#/components/schemas/SignedTreeHead'
        provenance:
          type: object
          additionalProperties: true
          description: The Ed25519-signed delegation-provenance token (who authorized the action).
      required:
      - version
      - auditLogId
      - workspaceId
      - rowHash
      - leafHash
      - leafIndex
      - treeSize
      - inclusionPath
      - signedTreeHead
    WitnessRecord:
      type: object
      description: An independent witness co-signature over a signed tree head (split-view defense).
      properties:
        witness:
          type: string
          description: 'Witness scheme: ''rekor'' or ''note:<name>''.'
        keyId:
          type: string
          description: Pinned witness key / log id used to verify the countersignature.
        signedAt:
          type: string
          format: date-time
        subjectHash:
          type: string
          description: 'Hex SHA-256 over the canonical STH: binds the record to this head.'
        signature:
          type: string
          description: The witness countersignature (for rekor, the SET).
        meta:
          type: object
          additionalProperties: true
      required:
      - witness
      - keyId
      - signedAt
      - subjectHash
      - signature
    SignedTreeHead:
      type: object
      description: An Ed25519-signed Merkle tree head over a sealed checkpoint window.
      properties:
        seq:
          type: integer
        merkleRoot:
          type: string
          description: Hex RFC 6962 root over the window's row hashes.
        treeSize:
          type: integer
        prevCheckpointHash:
          type: string
          description: Binds the STH into the append-only chain.
        checkpointHash:
          type: string
          description: This checkpoint's own hash, signed on self-anchored (v2) heads. Absent on v1.
        fromTs:
          type: string
          format: date-time
        toTs:
          type: string
          format: date-time
        workspaceId:
          type: string
          format: uuid
        algorithm:
          type: string
          enum:
          - EdDSA
        merkleVersion:
          type: integer
        treeAlgo:
          type: string
          examples:
          - rfc6962-sha256
        keyId:
          type: string
          description: RFC 7638 thumbprint of the signing key (JWKS lookup id).
        signedAt:
          type: string
          format: date-time
        signature:
          type: string
          description: base64url Ed25519 over the canonical STH.
      required:
      - seq
      - merkleRoot
      - treeSize
      - prevCheckpointHash
      - fromTs
      - toTs
      - workspaceId
      - algorithm
      - merkleVersion
      - treeAlgo
      - keyId
      - signedAt
      - signature
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An AxioRank API key (`axr_live_…` agent key or `axr_site_…` property key) or a short-lived token (`axr_tok_…`). Sent as `Authorization: Bearer <key>`. Scopes: `gateway:write`, `cards:verify`, `inbound:verify`, `logs:read`, `admin`.'