# The public API reference of Azoth OS — generated from the contract by
# scripts/build-openapi-public.mjs; readable at https://www.azothos.ai/docs/api.
openapi: 3.1.0
info:
  title: Azoth OS API
  version: 1.1.0
  description: |-
    The routes of Azoth OS an application, an agent or an identity provider calls: the governed
    gateway, the decision journal and its dossiers, governance, usage and spend, SCIM provisioning.

    Authentication: each operation's `security` says which. A workspace API key, from Settings › Access,
    as `Authorization: Bearer <key>` or `X-Azoth-API-Key: <key>` — every route that takes a key accepts
    both; `x-azoth-scope` is the scope a scoped key needs. The dashboard's own reads take a signed-in
    session instead. SCIM routes take the workspace's SCIM token.

    Errors: an error answer carries `error`, a stable `code` and a `doc_url` to its entry in the
    error catalogue (https://www.azothos.ai/docs/errors). `x-azoth-codes` lists the codes an answer can
    carry. `x-azoth-feature` names the module a route needs: where the deployment does not run it, the
    route says so.

    The same reference, readable: https://www.azothos.ai/docs/api
servers:
  - url: https://www.azothos.ai
    description: Production
tags:
  - name: system
    description: Health and observability
  - name: sdk-ingest
    description: Usage event ingestion (SDK)
  - name: sdk-routing
    description: Intelligent model routing (SDK)
  - name: sdk-cache
    description: Semantic prompt cache (SDK)
  - name: sdk-loops
    description: Loop detection (SDK)
  - name: sdk-v1
    description: REST API v1 — requires developer plan (SDK)
  - name: sdk-regression
    description: Regression testing suite management and execution (SDK — pro plan)
  - name: scim
    description: SCIM 2.0 user/group provisioning (RFC 7643/7644) + token management
paths:
  /api/health:
    get:
      operationId: getHealth
      tags:
        - system
      summary: Health check, for uptime monitors
      description: |
        Answers 503 only when the database does not answer (`status: unavailable`). A cache, billing or
        provider breaker degrades the status word (`status: degraded`) but answers 200: none of them is an
        outage. Without credentials the payload is `status` and `version.commit` — the first 12 characters
        of the commit serving. The deployment's monitoring bearer token also reads `checks` (the database,
        Redis and Stripe), the full commit, the workers' queue and migrations. 120 requests a minute per
        address.
      security: []
      responses:
        '200':
          description: The database answers (`status` ok, or degraded by a non-critical dependency)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '429':
          description: Rate limited
        '503':
          description: The database does not answer (`status` unavailable)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /api/ingest:
    post:
      tags:
        - sdk-ingest
      operationId: postIngest
      summary: Ingest AI usage events
      description: |
        A batch of up to 500 usage events of AI calls made outside the gateway (observed, never governed).
        A write key is required; 200 batches a minute per workspace.

        **Budget gate**: the batch is refused with `402` before any event is stored when its total `costUsd`
        would take the workspace past an active budget; the answer names the budget and the overage.

        **Key scope**: a key limited to some connectors or environments refuses a batch with an event
        outside them (`403`).
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: ingest:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - events
              properties:
                events:
                  type: array
                  minItems: 1
                  maxItems: 500
                  items:
                    $ref: '#/components/schemas/IngestEvent'
      responses:
        '200':
          description: Events accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: integer
                    example: 12
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: A budget refused the batch before anything was stored.
          x-azoth-codes:
            - budget_exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Budget limit exceeded
                  code:
                    type: string
                    example: budget_exceeded
                  doc_url:
                    type: string
                    format: uri
                  budget:
                    type: string
                    description: Budget name
                    example: Monthly cap
                  overage:
                    type: number
                    description: USD over the limit
                    example: 12.34
        '403':
          description: >-
            A read key (`api_key_role_denied`); a key whose scopes, connectors or environments do not cover the call
            (`api_key_scope_denied` — for a connector or an environment, `dimension` says which); an address outside the
            workspace's IP allowlist (`ip_not_allowed`); or an EU-only data policy this deployment cannot honour
            (`eu_storage_unavailable`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - eu_storage_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: The body is larger than the route accepts (1 MB).
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again; or the ingest
            queue is full and the batch was not stored — send it again after the same delay.
          x-azoth-codes:
            - ingest_queue_full
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Ingest is not set up on this deployment — it cannot reach its database; nothing was stored.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: The write timed out; send the batch again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/arbiter/route:
    post:
      operationId: postArbiterRoute
      tags:
        - sdk-routing
      summary: Select optimal model for a request
      description: |
        Scores the available models against cost, quality and latency and answers the best one, checked
        against the workspace's governance and daily budget. The arbiter only routes: send the call itself
        through `/api/v1/chat/completions`. A write key is required.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: inference:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArbiterRequest'
      responses:
        '200':
          description: Routing decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArbiterResponse'
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: The daily budget left is below the model's estimated cost (`remainingUsd` says what is left).
          x-azoth-codes:
            - budget_exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Governance refused the selected model (`human_review_not_resumable` when a rule requires a person: send the
            call through `/api/v1/chat/completions` to have it held), or a key refusal.
          x-azoth-codes:
            - policy_blocked
            - sovereignty_blocked
            - jurisdiction_blocked
            - kill_switch_active
            - human_review_not_resumable
            - api_key_scope_denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The budget or governance could not be read — fail-closed.
          x-azoth-codes:
            - budget_unavailable
            - governance_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/cache/lookup:
    post:
      operationId: postCacheLookup
      tags:
        - sdk-cache
      summary: Look up a cached answer for a prompt
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: cache:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
              properties:
                prompt:
                  type: string
                  maxLength: 100000
                threshold:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: Similarity threshold (default 0.92)
                model:
                  type: string
                  maxLength: 128
      responses:
        '200':
          description: Cache result
          content:
            application/json:
              schema:
                type: object
                properties:
                  hit:
                    type: boolean
                  response:
                    type: string
                  savedUsd:
                    type: number
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/cache/store:
    post:
      operationId: postCacheStore
      tags:
        - sdk-cache
      summary: Store a prompt and its answer in the cache
      description: A write key is required. The workspace's data policy applies to what is stored.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: cache:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
                - response
                - model
                - provider
              properties:
                prompt:
                  type: string
                  maxLength: 100000
                response:
                  type: string
                  maxLength: 500000
                model:
                  type: string
                  maxLength: 128
                provider:
                  type: string
                  maxLength: 64
                costUsd:
                  type: number
                  minimum: 0
                ttlMs:
                  type: integer
                  minimum: 1
                  maximum: 604800000
      responses:
        '200':
          description: Entry stored
          content:
            application/json:
              schema:
                type: object
                properties:
                  stored:
                    type: boolean
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/loops/check:
    post:
      operationId: postLoopsCheck
      tags:
        - sdk-loops
      summary: Check an agent for a loop, reset its counters, or read its state
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: advisory:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agentId
              properties:
                action:
                  type: string
                  enum:
                    - check
                    - reset
                    - state
                  default: check
                agentId:
                  type: string
                  maxLength: 128
                workflowId:
                  type: string
                  maxLength: 128
                  nullable: true
                prompt:
                  type: string
                  maxLength: 100000
                  description: Required for action=check
                model:
                  type: string
                  maxLength: 128
                costUsd:
                  type: number
                  minimum: 0
      responses:
        '200':
          description: Loop check result
          content:
            application/json:
              schema:
                type: object
                properties:
                  loopDetected:
                    type: boolean
                  severity:
                    type: string
                    enum:
                      - warning
                      - critical
                  callCount:
                    type: integer
                  windowCostUsd:
                    type: number
                  shouldTerminate:
                    type: boolean
        '400':
          description: The body failed validation, or `prompt` is missing for `action=check`.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/proof/keys/{workspaceId}:
    get:
      operationId: getProofKeys
      tags:
        - system
      summary: A workspace's public receipt keys (JWKS)
      description: |
        Every public key the workspace ever signed a receipt or a dossier with — the retired ones included,
        so their receipts keep verifying — with its status and dates. Public by design: whoever holds a
        receipt verifies it without an account. The same file ships in every dossier (`keys.jwks.json`).
        A workspace with no key yet answers an empty set, like one that does not exist. Cached 5 minutes.
      security: []
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      type: object
                      description: A JWK (Ed25519, `kid` = RFC 7638 thumbprint) with its status and dates
        '400':
          description: The workspace id is not a UUID.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/chat/completions:
    post:
      operationId: postV1ChatCompletions
      tags:
        - sdk-v1
      summary: The governed gateway, OpenAI-compatible
      description: |
        A drop-in replacement for OpenAI's `/v1/chat/completions`: point an OpenAI client at
        `<your host>/api/v1` with an Azoth API key. Every call is bound to its mandate, checked against
        the emergency stop, the quota, the budgets, the policy rules, the applicable law and human
        approval before the model, and its decision is sealed. The provider is inferred from `model`.

        A served answer that is not streamed carries `X-Azoth-Receipt` and `azoth.receipt` in its body;
        a streamed answer (`stream: true`, `text/event-stream`) carries `X-Azoth-Trace-Id` — its decision
        is sealed when the stream ends. Every refusal carries its receipt and a `refusal` block (what,
        why, the rule and its owner, the compliant alternatives) in the caller's language.

        Send an `Idempotency-Key` to retry safely: a retry of an answered call gets that answer back,
        never a second model call, seal or spend.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: inference:write
      parameters:
        - $ref: '#/components/parameters/UsecaseHeader'
        - $ref: '#/components/parameters/DecisionRefHeader'
        - $ref: '#/components/parameters/SubjectZoneHeader'
        - $ref: '#/components/parameters/EndUserHeader'
        - $ref: '#/components/parameters/ChallengePassedHeader'
        - $ref: '#/components/parameters/OnBehalfOfHeader'
        - $ref: '#/components/parameters/LocaleHeader'
        - $ref: '#/components/parameters/AlternativeHeader'
        - $ref: '#/components/parameters/RefusalRefHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - messages
              properties:
                model:
                  type: string
                  minLength: 1
                messages:
                  type: array
                  minItems: 1
                  maxItems: 200
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - system
                          - user
                          - assistant
                          - tool
                          - function
                      content:
                        description: A string, or an array of content parts (their text is used)
                        oneOf:
                          - type: string
                          - type: array
                            items: {}
                      name:
                        type: string
                      tool_call_id:
                        type: string
                temperature:
                  type: number
                  minimum: 0
                  maximum: 2
                  default: 0.7
                max_tokens:
                  type: integer
                  minimum: 1
                  maximum: 32768
                stream:
                  type: boolean
                  default: false
                azoth_use_cache:
                  type: boolean
                  default: true
                  description: Allow the semantic cache for this call
                azoth_task:
                  type: string
                  enum:
                    - stable_qa
                    - rag
                    - faq
                    - summarization_soft
                    - arithmetic
                    - code
                    - legal
                    - finance
                    - medical
                    - security
                    - precision
                    - unknown
                  description: 'What the call does — a cache-safety hint: precise tasks never reuse a similar answer'
                azoth_cache_policy:
                  type: string
                  enum:
                    - auto
                    - strict
                    - permissive
                  default: auto
                azoth_agent_id:
                  type: string
                  description: The agent the call is attributed to
                azoth_workflow_id:
                  type: string
                azoth_compute_os:
                  type: boolean
                  default: false
                  description: Record the optimisation advice for this call
                azoth_sources:
                  $ref: '#/components/schemas/GroundingSources'
      responses:
        '200':
          description: The answer, in OpenAI's `chat.completion` shape (or an SSE stream when `stream` is true).
          headers:
            X-Azoth-Receipt:
              $ref: '#/components/headers/Receipt'
            X-Azoth-Trace-Id:
              $ref: '#/components/headers/TraceId'
            X-Azoth-Idempotency:
              $ref: '#/components/headers/IdempotencyState'
          content:
            application/json:
              schema:
                type: object
                description: chat.completion, plus `azoth.receipt` when a receipt was signed
            text/event-stream:
              schema:
                type: string
        '202':
          description: >-
            A rule requires a person's approval: the call is held under `approval_request_id`; once a different reviewer
            approves it, run it with `POST /api/v1/infer/resume`.
          x-azoth-codes:
            - human_review_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: The body or an Azoth header failed validation, or a person must be named on every call.
          x-azoth-codes:
            - validation_failed
            - invalid_decision_ref
            - invalid_on_behalf_of
            - invalid_alternative
            - alternative_not_offered
            - alternative_mismatch
            - invalid_refusal_ref
            - human_identity_required
            - idempotency_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: A budget, the month's quota or the trial refused the call before the model.
          x-azoth-codes:
            - budget_exceeded
            - ai_ops_limit_exceeded
            - sealed_decisions_limit_reached
            - trial_exhausted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: A governance refusal — sealed, with its receipt and its `refusal` block — or a key refusal.
          x-azoth-codes:
            - api_key_scope_denied
            - policy_blocked
            - usecase_unresolved
            - usecase_not_approved
            - usecase_prohibited
            - usecase_archived
            - usecase_divergence
            - mandate_suspended
            - mandate_expired
            - kill_switch_active
            - jurisdiction_blocked
            - sovereignty_blocked
            - secnumcloud_blocked
            - egress_blocked
            - data_exfiltration_blocked
            - redaction_failed
            - human_review_not_resumable
            - on_behalf_of_not_allowed
            - ungrounded_answer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            The first call with this `Idempotency-Key` still runs, or was answered but its answer was not kept for a
            retry (its trace and receipt are on this answer).
          x-azoth-codes:
            - idempotency_key_in_progress
            - idempotency_replay_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            The provider is not connected, refused the workspace's key, or refused this call — its account's credit or
            billing, the request's size or parameters: a retry as is fails again — or the `Idempotency-Key` was used
            with another body.
          x-azoth-codes:
            - provider_not_connected
            - provider_key_rejected
            - provider_permission_denied
            - provider_model_not_found
            - provider_payment_required
            - provider_request_too_large
            - provider_request_rejected
            - provider_not_supported
            - onboarding_no_provider
            - trial_unavailable
            - trial_limits_exceeded
            - idempotency_key_reused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '428':
          description: A public system asks the visitor to pass a challenge, then to send its nonce in `X-Azoth-Challenge-Passed`.
          x-azoth-codes:
            - exhaustion_challenge_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: A rate limit, a public system slowing or pausing a visitor, or too many concurrent calls.
          x-azoth-codes:
            - exhaustion_slow
            - exhaustion_blocked
            - tenant_concurrency_limit
            - loop_detected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: The provider failed after the call was admitted (nothing was sealed as served).
          x-azoth-codes:
            - provider_failure
            - provider_rate_limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            Governance, the emergency stop, the budget check, the identity check or the API key lookup could not run —
            the gateway fails closed.
          x-azoth-codes:
            - governance_error
            - kill_switch_unavailable
            - budget_unavailable
            - identity_unavailable
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/chat:
    post:
      operationId: postV1Chat
      tags:
        - sdk-v1
      summary: The governed gateway with an explicit provider, fallbacks and streaming
      description: |
        The same governance as `/api/v1/chat/completions`, in Azoth's own shape: name the `provider`,
        add up to 5 `fallbackProviders` (each one is governed as a new call), stream with `stream`.
        `onApprovalRequired: refuse` answers 403 instead of holding the call for a person.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: inference:write
      parameters:
        - $ref: '#/components/parameters/UsecaseHeader'
        - $ref: '#/components/parameters/DecisionRefHeader'
        - $ref: '#/components/parameters/SubjectZoneHeader'
        - $ref: '#/components/parameters/EndUserHeader'
        - $ref: '#/components/parameters/ChallengePassedHeader'
        - $ref: '#/components/parameters/OnBehalfOfHeader'
        - $ref: '#/components/parameters/LocaleHeader'
        - $ref: '#/components/parameters/AlternativeHeader'
        - $ref: '#/components/parameters/RefusalRefHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messages
                - model
                - provider
              properties:
                provider:
                  type: string
                  enum:
                    - openai
                    - anthropic
                    - mistral
                    - gemini
                    - azure_openai
                    - openrouter
                    - ollama
                    - deepseek
                    - huggingface
                    - internal
                model:
                  type: string
                  minLength: 1
                messages:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - system
                          - user
                          - assistant
                      content:
                        type: string
                        minLength: 1
                temperature:
                  type: number
                  minimum: 0
                  maximum: 2
                  default: 0.7
                maxTokens:
                  type: integer
                  minimum: 1
                  maximum: 32768
                stream:
                  type: boolean
                  default: false
                useCache:
                  type: boolean
                  default: true
                task:
                  type: string
                  enum:
                    - stable_qa
                    - rag
                    - faq
                    - summarization_soft
                    - arithmetic
                    - code
                    - legal
                    - finance
                    - medical
                    - security
                    - precision
                    - unknown
                cachePolicy:
                  type: string
                  enum:
                    - auto
                    - strict
                    - permissive
                  default: auto
                agentId:
                  type: string
                workflowId:
                  type: string
                fallbackProviders:
                  type: array
                  maxItems: 5
                  default: []
                  items:
                    type: object
                    required:
                      - provider
                      - model
                    properties:
                      provider:
                        type: string
                        enum:
                          - openai
                          - anthropic
                          - mistral
                          - gemini
                          - azure_openai
                          - openrouter
                          - ollama
                          - deepseek
                          - huggingface
                          - internal
                      model:
                        type: string
                        minLength: 1
                azureEndpoint:
                  type: string
                  format: uri
                  description: 'Required with provider azure_openai: an Azure OpenAI https endpoint'
                azureDeployment:
                  type: string
                  description: Required with provider azure_openai
                ollamaBaseUrl:
                  type: string
                  format: uri
                  description: >-
                    Optional. The gateway calls Ollama only at the address the workspace saved in Settings › Providers
                    and models; when sent, this must be that same address (scheme, host, port and path, a trailing slash
                    aside), else the call is refused (403 `ollama_endpoint_not_declared`). Without a saved address, an
                    Ollama call is refused (403 `ollama_endpoint_missing`).
                onApprovalRequired:
                  type: string
                  enum:
                    - park
                    - refuse
                  default: park
                  description: '`park` holds a call a rule sends to a person (202); `refuse` answers 403 and holds nothing.'
                azoth_sources:
                  $ref: '#/components/schemas/GroundingSources'
      responses:
        '200':
          description: The answer (`content`, `model`, `provider`, `usage`, `receipt`…), or an SSE stream when `stream` is true.
          headers:
            X-Azoth-Receipt:
              $ref: '#/components/headers/Receipt'
            X-Azoth-Trace-Id:
              $ref: '#/components/headers/TraceId'
            X-Azoth-Idempotency:
              $ref: '#/components/headers/IdempotencyState'
          content:
            application/json:
              schema:
                type: object
            text/event-stream:
              schema:
                type: string
        '202':
          description: >-
            A rule requires a person's approval — the call is held under `approval_request_id` (see
            `/api/v1/infer/resume`).
          x-azoth-codes:
            - human_review_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: The body or an Azoth header failed validation, or a person must be named on every call.
          x-azoth-codes:
            - validation_failed
            - invalid_decision_ref
            - invalid_on_behalf_of
            - invalid_alternative
            - alternative_not_offered
            - alternative_mismatch
            - invalid_refusal_ref
            - human_identity_required
            - idempotency_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: A budget or the month's quota refused the call before the model.
          x-azoth-codes:
            - budget_exceeded
            - ai_ops_limit_exceeded
            - sealed_decisions_limit_reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: A governance refusal — sealed, with its receipt and its `refusal` block — or a key refusal.
          x-azoth-codes:
            - api_key_scope_denied
            - policy_blocked
            - usecase_unresolved
            - usecase_not_approved
            - usecase_prohibited
            - usecase_archived
            - usecase_divergence
            - mandate_suspended
            - mandate_expired
            - kill_switch_active
            - jurisdiction_blocked
            - sovereignty_blocked
            - secnumcloud_blocked
            - egress_blocked
            - ollama_endpoint_missing
            - ollama_endpoint_not_declared
            - data_exfiltration_blocked
            - redaction_failed
            - human_review_not_resumable
            - on_behalf_of_not_allowed
            - ungrounded_answer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            The first call with this `Idempotency-Key` still runs, or was answered but its answer was not kept for a
            retry (its trace and receipt are on this answer).
          x-azoth-codes:
            - idempotency_key_in_progress
            - idempotency_replay_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            A provider address the gateway refuses, a missing Azure setting, or a provider that is not connected,
            refused the key or refused this call — its account's credit or billing, the request's size or parameters —
            or the `Idempotency-Key` was used with another body.
          x-azoth-codes:
            - endpoint_url_not_allowed
            - azure_endpoint_not_allowed
            - azure_config_required
            - invalid_azure_deployment
            - provider_not_connected
            - provider_key_rejected
            - provider_permission_denied
            - provider_model_not_found
            - provider_payment_required
            - provider_request_too_large
            - provider_request_rejected
            - idempotency_key_reused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '428':
          description: A public system asks the visitor to pass a challenge.
          x-azoth-codes:
            - exhaustion_challenge_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: A rate limit, a public system slowing or pausing a visitor, or too many concurrent calls.
          x-azoth-codes:
            - exhaustion_slow
            - exhaustion_blocked
            - tenant_concurrency_limit
            - loop_detected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: The provider and every fallback failed.
          x-azoth-codes:
            - provider_failure
            - provider_rate_limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            Governance, the emergency stop, the budget check, the identity check or the API key lookup could not run —
            the gateway fails closed.
          x-azoth-codes:
            - governance_error
            - kill_switch_unavailable
            - budget_unavailable
            - identity_unavailable
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/infer/resume:
    post:
      operationId: postV1InferResume
      tags:
        - sdk-v1
      summary: Run a held call once a reviewer approved it
      description: |
        Runs, once, the call a rule held for a person (the 202's `approval_request_id`), after a
        reviewer other than the requester approved it. Only the API key that made the call may resume
        it. The call meets the gateway's controls again — the emergency stop, the quota and governance
        with only that approval's gate waived — and is sealed under the same approval id. The id can be
        sent in the body or in the query string of the 202's `tracking_url`. Not streamed, no fallbacks.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: inference:write
      parameters:
        - name: approval_request_id
          in: query
          required: false
          description: The approval id, when it is not in the body (the 202's `tracking_url`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              required:
                - approval_request_id
              properties:
                approval_request_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: The answer of the approved call, with its receipt.
          headers:
            X-Azoth-Receipt:
              $ref: '#/components/headers/Receipt'
            X-Azoth-Trace-Id:
              $ref: '#/components/headers/TraceId'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The body failed validation.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: A budget or the month's quota refused the call (the approval is kept).
          x-azoth-codes:
            - budget_exceeded
            - ai_ops_limit_exceeded
            - sealed_decisions_limit_reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Another key's approval, a rejected approval, or a governance refusal under the rules in force now.
          x-azoth-codes:
            - api_key_scope_denied
            - not_requester
            - rejected
            - policy_blocked
            - usecase_not_approved
            - usecase_prohibited
            - usecase_archived
            - mandate_suspended
            - mandate_expired
            - kill_switch_active
            - jurisdiction_blocked
            - sovereignty_blocked
            - egress_blocked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No held call of this workspace has this approval id.
          x-azoth-codes:
            - not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Still pending, or already run.
          x-azoth-codes:
            - pending
            - already_executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: The approval expired — sealed, with its receipt.
          x-azoth-codes:
            - approval_expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            A rule now routes the call to a provider this route cannot call, or the workspace has no key for the
            provider — nothing was run and the approval is kept: fix it, then resume again. Or the provider refused the
            approved call — the key, the model, the account's credit or payment, the request's size or parameters, as
            the code says: the approval was used, ask for a new one once it is fixed.
          x-azoth-codes:
            - provider_not_supported
            - provider_not_connected
            - provider_key_rejected
            - provider_permission_denied
            - provider_model_not_found
            - provider_payment_required
            - provider_request_too_large
            - provider_request_rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was run.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: The provider failed (down, unreachable, or its rate limit or credit reached); the approval was used.
          x-azoth-codes:
            - provider_failure
            - provider_rate_limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Governance could not run, or the stored call cannot be read on this deployment — nothing was run.
          x-azoth-codes:
            - governance_error
            - kill_switch_unavailable
            - provider_key_storage_unavailable
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/infer/preflight:
    post:
      operationId: postV1InferPreflight
      tags:
        - sdk-v1
      summary: Score whether a request needs a model call at all
      description: |
        A 0 to 1 necessity score and, when a deterministic rule of the workspace already answers the
        request, the static response to return without a model call. The body is capped at 64 KB.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: advisory:read
      x-azoth-feature: FEATURE_IAE
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                connectorId:
                  type: string
                  minLength: 1
                  maxLength: 64
                request:
                  type: object
                  description: The request you would send — hashed by its structure
              additionalProperties: true
      responses:
        '200':
          description: The necessity score
          content:
            application/json:
              schema:
                type: object
                properties:
                  score:
                    type: number
                    minimum: 0
                    maximum: 1
                  shouldAvoid:
                    type: boolean
                  avoidReason:
                    type: string
                    nullable: true
                  staticResponse:
                    nullable: true
                  requestHash:
                    type: string
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: The body is larger than the route accepts (64 KB).
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/compress:
    post:
      operationId: postV1Compress
      tags:
        - sdk-v1
      summary: Compress long reasoning content (levels L1 to L3)
      description: Stores the compressed content and answers its id, its level and a reconstruction hash. A write key is required.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: advisory:read
      x-azoth-feature: FEATURE_CCE
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  minLength: 1
                  maxLength: 500000
                level:
                  type: string
                  enum:
                    - L1
                    - L2
                    - L3
                  default: L2
                agentId:
                  type: string
                  format: uuid
                  nullable: true
                workflowId:
                  type: string
                  format: uuid
                  nullable: true
                traceId:
                  type: string
                  format: uuid
                  nullable: true
      responses:
        '200':
          description: The compression result
          content:
            application/json:
              schema:
                type: object
                properties:
                  cognitiveStateId:
                    type: string
                    format: uuid
                    nullable: true
                  level:
                    type: string
                    enum:
                      - L1
                      - L2
                      - L3
                  originalTokens:
                    type: integer
                  compressedTokens:
                    type: integer
                  compressionRatio:
                    type: number
                  reconstructionHash:
                    type: string
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/reconstruct:
    post:
      operationId: postV1Reconstruct
      tags:
        - sdk-v1
      summary: Reconstruct compressed content from its id
      description: Only the workspace that compressed the content can reconstruct it.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: advisory:read
      x-azoth-feature: FEATURE_CCE
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - cognitiveStateId
              properties:
                cognitiveStateId:
                  type: string
                  format: uuid
      responses:
        '200':
          description: The reconstructed content
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: string
                  isLossless:
                    type: boolean
                  expandedTokens:
                    type: integer
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No compressed content with this id in the workspace.
          x-azoth-codes:
            - not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/marketplace:
    get:
      operationId: getV1Marketplace
      tags:
        - sdk-v1
      summary: The best-fit model of the provider marketplace for your constraints
      description: Filters the active listings by your hard constraints and scores them on cost, quality and latency.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: advisory:read
      x-azoth-feature: FEATURE_MARKETPLACE
      parameters:
        - name: mode
          in: query
          schema:
            type: string
            enum:
              - cost
              - quality
              - balanced
            default: balanced
        - name: maxCostPer1k
          in: query
          schema:
            type: number
            minimum: 0
        - name: maxLatencyMs
          in: query
          schema:
            type: integer
            minimum: 1
        - name: minQuality
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 1
        - name: requiresVision
          in: query
          schema:
            type: boolean
        - name: requiresTools
          in: query
          schema:
            type: boolean
        - name: minContextWindow
          in: query
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: The best match and its score
          content:
            application/json:
              schema:
                type: object
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No listing meets the hard constraints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/models/defaults:
    get:
      operationId: getV1ModelsDefaults
      tags:
        - sdk-v1
      summary: Which model a first call can use, per provider
      description: |
        One line per gateway provider: whether the workspace has a key for it (`connected`), and its test
        model from the model catalog in force (`source: catalog`) or the fallback (`fallback`). `role` is
        the key's. What `azoth init` (`@azothos/cli`) reads before its first call.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: advisory:read
      responses:
        '200':
          description: The key's role and the providers
          content:
            application/json:
              schema:
                type: object
                required:
                  - role
                  - providers
                properties:
                  role:
                    type: string
                    enum:
                      - read
                      - write
                      - admin
                  providers:
                    type: array
                    items:
                      type: object
                      properties:
                        provider:
                          type: string
                        connected:
                          type: boolean
                        model:
                          type: string
                          nullable: true
                        source:
                          type: string
                          enum:
                            - catalog
                            - fallback
                          nullable: true
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/journal:
    get:
      operationId: getV1Journal
      tags:
        - sdk-v1
      summary: The sealed decisions of the workspace
      description: |
        The workspace's sealed decision entries, newest first, with a footprint summary. The personal-data
        envelope is never included. Every parameter is validated: a value that cannot be read is a 400 naming it.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: journal:read
      x-azoth-feature: FEATURE_DECISION_JOURNAL
      parameters:
        - name: actorId
          in: query
          schema:
            type: string
            maxLength: 200
        - name: agentId
          in: query
          schema:
            type: string
            maxLength: 200
        - name: model
          in: query
          schema:
            type: string
            maxLength: 200
        - name: surface
          in: query
          schema:
            type: string
            enum:
              - inference
              - agent_step
              - agent_run
              - guard
              - governance
        - name: hasTools
          in: query
          schema:
            type: boolean
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
        - name: minCostEur
          in: query
          schema:
            type: number
            minimum: 0
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 0
            default: 100
          description: Page size (clamped to the maximum)
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: The sealed entries and their footprint
          content:
            application/json:
              schema:
                type: object
                properties:
                  entries:
                    type: array
                    items:
                      type: object
                  count:
                    type: integer
                  footprint:
                    type: object
        '400':
          description: A query parameter could not be read (`field` names it).
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/journal/export:
    get:
      operationId: getV1JournalExport
      tags:
        - sdk-v1
      summary: The evidence pack, or the signed audit dossier as a ZIP
      description: |
        The period's entries (seq ascending) with the chain's integrity verdict, also in the
        `X-Azoth-Journal-Integrity` header (`intact` or `broken:<seq>`). `format=dossier` answers the
        audit dossier: a reproducible ZIP — manifest, evidence, readable HTML and PDF, the workspace's
        public keys — anchored, timestamped when a time-stamping authority is set up, and signed with the
        workspace's key. Check it offline with `azoth-verify`. The personal-data envelope is never included.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: journal:read
      x-azoth-feature: FEATURE_DECISION_JOURNAL
      parameters:
        - name: actorId
          in: query
          schema:
            type: string
            maxLength: 200
        - name: agentId
          in: query
          schema:
            type: string
            maxLength: 200
        - name: model
          in: query
          schema:
            type: string
            maxLength: 200
        - name: surface
          in: query
          schema:
            type: string
            enum:
              - inference
              - agent_step
              - agent_run
              - guard
              - governance
        - name: hasTools
          in: query
          schema:
            type: boolean
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
        - name: minCostEur
          in: query
          schema:
            type: number
            minimum: 0
        - name: format
          in: query
          schema:
            type: string
            enum:
              - json
              - dossier
            default: json
        - name: lang
          in: query
          schema:
            type: string
            enum:
              - en
              - fr
            default: en
          description: The language of the dossier's readable files
      responses:
        '200':
          description: The evidence pack (JSON), or the dossier (ZIP)
          headers:
            X-Azoth-Journal-Integrity:
              schema:
                type: string
              description: '`intact` or `broken:<seq>`'
            X-Azoth-Dossier-Root-Hash:
              schema:
                type: string
              description: The dossier's root hash (`format=dossier`)
          content:
            application/json:
              schema:
                type: object
            application/zip:
              schema:
                type: string
                format: binary
        '400':
          description: A query parameter could not be read (`field` names it).
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The workspace's key could not sign the dossier — nothing is exported unsigned.
          x-azoth-codes:
            - dossier_signature_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/decisions/export:
    post:
      operationId: postV1DecisionsExport
      tags:
        - sdk-v1
      summary: The decision dossier of one business decision, as a ZIP
      description: |
        Every sealed call that carried this `X-Azoth-Decision-Ref`, with the policy in force that day, in
        a signed ZIP the offline verifier checks. The reference travels in the body, never in a URL, and
        is never stored.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: journal:read
      x-azoth-feature: FEATURE_DECISION_DOSSIER
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ref
              properties:
                ref:
                  type: string
                  minLength: 1
                  maxLength: 128
                  description: 'The decision reference: 1 to 128 visible ASCII characters'
      responses:
        '200':
          description: The decision dossier
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No sealed call carries this reference.
          x-azoth-codes:
            - decision_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The workspace's key could not sign the dossier — nothing is exported unsigned.
          x-azoth-codes:
            - dossier_signature_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/vault/receipts:
    post:
      operationId: postV1VaultReceipts
      tags:
        - sdk-v1
      summary: Seal the receipt of a call kept in your own vault
      description: |
        For a system in vault mode (`X-Azoth-Vault: on`), the SDK stores the request and the answer
        encrypted with your key in your storage, then posts their hashes here. Azoth seals the hashes
        under the call's trace id; it never receives the content or the key. Send the call's
        `X-Azoth-Decision-Ref`, if it had one.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: inference:write
      x-azoth-feature: FEATURE_CLIENT_VAULT
      parameters:
        - $ref: '#/components/parameters/DecisionRefHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - traceId
                - plaintextHash
                - ciphertextHash
              additionalProperties: false
              properties:
                traceId:
                  type: string
                  format: uuid
                plaintextHash:
                  type: string
                  pattern: ^[0-9a-f]{64}$
                ciphertextHash:
                  type: string
                  pattern: ^[0-9a-f]{64}$
                keyId:
                  type: string
                  description: 'A label of 1 to 64 letters, digits or . _ : -'
      responses:
        '202':
          description: Sealed
          content:
            application/json:
              schema:
                type: object
                properties:
                  sealed:
                    type: boolean
                  traceId:
                    type: string
                    format: uuid
        '400':
          description: The body or the decision reference failed validation.
          x-azoth-codes:
            - validation_failed
            - invalid_decision_ref
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/guard/evidence:
    get:
      operationId: getV1GuardEvidence
      tags:
        - sdk-v1
      summary: Azoth Guard's evidence pack, by obligation
      description: |
        The workspace's Guard findings grouped by the AI Act or GDPR obligation each is technical evidence
        for, anchored to the decision journal's integrity verdict. Findings carry only redacted evidence.
        The pack supports obligations: it is never a certification or an attestation of compliance.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: journal:read
      x-azoth-feature: FEATURE_GUARD_EVIDENCE_PACK
      parameters:
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
        - name: category
          in: query
          schema:
            type: string
          description: A Guard risk category (an unknown one is ignored)
        - name: severity
          in: query
          schema:
            type: string
            enum:
              - info
              - low
              - medium
              - high
              - critical
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: The evidence pack
          content:
            application/json:
              schema:
                type: object
                properties:
                  workspaceId:
                    type: string
                  generatedAt:
                    type: string
                    format: date-time
                  mappingVersion:
                    type: string
                  disclaimerKey:
                    type: string
                  summary:
                    type: object
                  obligations:
                    type: array
                    items:
                      type: object
                  findings:
                    type: array
                    items:
                      type: object
                  journalIntegrity:
                    type: object
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/incidents:
    get:
      operationId: getV1Incidents
      tags:
        - sdk-v1
      summary: The workspace's incidents
      description: >-
        Each incident's id, title, severity, status and the number of sealed decisions it touched — so your own system
        can check its references against one.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: journal:read
      x-azoth-feature: FEATURE_INCIDENT_MODE
      responses:
        '200':
          description: The incidents
          content:
            application/json:
              schema:
                type: object
                properties:
                  incidents:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        title:
                          type: string
                        severity:
                          type: string
                          enum:
                            - low
                            - medium
                            - high
                            - critical
                        status:
                          type: string
                        declaredAt:
                          type: string
                          format: date-time
                        closedAt:
                          type: string
                          format: date-time
                          nullable: true
                        scopeHash:
                          type: string
                        matched:
                          type: integer
                        scanState:
                          type: string
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/incidents/{id}/match:
    post:
      operationId: postV1IncidentsMatch
      tags:
        - sdk-v1
      summary: Which of your business references an incident touched
      description: |
        Up to 1,000 of your references (the `X-Azoth-Decision-Ref` you sent) → which of them the
        incident touched, and how far each was reviewed. Hashed on arrival, never stored or logged.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: journal:read
      x-azoth-feature: FEATURE_INCIDENT_MODE
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refs
              additionalProperties: false
              properties:
                refs:
                  type: array
                  minItems: 1
                  maxItems: 1000
                  items:
                    type: string
                    minLength: 1
                    maxLength: 256
      responses:
        '200':
          description: The references the incident touched
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such incident in the workspace.
          x-azoth-codes:
            - incident_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/usecases:
    get:
      operationId: getV1Usecases
      tags:
        - sdk-v1
      summary: The workspace's declared systems (use cases) and their flags
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: usecases:read
      responses:
        '200':
          description: The use cases, newest first, with the assessment's disclaimer
          content:
            application/json:
              schema:
                type: object
                properties:
                  usecases:
                    type: array
                    items:
                      type: object
                  disclaimer:
                    type: string
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: postV1Usecases
      tags:
        - sdk-v1
      summary: Declare a system (use case)
      description: |
        Runs the deterministic assessment and stores its flags; a blocking flag puts the use case under
        review. A key declares; only a person reviews and approves it, from the dashboard. The flags are
        a technical assessment, never a legal verdict. A write key is required.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: usecases:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                description:
                  type: string
                  maxLength: 5000
                purpose:
                  type: string
                  maxLength: 5000
                legal_basis:
                  type: string
                  enum:
                    - consent
                    - contract
                    - legal_obligation
                    - vital_interests
                    - public_task
                    - legitimate_interests
                data_categories:
                  type: array
                  maxItems: 50
                  default: []
                  items:
                    type: object
                    required:
                      - category
                      - sensitive
                    properties:
                      category:
                        type: string
                        minLength: 1
                        maxLength: 120
                      sensitive:
                        type: boolean
                affected_population:
                  type: string
                  enum:
                    - employees
                    - customers
                    - public
                    - minors
                    - vulnerable
                ai_act_classification:
                  type: string
                  enum:
                    - prohibited
                    - high_risk
                    - limited_risk
                    - minimal_risk
                automated_decision:
                  type: boolean
                  default: false
                provider:
                  type: string
                  maxLength: 120
                data_leaves_eu:
                  type: boolean
                  default: false
      responses:
        '201':
          description: The use case, its flags and the disclaimer
          content:
            application/json:
              schema:
                type: object
                properties:
                  usecase:
                    type: object
                  flags:
                    type: array
                    items:
                      type: object
                  disclaimer:
                    type: string
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/usecases/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getV1UsecasesId
      tags:
        - sdk-v1
      summary: One declared system (use case)
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: usecases:read
      responses:
        '200':
          description: The use case and the disclaimer
          content:
            application/json:
              schema:
                type: object
                properties:
                  usecase:
                    type: object
                  disclaimer:
                    type: string
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such use case in the workspace.
          x-azoth-codes:
            - not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchV1UsecasesId
      tags:
        - sdk-v1
      summary: Always refused — a person reviews a use case, from the dashboard
      description: >-
        Reviewing a use case is a person's accountable act (a reviewer other than its declarant); an API key has no
        person, so it can declare a use case but never review it.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: usecases:write
      responses:
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: A use case is reviewed by a person, signed in to the dashboard.
          x-azoth-codes:
            - human_reviewer_required
            - api_key_scope_denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/usecases/{id}/divergences:
    get:
      operationId: getV1UsecasesIdDivergences
      tags:
        - sdk-v1
      summary: The sealed calls that ran outside what a use case was approved for
      description: >-
        Each divergence carries its journal `seq`, so it can be checked in the sealed chain. The most recent 500 entries
        are read (`truncated` says when there were more).
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: usecases:read
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The divergences, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  usecaseId:
                    type: string
                  count:
                    type: integer
                  truncated:
                    type: boolean
                  divergences:
                    type: array
                    items:
                      type: object
                      properties:
                        seq:
                          type: integer
                        occurredAt:
                          type: string
                          format: date-time
                        decision:
                          type: string
                          nullable: true
                        provider:
                          type: string
                          nullable: true
                        model:
                          type: string
                          nullable: true
                        divergenceCodes:
                          type: array
                          items:
                            type: string
                  disclaimer:
                    type: string
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/exceptions:
    post:
      operationId: postV1Exceptions
      tags:
        - sdk-v1
      summary: Ask the rule's owner for a time-limited exception to a refusal
      description: |
        `refusal_ref` is the `refusal.ref` of a policy refusal of this API key, less than 7 days old: the
        rule and the identity the exception would cover come from it, never from the body. The rule's
        owner is told and decides; nothing applies until then. Asking again while a request is pending
        answers it (200). A write key is required.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: inference:write
      x-azoth-feature: FEATURE_HELPFUL_REFUSALS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refusal_ref
                - justification
              additionalProperties: false
              properties:
                refusal_ref:
                  type: string
                  minLength: 10
                  maxLength: 1024
                justification:
                  type: string
                  minLength: 20
                  maxLength: 2000
                  description: Why the rule should not apply here
                duration_days:
                  type: integer
                  minimum: 1
                  maximum: 90
                  description: The workspace's default when omitted; never past its ceiling
                requester_label:
                  type: string
                  minLength: 1
                  maxLength: 120
                  description: Who asks inside your application — kept on the request, never sealed
      responses:
        '200':
          description: The pending request already asked for this refusal
          content:
            application/json:
              schema:
                type: object
        '201':
          description: The request, created
          content:
            application/json:
              schema:
                type: object
        '400':
          description: >-
            The body failed validation, the reference is not one of this key's refusals, or this refusal cannot be
            lifted by an exception.
          x-azoth-codes:
            - validation_failed
            - invalid_refusal_ref
            - not_exceptionable
            - no_identity
            - duration_exceeds_ceiling
            - incident_containment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The rule that refused the call no longer exists.
          x-azoth-codes:
            - rule_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: An owner or admin has not turned this capability on for the workspace (Settings › Modules).
          x-azoth-codes:
            - capability_off
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/exceptions/{id}:
    get:
      operationId: getV1ExceptionsId
      tags:
        - sdk-v1
      summary: Where an exception this key asked for stands
      description: >-
        pending, active (until `expires_at`), expired, denied, revoked, or lapsed (nobody decided in time). Another
        key's request is a 404.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: inference:write
      x-azoth-feature: FEATURE_HELPFUL_REFUSALS
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The exception request and its state
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The id is not a UUID.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No exception this key asked for has this id.
          x-azoth-codes:
            - not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/grounding/release:
    post:
      operationId: postV1GroundingRelease
      tags:
        - sdk-v1
      summary: Fetch a high-stakes answer the grounding check held, once approved
      description: |
        Once someone other than the requester approved it, the API key that made the call fetches the
        held answer, once: it is erased as it is released, and the release is sealed. The answer comes
        in the format of the route that held it (`chat.completion` for `/api/v1/chat/completions`).
        A write key is required.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: inference:write
      x-azoth-feature: FEATURE_GROUNDING_CHECK
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - approval_request_id
              additionalProperties: false
              properties:
                approval_request_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: The released answer
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The approval was rejected, or a key refusal.
          x-azoth-codes:
            - rejected
            - api_key_scope_denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No held answer of this key has this approval id.
          x-azoth-codes:
            - not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Still waiting for its approval, or already released.
          x-azoth-codes:
            - pending
            - already_released
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: The approval expired before it was released.
          x-azoth-codes:
            - approval_expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/grounding/receipts:
    post:
      operationId: postV1GroundingReceipts
      tags:
        - sdk-v1
      summary: Seal the receipt of a grounding check run on your side
      description: |
        For a system in vault mode, the SDK checks the answer against its passages itself and posts the
        counts, versions and a hash — never the answer or the passages. Recorded and sealed. A write key is required.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: inference:write
      x-azoth-feature: FEATURE_GROUNDING_CHECK
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - traceId
                - claims
                - supported
                - judgeVersion
                - claimsVersion
                - sourcesHash
                - sourceCount
              additionalProperties: false
              properties:
                traceId:
                  type: string
                  format: uuid
                claims:
                  type: integer
                  minimum: 0
                  maximum: 500
                supported:
                  type: integer
                  minimum: 0
                  maximum: 500
                  description: At most `claims`
                judgeVersion:
                  type: string
                  maxLength: 200
                claimsVersion:
                  type: string
                  maxLength: 40
                sourcesHash:
                  type: string
                  pattern: ^[0-9a-f]{64}$
                  nullable: true
                sourceCount:
                  type: integer
                  minimum: 0
                  maximum: 100
                latencyMs:
                  type: integer
                  minimum: 0
                  maximum: 600000
                usecaseId:
                  type: string
                  format: uuid
                  description: The use case the call was bound to
      responses:
        '202':
          description: Sealed
          content:
            application/json:
              schema:
                type: object
                properties:
                  sealed:
                    type: boolean
                  checkId:
                    type: string
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The use case named is not one of the workspace's.
          x-azoth-codes:
            - usecase_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: An owner or admin has not turned this capability on for the workspace (Settings › Modules).
          x-azoth-codes:
            - capability_off
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/policy/packs:
    get:
      operationId: getV1PolicyPacks
      tags:
        - sdk-v1
      summary: The regulatory policy packs, or one pack in full
      description: |
        Each pack's id, framework, jurisdiction, review status and counts of instantiable rules and engine
        gaps; `?id=<packId>` answers one pack with its rules and obligation references. A pack presents
        technical controls supporting obligations — never a certification. Applying one is an admin's act,
        in the dashboard.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: policy:read
      x-azoth-feature: FEATURE_POLICY_PACKS
      parameters:
        - name: id
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: The packs (or one pack and its summary)
          content:
            application/json:
              schema:
                type: object
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No pack has this id.
          x-azoth-codes:
            - not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/governance/config:
    get:
      operationId: getV1GovernanceConfig
      tags:
        - sdk-v1
      summary: The workspace's data policy, as the SDK applies it in your process
      description: |
        The data categories the workspace's data policy allows and denies for a connector and an
        environment (connector + environment, then connector, then workspace), so the SDK strips what the
        server would strip before it leaves your process. Cached 60 seconds.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: policy:read
      parameters:
        - name: connector
          in: query
          schema:
            type: string
            maxLength: 120
        - name: environment
          in: query
          schema:
            type: string
            maxLength: 60
      responses:
        '200':
          description: The policy
          content:
            application/json:
              schema:
                type: object
                properties:
                  allowedDataCategories:
                    type: array
                    items:
                      type: string
                  deniedDataCategories:
                    type: array
                    items:
                      type: string
                  sovereigntyProfile:
                    type: string
                    enum:
                      - eu_only
                      - default
                  redactPii:
                    type: boolean
                  connectorSlug:
                    type: string
                    nullable: true
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/reference-sets/pending:
    get:
      operationId: getV1ReferenceSetsPending
      tags:
        - sdk-v1
      summary: The reference-set runs waiting for your system (model change control)
      description: |
        Reference sets kept in your vault, whose cases Azoth never holds: for each run, the model to run
        them on, `maxTokens`, and the cases by id and sha256. Run them through the gateway (SDK
        `runReferenceSet`) and post the receipt.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: usecases:read
      x-azoth-feature: FEATURE_MODEL_CHANGE_CONTROL
      responses:
        '200':
          description: The runs waiting
          content:
            application/json:
              schema:
                type: object
                properties:
                  runs:
                    type: array
                    items:
                      type: object
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: An owner or admin has not turned this capability on for the workspace (Settings › Modules).
          x-azoth-codes:
            - capability_off
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/reference-sets/receipts:
    post:
      operationId: postV1ReferenceSetsReceipts
      tags:
        - sdk-v1
      summary: Post the results of a reference-set run your system ran
      description: |
        Every case once, by the id and sha256 Azoth holds — never their text. The run is compared,
        reported and sealed like a run Azoth made. A write key is required.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: usecases:write
      x-azoth-feature: FEATURE_MODEL_CHANGE_CONTROL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - runId
                - results
              additionalProperties: false
              properties:
                runId:
                  type: string
                  format: uuid
                servedVersion:
                  type: string
                  minLength: 1
                  maxLength: 200
                results:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    required:
                      - id
                      - sha256
                      - passed
                      - latencyMs
                      - costUsd
                    additionalProperties: false
                    properties:
                      id:
                        type: string
                        pattern: ^[A-Za-z0-9_.:-]{1,64}$
                      sha256:
                        type: string
                        pattern: ^[0-9a-f]{64}$
                      passed:
                        type: boolean
                      error:
                        type: string
                        maxLength: 60
                      latencyMs:
                        type: integer
                        minimum: 0
                        maximum: 600000
                      costUsd:
                        type: number
                        minimum: 0
                        maximum: 100
                      assertions:
                        type: array
                        maxItems: 10
                        default: []
                        items:
                          type: object
                          required:
                            - type
                            - passed
                          properties:
                            type:
                              type: string
                              maxLength: 40
                            passed:
                              type: boolean
                            error:
                              type: string
                              maxLength: 200
      responses:
        '200':
          description: The run's verdict
          content:
            application/json:
              schema:
                type: object
                properties:
                  runId:
                    type: string
                    format: uuid
                  verdict:
                    type: string
                  regressed:
                    type: boolean
                  reportSha256:
                    type: string
        '400':
          description: The body failed validation, or a case is unknown or sent twice.
          x-azoth-codes:
            - validation_failed
            - unknown_case
            - duplicate_case
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No run of this workspace has this id.
          x-azoth-codes:
            - run_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The run is not waiting for your system, or the capability is off for the workspace.
          x-azoth-codes:
            - run_not_awaiting_client
            - capability_off
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/mcp:
    post:
      operationId: postV1Mcp
      tags:
        - sdk-v1
      summary: The governed MCP gateway (Streamable HTTP, tools only)
      description: |
        One endpoint for any standard MCP client, with an API key bound to one agent (created in
        Agents › MCP tools). `tools/list` shows the tools an admin approved for that agent's mandate;
        `tools/call` goes through the mandate, Azoth Guard and, for an irreversible or financial tool, a
        person's approval — sealed without its arguments or result, which come back marked untrusted.
        Stateless: one JSON-RPC 2.0 message per request; protocol errors keep the JSON-RPC shape.
        A browser `Origin` must be this deployment's.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: agents:write
      x-azoth-feature: FEATURE_MCP_GATEWAY
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: A JSON-RPC 2.0 message (initialize, server/discover, tools/list, tools/call, ping)
      responses:
        '200':
          description: The JSON-RPC answer
          content:
            application/json:
              schema:
                type: object
        '202':
          description: A notification, accepted (no body).
        '400':
          description: A JSON-RPC parse or protocol error, in the JSON-RPC shape.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The key is not bound to an agent, the browser origin is not this deployment's, or a key or plan refusal.
          x-azoth-codes:
            - key_not_bound_to_agent
            - origin_not_allowed
            - api_key_scope_denied
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Azoth Guard is off on this deployment — nothing could be authorised — or the database is unreachable.
          x-azoth-codes:
            - feature_disabled
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: getV1Mcp
      tags:
        - sdk-v1
      summary: Not used — the MCP gateway opens no stream (405)
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: agents:write
      x-azoth-feature: FEATURE_MCP_GATEWAY
      responses:
        '405':
          description: 'Method not allowed: POST only (`Allow: POST`).'
    delete:
      operationId: deleteV1Mcp
      tags:
        - sdk-v1
      summary: Not used — the MCP gateway keeps no session (405)
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: agents:write
      x-azoth-feature: FEATURE_MCP_GATEWAY
      responses:
        '405':
          description: 'Method not allowed: POST only (`Allow: POST`).'
  /api/v1/agents:
    get:
      operationId: getV1Agents
      tags:
        - sdk-v1
      summary: Spend and savings per agent
      description: Requires the Starter plan or above.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: agents:read
      parameters:
        - name: days
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
      responses:
        '200':
          description: One line per agent
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '400':
          description: '`days` could not be read (`field` names it).'
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/insights/{tool}:
    post:
      operationId: postV1InsightsTool
      tags:
        - sdk-v1
      summary: Run one of the assistant's read tools
      description: |
        What the in-app assistant reads, for an MCP server or any client: the same functions as the
        dashboard, so a figure here is the dashboard's. Read-only — a POST because the tool's input
        travels in the body. No model is called and no member's e-mail is returned. A former tool name
        answers for one version with a `Deprecation` header and the name to use. Requires the Starter plan
        or above, and the assistant on for the workspace.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: insights:read
      x-azoth-feature: FEATURE_ASSISTANT
      parameters:
        - name: tool
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-z_]+$
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                input:
                  type: object
                  default: {}
                  description: The tool's own input
                locale:
                  type: string
                  enum:
                    - en
                    - fr
                    - es
                    - zh
                    - ar
                  default: en
      responses:
        '200':
          description: The tool's data and the screens it comes from
          content:
            application/json:
              schema:
                type: object
                properties:
                  tool:
                    type: string
                  deprecated:
                    type: object
                    properties:
                      use:
                        type: string
                  data: {}
                  sources:
                    type: array
                    items:
                      type: object
        '400':
          description: The body or the tool's input failed validation (`field` names it, the tool's under `input`).
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The assistant is turned off for the workspace, or a key or plan refusal.
          x-azoth-codes:
            - assistant_disabled
            - api_key_scope_denied
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No tool has this name (`tools` lists them).
          x-azoth-codes:
            - unknown_tool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: This module is not enabled on this deployment.
          x-azoth-codes:
            - feature_disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/usage:
    get:
      operationId: getV1Usage
      tags:
        - sdk-v1
      summary: The workspace's usage traces, newest first (paginated)
      description: Every plan. Prefer `cursor` (the previous page's `next_cursor`) to `offset`.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: usage:read
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: cursor
          in: query
          schema:
            type: string
          description: The previous page's `next_cursor`
        - name: since
          in: query
          schema:
            type: string
            format: date
          description: A lower bound on the trace date (YYYY-MM-DD…)
        - name: model
          in: query
          schema:
            type: string
            maxLength: 128
        - name: agentId
          in: query
          schema:
            type: string
            maxLength: 128
        - name: status
          in: query
          schema:
            type: string
            enum:
              - ok
              - error
              - cached
      responses:
        '200':
          description: A page of usage traces
          content:
            application/json:
              schema:
                type: object
                properties:
                  traces:
                    type: array
                    items:
                      type: object
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
                      hasMore:
                        type: boolean
                  next_cursor:
                    type: string
                    nullable: true
        '400':
          description: A query parameter or the cursor could not be read (`field` names it).
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/report:
    get:
      operationId: getV1Report
      tags:
        - sdk-v1
      summary: The spend and savings report of the workspace
      description: >-
        Requires the Starter plan or above. `subscriptionCostUsd` is the subscription the report compares the spend with
        (USD).
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: usage:read
      parameters:
        - name: days
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
        - name: subscriptionCostUsd
          in: query
          schema:
            type: number
            minimum: 0
      responses:
        '200':
          description: The report
          content:
            application/json:
              schema:
                type: object
        '400':
          description: '`days` could not be read (`field` names it).'
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/budgets:
    get:
      operationId: getV1Budgets
      tags:
        - sdk-v1
      summary: The workspace's budgets and their use
      description: |
        The budgets set in Rules › Budgets, each with what it has used. `overBudget` is true once `used`
        passes `budget_limit` — `azoth budget --exit-on-exceeded` fails a CI step on it. Amounts in USD.
        A database failure is a 500, never an empty list.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: budgets:read
      responses:
        '200':
          description: The budgets, by name (an empty list when there is none)
          content:
            application/json:
              schema:
                type: object
                required:
                  - budgets
                properties:
                  budgets:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - name
                        - period
                        - budget_limit
                        - used
                        - pct
                        - remaining
                        - overBudget
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        period:
                          type: string
                          example: monthly
                        budget_limit:
                          type: number
                          example: 100
                        used:
                          type: number
                          example: 42.5
                        pct:
                          type: integer
                          minimum: 0
                          maximum: 100
                          description: used / budget_limit, rounded, at most 100
                        remaining:
                          type: number
                          minimum: 0
                          description: budget_limit − used, at least 0
                        overBudget:
                          type: boolean
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/export:
    get:
      operationId: getV1Export
      tags:
        - sdk-v1
      summary: The workspace's data, for portability (GDPR art. 20)
      description: |
        The art. 20 tables by default, as JSON or NDJSON; `tables` picks some (backup tables need an admin
        key). Rows that name a person go only to that person, through their personal API key; a service key
        exports none of them. Paginate per table with `offset` while `_meta.truncated` is true.
        10 exports per workspace per hour.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: journal:read
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum:
              - json
              - ndjson
            default: json
        - name: tables
          in: query
          schema:
            type: string
          description: Comma-separated table names
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 5000
            default: 5000
      responses:
        '200':
          description: The export
          content:
            application/json:
              schema:
                type: object
            application/x-ndjson:
              schema:
                type: string
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Backup tables asked with a key that is not an admin key (`api_key_role_denied`), a scope refusal
            (`api_key_scope_denied`), or an address outside the workspace's IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_role_denied
            - api_key_scope_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/system/modules:
    get:
      operationId: getSystemModules
      tags:
        - sdk-v1
      summary: Which modules are production-grade, beta or experimental
      description: The product's own module registry — no workspace data, so any key role reads it. Cached 5 minutes.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: usage:read
      parameters:
        - name: maturity
          in: query
          required: false
          schema:
            type: string
            enum:
              - core
              - beta
              - experimental
              - deprecated
      responses:
        '200':
          description: The module registry
          content:
            application/json:
              schema:
                type: object
                required:
                  - modules
                  - generated_at
                properties:
                  generated_at:
                    type: string
                    format: date-time
                  modules:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        maturity:
                          type: string
                          enum:
                            - core
                            - beta
                            - experimental
                            - deprecated
                        description:
                          type: string
                        featureFlag:
                          type: string
                          nullable: true
                        since:
                          type: string
        '400':
          description: An unknown `maturity` value.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/greenops/footprint:
    get:
      operationId: getV1GreenopsFootprint
      tags:
        - sdk-v1
      summary: The workspace's estimated energy and carbon footprint, over an API key
      description: >-
        The figures of the dashboard's GreenOps summary — energy saved, carbon avoided, inferences avoided, by strategy
        and provider. Estimates.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: usage:read
      parameters:
        - $ref: '#/components/parameters/PeriodDaysQuery'
      responses:
        '200':
          description: The footprint
          content:
            application/json:
              schema:
                type: object
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/greenops/energy:
    get:
      operationId: getV1GreenopsEnergy
      tags:
        - sdk-v1
      summary: Energy per day and per strategy, and the workspace's energy budget
      description: An API key, or a signed-in member naming `workspaceId`.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
        - SessionCookie: []
      parameters:
        - name: workspaceId
          in: query
          schema:
            type: string
            format: uuid
          description: Required with a session; the key's workspace otherwise
        - name: days
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 90
            default: 30
        - name: feature
          in: query
          schema:
            type: string
            enum:
              - all
              - io
            default: all
      responses:
        '200':
          description: Energy attribution
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalUsedWh:
                    type: number
                  totalSavedWh:
                    type: number
                  avgEnergyWhPerExec:
                    type: number
                  budget:
                    type: object
                    properties:
                      usedWh:
                        type: number
                      budgetWh:
                        type: number
                  dailySeries:
                    type: array
                    items:
                      type: object
                  byStrategy:
                    type: array
                    items:
                      type: object
                  topExecutions:
                    type: array
                    items:
                      type: object
        '401':
          description: No valid API key and no signed-in session.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
            - session_required
            - session_expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Not a member of the workspace named, a key that names another workspace than its own (`forbidden`), or a key
            refusal.
          x-azoth-codes:
            - not_a_member
            - forbidden
            - api_key_scope_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/greenops/summary:
    get:
      operationId: getV1GreenopsSummary
      tags:
        - sdk-v1
      summary: GreenOps key figures (the dashboard's read)
      description: >-
        Energy saved, carbon avoided, inferences avoided, the strategies and the most efficient providers. Estimates.
        For an API key, use `/api/v1/greenops/footprint`.
      security:
        - SessionCookie: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdQuery'
        - $ref: '#/components/parameters/PeriodDaysQuery'
      responses:
        '200':
          description: The key figures
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The `workspaceId` query parameter is missing.
          x-azoth-codes:
            - workspace_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No signed-in session, or it expired, or its MFA challenge is not completed.
          x-azoth-codes:
            - session_required
            - session_expired
            - mfa_challenge_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The signed-in person is not a member of this workspace, or the workspace requires MFA.
          x-azoth-codes:
            - not_a_member
            - mfa_required_by_workspace
            - forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The workspace membership could not be checked, or the service could not reach its database; try again.
          x-azoth-codes:
            - membership_lookup_failed
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/greenops/carbon:
    get:
      operationId: getV1GreenopsCarbon
      tags:
        - sdk-v1
      summary: Estimated carbon totals and their monthly trend (the dashboard's read)
      security:
        - SessionCookie: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdQuery'
        - $ref: '#/components/parameters/PeriodDaysQuery'
        - name: months
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 24
            default: 6
      responses:
        '200':
          description: Totals and the trend
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The `workspaceId` query parameter is missing.
          x-azoth-codes:
            - workspace_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No signed-in session, or it expired, or its MFA challenge is not completed.
          x-azoth-codes:
            - session_required
            - session_expired
            - mfa_challenge_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The signed-in person is not a member of this workspace, or the workspace requires MFA.
          x-azoth-codes:
            - not_a_member
            - mfa_required_by_workspace
            - forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The workspace membership could not be checked, or the service could not reach its database; try again.
          x-azoth-codes:
            - membership_lookup_failed
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/greenops/provider-efficiency:
    get:
      operationId: getV1GreenopsProviderEfficiency
      tags:
        - sdk-v1
      summary: Energy per 1,000 tokens, per provider and model (the dashboard's read)
      security:
        - SessionCookie: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdQuery'
        - $ref: '#/components/parameters/PeriodDaysQuery'
      responses:
        '200':
          description: One row per provider and model, most efficient first
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          description: The `workspaceId` query parameter is missing.
          x-azoth-codes:
            - workspace_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No signed-in session, or it expired, or its MFA challenge is not completed.
          x-azoth-codes:
            - session_required
            - session_expired
            - mfa_challenge_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The signed-in person is not a member of this workspace, or the workspace requires MFA.
          x-azoth-codes:
            - not_a_member
            - mfa_required_by_workspace
            - forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The workspace membership could not be checked, or the service could not reach its database; try again.
          x-azoth-codes:
            - membership_lookup_failed
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/greenops/replay-savings:
    get:
      operationId: getV1GreenopsReplaySavings
      tags:
        - sdk-v1
      summary: Energy saved by reusing answers (the dashboard's read)
      description: >-
        The reuse rate of cached answers, the energy it saved and its most frequent patterns. Energy only — no cost
        figure.
      security:
        - SessionCookie: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdQuery'
        - $ref: '#/components/parameters/PeriodDaysQuery'
      responses:
        '200':
          description: Reuse figures
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The `workspaceId` query parameter is missing.
          x-azoth-codes:
            - workspace_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No signed-in session, or it expired, or its MFA challenge is not completed.
          x-azoth-codes:
            - session_required
            - session_expired
            - mfa_challenge_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The signed-in person is not a member of this workspace, or the workspace requires MFA.
          x-azoth-codes:
            - not_a_member
            - mfa_required_by_workspace
            - forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The workspace membership could not be checked, or the service could not reach its database; try again.
          x-azoth-codes:
            - membership_lookup_failed
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/greenops/abatement:
    get:
      operationId: getV1GreenopsAbatement
      tags:
        - sdk-v1
      summary: Avoided CO₂ with its traceability (the dashboard's read)
      description: |
        The period's avoided CO₂ with what it rests on: the number of avoidances, by strategy, the
        methodology version and the sources of its coefficients. The avoided fraction is the figure to
        report; absolute grams are flagged advisory (`absoluteFigureReliable: false`).
      security:
        - SessionCookie: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdQuery'
        - $ref: '#/components/parameters/PeriodDaysQuery'
      responses:
        '200':
          description: The avoided-CO₂ report
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The `workspaceId` query parameter is missing.
          x-azoth-codes:
            - workspace_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No signed-in session, or it expired, or its MFA challenge is not completed.
          x-azoth-codes:
            - session_required
            - session_expired
            - mfa_challenge_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The signed-in person is not a member of this workspace, or the workspace requires MFA.
          x-azoth-codes:
            - not_a_member
            - mfa_required_by_workspace
            - forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The workspace membership could not be checked, or the service could not reach its database; try again.
          x-azoth-codes:
            - membership_lookup_failed
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/greenops:
    get:
      operationId: getV1Greenops
      tags:
        - sdk-v1
      deprecated: true
      summary: 'Deprecated: use /api/v1/greenops/summary'
      description: >-
        The former GreenOps read, kept until its `Sunset` date (2027-01-01). It answers `Deprecation`, `Sunset` and a
        `Link` to `/api/v1/greenops/summary`.
      security:
        - SessionCookie: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceIdQuery'
        - $ref: '#/components/parameters/PeriodDaysQuery'
      responses:
        '200':
          description: The former shape (`metrics`, `providerRanking`, `bySource`, `recentProfiles`)
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
            Link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The `workspaceId` query parameter is missing.
          x-azoth-codes:
            - workspace_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No signed-in session, or it expired, or its MFA challenge is not completed.
          x-azoth-codes:
            - session_required
            - session_expired
            - mfa_challenge_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The signed-in person is not a member of this workspace, or the workspace requires MFA.
          x-azoth-codes:
            - not_a_member
            - mfa_required_by_workspace
            - forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The workspace membership could not be checked, or the service could not reach its database; try again.
          x-azoth-codes:
            - membership_lookup_failed
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/regression/suites:
    get:
      operationId: getV1RegressionSuites
      tags:
        - sdk-regression
      summary: The workspace's regression suites
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: regression:read
      responses:
        '200':
          description: The suites
          content:
            application/json:
              schema:
                type: object
                properties:
                  suites:
                    type: array
                    items:
                      $ref: '#/components/schemas/RegressionSuite'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: postV1RegressionSuites
      tags:
        - sdk-regression
      summary: Create a regression suite
      description: |
        A named list of cases with their assertions. A case without an `id` gets the next one (`tc-001`,
        `tc-002`…). Requires the Starter plan or above and a write key; the plan sets how many suites a
        workspace keeps.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: regression:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - cases
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                description:
                  type: string
                provider:
                  type: string
                  default: openai
                model:
                  type: string
                  description: The model the suite runs on by default
                cases:
                  type: array
                  minItems: 1
                  maxItems: 500
                  items:
                    $ref: '#/components/schemas/RegressionCase'
      responses:
        '201':
          description: The suite
          content:
            application/json:
              schema:
                type: object
                properties:
                  suite:
                    $ref: '#/components/schemas/RegressionSuite'
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: The plan's number of suites is reached.
          x-azoth-codes:
            - regression_suite_limit_exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchV1RegressionSuites
      tags:
        - sdk-regression
      summary: Change a suite's name, description, provider or model
      description: The cases never change once the suite exists, so past runs stay comparable. A write key is required.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: regression:write
      parameters:
        - name: suiteId
          in: query
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                description:
                  type: string
                provider:
                  type: string
                model:
                  type: string
      responses:
        '200':
          description: The suite
          content:
            application/json:
              schema:
                type: object
                properties:
                  suite:
                    $ref: '#/components/schemas/RegressionSuite'
        '400':
          description: '`suiteId` is missing, or the body failed validation (`field` names which).'
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such suite in the workspace.
          x-azoth-codes:
            - not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteV1RegressionSuites
      tags:
        - sdk-regression
      summary: Delete a suite and its runs
      description: A write key is required.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: regression:write
      parameters:
        - name: suiteId
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
        '400':
          description: '`suiteId` is missing.'
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such suite in the workspace.
          x-azoth-codes:
            - not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/regression/runs:
    get:
      operationId: getV1RegressionRuns
      tags:
        - sdk-regression
      summary: The latest regression runs, newest first
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: regression:read
      parameters:
        - name: suiteId
          in: query
          schema:
            type: string
            format: uuid
          description: One suite's runs
      responses:
        '200':
          description: Up to 50 runs
          content:
            application/json:
              schema:
                type: object
                properties:
                  runs:
                    type: array
                    items:
                      $ref: '#/components/schemas/RegressionRun'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: postV1RegressionRuns
      tags:
        - sdk-regression
      summary: Run a suite, or compare 2 to 5 models on it
      description: |
        `{ suiteId, provider?, model? }` runs the suite on one model (the suite's own by default);
        `{ suiteId, models: [...] }` runs it on 2 to 5 models side by side. Each case goes through the
        governed gateway. The answer comes at once (202); read the result at `/api/v1/regression/runs/{id}`.
        Requires the Starter plan or above and a write key.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: regression:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required:
                    - suiteId
                  properties:
                    suiteId:
                      type: string
                      format: uuid
                    provider:
                      type: string
                    model:
                      type: string
                    checkRunId:
                      type: string
                      format: uuid
                      description: The GitHub check run the result is posted to
                    commitSha:
                      type: string
                      maxLength: 40
                    pullNumber:
                      type: integer
                      minimum: 1
                    repoFullName:
                      type: string
                      maxLength: 200
                - type: object
                  required:
                    - suiteId
                    - models
                  properties:
                    suiteId:
                      type: string
                      format: uuid
                    models:
                      type: array
                      minItems: 2
                      maxItems: 5
                      items:
                        type: object
                        required:
                          - provider
                          - model
                        properties:
                          provider:
                            type: string
                          model:
                            type: string
      responses:
        '202':
          description: Started — `runId`, or `runs` in compare mode
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The body failed validation; `error` names the first field at fault.
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's
            (`api_key_role_denied`), the request's address is outside the workspace's IP allowlist (`ip_not_allowed`),
            or the workspace's plan does not include this feature (`plan_required` names the plan that does).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
            - plan_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such suite (or check run) in the workspace.
          x-azoth-codes:
            - not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/regression/runs/{id}:
    get:
      operationId: getV1RegressionRunsId
      tags:
        - sdk-regression
      summary: One run, with each case's result
      description: Read again until `status` is `completed` or `failed`.
      security:
        - BearerToken: []
        - ApiKeyHeader: []
      x-azoth-scope: regression:read
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The run
          content:
            application/json:
              schema:
                type: object
                properties:
                  run:
                    $ref: '#/components/schemas/RegressionRun'
        '401':
          description: The API key is missing, invalid or revoked.
          x-azoth-codes:
            - api_key_missing
            - api_key_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key's scopes do not cover this route (`api_key_scope_denied`), its role is below the route's — a read
            key called a route that writes (`api_key_role_denied`) — or the request's address is outside the workspace's
            IP allowlist (`ip_not_allowed`).
          x-azoth-codes:
            - api_key_scope_denied
            - api_key_role_denied
            - ip_not_allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such run in the workspace.
          x-azoth-codes:
            - not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/me:
    get:
      operationId: getMe
      tags:
        - sdk-v1
      summary: Your personal data (GDPR art. 15) — signed in, never an API key
      description: |
        Every record of personal data held about the signed-in person: profile, memberships, personal
        API keys, consents, attribution, exceptions they asked for, chat links, notifications, support
        tickets, and their audit history 500 entries at a time (`cursor` = the previous page's
        `_meta.nextCursor`). An API key is no person: this route takes a session only. 10 requests an
        hour; each one is audited.
      security:
        - SessionCookie: []
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
            format: date-time
          description: The previous page's `_meta.nextCursor`
      responses:
        '200':
          description: The personal data
          content:
            application/json:
              schema:
                type: object
                required:
                  - _meta
                  - profile
                properties:
                  _meta:
                    type: object
                  profile:
                    type: object
                  termsAcceptance: {}
                  consentRecords:
                    type: array
                    items:
                      type: object
                  workspaceMemberships:
                    type: array
                    items:
                      type: object
                  personalApiKeys:
                    type: array
                    items:
                      type: object
                  attribution: {}
                  policyExceptions:
                    type: array
                    items:
                      type: object
                  chatAccountLinks:
                    type: array
                    items:
                      type: object
                  auditHistory:
                    type: array
                    items:
                      type: object
                  scimIdentities:
                    type: array
                    items:
                      type: object
                  notifications:
                    type: array
                    items:
                      type: object
                  supportTickets:
                    type: array
                    items:
                      type: object
                  supportMessages:
                    type: array
                    items:
                      type: object
        '400':
          description: '`cursor` is not an ISO 8601 date-time.'
          x-azoth-codes:
            - validation_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No signed-in session, or it expired, or its MFA challenge is not completed.
          x-azoth-codes:
            - session_required
            - session_expired
            - mfa_challenge_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service could not reach its database; try again.
          x-azoth-codes:
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteMe
      tags:
        - sdk-v1
      summary: Erase your account (GDPR art. 17) — signed in, never an API key
      description: |
        Erases the signed-in person's account and the workspaces they alone own, at once: audited first,
        the subscriptions of those workspaces cancelled first (nothing is deleted unless that succeeds), a
        confirmation e-mail queued. A workspace under a litigation hold is never erased (409). Cannot be
        undone. 3 requests an hour.
      security:
        - SessionCookie: []
      responses:
        '200':
          description: Erased
          content:
            application/json:
              schema:
                type: object
                properties:
                  erased:
                    type: boolean
        '401':
          description: No signed-in session, or it expired, or its MFA challenge is not completed.
          x-azoth-codes:
            - session_required
            - session_expired
            - mfa_challenge_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: A workspace you own is under a litigation hold.
          x-azoth-codes:
            - legal_hold_active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — wait `retryAfterMs` (body) or `Retry-After` (header), then try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal error; nothing was changed. Try again, or contact support with the time of the call.
          x-azoth-codes:
            - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: A subscription could not be cancelled — nothing was erased.
          x-azoth-codes:
            - billing_cancel_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service is unavailable, or the subscriptions could not be checked — nothing was erased.
          x-azoth-codes:
            - billing_cancel_failed
            - service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/scim/v2/Users:
    get:
      operationId: scimListUsers
      tags:
        - scim
      summary: 'SCIM: list users (filter, paginate)'
      security:
        - ScimBearer: []
      parameters:
        - name: filter
          in: query
          schema:
            type: string
          description: SCIM filter, e.g. userName eq "alice@example.com"
        - name: startIndex
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: count
          in: query
          schema:
            type: integer
            minimum: 0
            default: 100
      responses:
        '200':
          description: SCIM ListResponse
        '401':
          description: Invalid SCIM token
        '503':
          description: SCIM not configured
    post:
      operationId: scimCreateUser
      tags:
        - scim
      summary: 'SCIM: create + provision a user'
      security:
        - ScimBearer: []
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              type: object
              description: SCIM User resource (RFC 7643 §4.1)
      responses:
        '201':
          description: SCIM User created
        '401':
          description: Invalid SCIM token
        '409':
          description: User already exists
  /api/scim/v2/Users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: scimGetUser
      tags:
        - scim
      summary: 'SCIM: get a user'
      security:
        - ScimBearer: []
      responses:
        '200':
          description: SCIM User
        '401':
          description: Invalid SCIM token
        '404':
          description: User not found
    put:
      operationId: scimReplaceUser
      tags:
        - scim
      summary: 'SCIM: replace a user'
      security:
        - ScimBearer: []
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              type: object
              description: SCIM User resource
      responses:
        '200':
          description: SCIM User replaced
        '401':
          description: Invalid SCIM token
        '404':
          description: User not found
    patch:
      operationId: scimPatchUser
      tags:
        - scim
      summary: 'SCIM: patch a user (e.g. deactivate via active=false)'
      security:
        - ScimBearer: []
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              type: object
              description: SCIM PatchOp (RFC 7644 §3.5.2)
      responses:
        '200':
          description: SCIM User patched
        '401':
          description: Invalid SCIM token
        '404':
          description: User not found
    delete:
      operationId: scimDeleteUser
      tags:
        - scim
      summary: 'SCIM: delete (deprovision) a user'
      security:
        - ScimBearer: []
      responses:
        '204':
          description: User deleted
        '401':
          description: Invalid SCIM token
        '404':
          description: User not found
  /api/scim/v2/Groups:
    get:
      operationId: scimListGroups
      tags:
        - scim
      summary: 'SCIM: list groups'
      security:
        - ScimBearer: []
      parameters:
        - name: filter
          in: query
          schema:
            type: string
        - name: startIndex
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: count
          in: query
          schema:
            type: integer
            minimum: 0
            default: 100
      responses:
        '200':
          description: SCIM ListResponse
        '401':
          description: Invalid SCIM token
    post:
      operationId: scimCreateGroup
      tags:
        - scim
      summary: 'SCIM: create a group'
      security:
        - ScimBearer: []
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              type: object
              description: SCIM Group resource (RFC 7643 §4.2)
      responses:
        '201':
          description: SCIM Group created
        '401':
          description: Invalid SCIM token
  /api/scim/v2/Groups/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: scimGetGroup
      tags:
        - scim
      summary: 'SCIM: get a group'
      security:
        - ScimBearer: []
      responses:
        '200':
          description: SCIM Group
        '401':
          description: Invalid SCIM token
        '404':
          description: Group not found
    patch:
      operationId: scimPatchGroup
      tags:
        - scim
      summary: 'SCIM: patch a group (membership changes)'
      security:
        - ScimBearer: []
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              type: object
              description: SCIM PatchOp
      responses:
        '200':
          description: SCIM Group patched
        '401':
          description: Invalid SCIM token
        '404':
          description: Group not found
    delete:
      operationId: scimDeleteGroup
      tags:
        - scim
      summary: 'SCIM: delete a group'
      security:
        - ScimBearer: []
      responses:
        '204':
          description: Group deleted
        '401':
          description: Invalid SCIM token
        '404':
          description: Group not found
  /api/scim/v2/ServiceProviderConfig:
    get:
      operationId: scimServiceProviderConfig
      tags:
        - scim
      summary: 'SCIM: service provider configuration (RFC 7643 §5)'
      security:
        - ScimBearer: []
      responses:
        '200':
          description: ServiceProviderConfig
        '401':
          description: Invalid SCIM token
  /api/scim/v2/ResourceTypes:
    get:
      operationId: scimResourceTypes
      tags:
        - scim
      summary: 'SCIM: supported resource types'
      security:
        - ScimBearer: []
      responses:
        '200':
          description: ResourceType list
        '401':
          description: Invalid SCIM token
  /api/scim/v2/ResourceTypes/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: scimResourceType
      tags:
        - scim
      summary: 'SCIM: a single resource type'
      security:
        - ScimBearer: []
      responses:
        '200':
          description: ResourceType
        '401':
          description: Invalid SCIM token
        '404':
          description: Not found
  /api/scim/v2/Schemas:
    get:
      operationId: scimSchemas
      tags:
        - scim
      summary: 'SCIM: supported schemas'
      security:
        - ScimBearer: []
      responses:
        '200':
          description: Schema list
        '401':
          description: Invalid SCIM token
  /api/scim/v2/Schemas/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: scimSchema
      tags:
        - scim
      summary: 'SCIM: a single schema definition'
      security:
        - ScimBearer: []
      responses:
        '200':
          description: Schema
        '401':
          description: Invalid SCIM token
        '404':
          description: Not found
components:
  headers:
    Deprecation:
      description: |
        Per draft-ietf-httpapi-deprecation §2. Always the literal `true`
        on aliases listed under the "Legacy second-name routes" preamble.
      schema:
        type: string
        enum:
          - true
    IdempotencyState:
      description: >-
        What became of the call's `Idempotency-Key`: `stored` (a retry gets this answer), `not-kept` (a retry is told,
        never served again), `released` (not a final answer: a retry runs), `replayed` (this is the first call's
        answer), `not-applied` (a stream), `unavailable` (the store could not be used). Absent without the key.
      schema:
        type: string
        enum:
          - stored
          - not-kept
          - released
          - replayed
          - not-applied
          - unavailable
    Link:
      description: |
        Per draft-ietf-httpapi-deprecation §3. Machine-readable pointer to
        the canonical replacement, formatted as RFC 8288 link header.
      schema:
        type: string
        example: </api/v1/infer/preflight>; rel="successor-version"
    Receipt:
      description: >-
        The signed receipt of the decision — a compact JWS (EdDSA) over the sealed decision, never any content. On every
        answer that is not streamed while the decision journal is on, and on every refusal.
      schema:
        type: string
    Sunset:
      description: |
        Per RFC 8594. RFC 1123 date after which the route returns 410 Gone.
        All 13 aliases use `Tue, 09 Dec 2026 00:00:00 GMT`.
      schema:
        type: string
        example: Tue, 09 Dec 2026 00:00:00 GMT
    TraceId:
      description: The trace id of the call, the key that finds its sealed decision.
      schema:
        type: string
        format: uuid
  parameters:
    AlternativeHeader:
      name: X-Azoth-Alternative
      in: header
      required: false
      description: >-
        Re-send a refused call with one of the compliant alternatives its refusal offered (`mask_pii`, `eu_model`,
        `reduce_scope`), with `X-Azoth-Refusal-Ref`. The call is governed again in full.
      schema:
        type: string
        enum:
          - mask_pii
          - eu_model
          - reduce_scope
    ChallengePassedHeader:
      name: X-Azoth-Challenge-Passed
      in: header
      required: false
      description: The nonce of a cost-exhaustion challenge the visitor passed (after a 428).
      schema:
        type: string
    DecisionRefHeader:
      name: X-Azoth-Decision-Ref
      in: header
      required: false
      description: >-
        The business decision the call belongs to — an opaque id (1 to 128 visible ASCII characters), never personal
        data. Sealed only as a keyed hash; a decision dossier gathers its calls.
      schema:
        type: string
        maxLength: 128
    EndUserHeader:
      name: X-Azoth-End-User
      in: header
      required: false
      description: The visitor of a public system — an opaque id, never an e-mail.
      schema:
        type: string
    IdempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        One unique value per call (1 to 255 visible ASCII characters — a UUID, say), for a call that is not streamed. A
        retry with the same key, body and `X-Azoth-*` headers within the hour gets the first answer back — its status,
        body, receipt and trace — without the gates, the model, a second seal or a second spend (`X-Azoth-Idempotency:
        replayed`). The same key with another body is refused (422 `idempotency_key_reused`), and so is a retry while
        the first call still runs (409 `idempotency_key_in_progress`). A served answer is kept only where the
        workspace's data policy keeps responses without redacting or anonymizing them, and never for a use case in vault
        mode: otherwise a retry is answered 409 `idempotency_replay_unavailable` with the first call's trace and receipt
        — never a second model call. A 5xx, a 429 or a request that failed validation keeps nothing: its retry runs. A
        stream ignores the key (`not-applied`); without the store, the call runs as without it (`unavailable`). Only the
        key's hash is kept, per API key: another key never gets the answer.
      schema:
        type: string
        minLength: 1
        maxLength: 255
    LocaleHeader:
      name: X-Azoth-Locale
      in: header
      required: false
      description: The language of a refusal's explanation.
      schema:
        type: string
        enum:
          - en
          - fr
          - es
          - zh
          - ar
    OnBehalfOfHeader:
      name: X-Azoth-On-Behalf-Of
      in: header
      required: false
      description: >-
        The person the call is made for — their SCIM id or e-mail, resolved to a member and sealed only as a pseudonym.
        Only a service key an owner or admin allowed to name people may send it.
      schema:
        type: string
        maxLength: 256
    PeriodDaysQuery:
      name: periodDays
      in: query
      description: The period read, in days (1 to 90; 30 by default).
      schema:
        type: integer
        minimum: 1
        maximum: 90
        default: 30
    RefusalRefHeader:
      name: X-Azoth-Refusal-Ref
      in: header
      required: false
      description: The `refusal.ref` of the refusal whose alternative is taken (less than 7 days old, this key's).
      schema:
        type: string
    SubjectZoneHeader:
      name: X-Azoth-Subject-Zone
      in: header
      required: false
      description: Where the people concerned are — `FR`, `US-CA`, `EU`… — for the applicable law.
      schema:
        type: string
    UsecaseHeader:
      name: X-Azoth-Usecase
      in: header
      required: false
      description: The system (mandate) the call serves — its id from Mandates › Systems and agents.
      schema:
        type: string
        format: uuid
    WorkspaceIdQuery:
      name: workspaceId
      in: query
      required: true
      description: The workspace to read; the session must be one of its members.
      schema:
        type: string
        format: uuid
  schemas:
    ArbiterRequest:
      type: object
      properties:
        agentId:
          type: string
          maxLength: 128
        promptTokens:
          type: integer
          minimum: 0
          example: 500
        mode:
          type: string
          enum:
            - cost
            - quality
            - balanced
            - latency
          default: balanced
        qualityFloor:
          type: number
          minimum: 0
          maximum: 1
        latencyCeilingMs:
          type: integer
          minimum: 1
          maximum: 120000
        budgetUsd:
          type: number
          minimum: 0
        candidates:
          type: array
          items:
            type: string
          maxItems: 20
    ArbiterResponse:
      type: object
      required:
        - model
        - provider
        - estimatedCostUsd
        - estimatedLatencyMs
      properties:
        model:
          type: string
          example: gpt-4o-mini
        provider:
          type: string
          example: openai
        estimatedCostUsd:
          type: number
          example: 0.00012
        estimatedLatencyMs:
          type: integer
          example: 280
        qualityScore:
          type: number
        confidence:
          type: number
        reason:
          type: string
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Unauthorized
        code:
          type: string
          description: >-
            The stable error code, when the answer has one (e.g. `policy_blocked`, `plan_required`) — the field to
            branch on, never `error`'s words.
        doc_url:
          type: string
          format: uri
          description: >-
            Where the code is explained — `<your host>/docs/errors#<code>` — on every answer whose code the
            documentation explains.
    GroundingSources:
      type: array
      maxItems: 20
      description: >-
        The passages the answer must rest on, or their references, for the grounding check — at most 100,000 characters
        of text in all. Ignored where the grounding check is not enabled.
      items:
        oneOf:
          - type: object
            required:
              - text
            additionalProperties: false
            properties:
              id:
                type: string
                minLength: 1
                maxLength: 128
              text:
                type: string
                minLength: 1
                maxLength: 20000
          - type: object
            required:
              - id
              - sha256
            additionalProperties: false
            properties:
              id:
                type: string
                minLength: 1
                maxLength: 128
              sha256:
                type: string
                pattern: ^[0-9a-f]{64}$
    HealthResponse:
      type: object
      required:
        - status
        - version
      properties:
        status:
          type: string
          enum:
            - ok
            - degraded
            - unavailable
        version:
          type: object
          properties:
            commit:
              type: string
              nullable: true
              description: 'The commit this deployment serves: its first 12 characters without credentials, in full with the bearer'
        timestamp:
          type: string
          format: date-time
        latencyMs:
          type: integer
          example: 23
        checks:
          type: object
          description: Read with the monitoring bearer token only
          properties:
            db:
              type: string
              enum:
                - ok
                - degraded
                - not_configured
            redis:
              type: string
              enum:
                - ok
                - degraded
                - not_configured
            stripe:
              type: string
              enum:
                - configured
                - misconfigured
                - not_configured
        features:
          type: object
          additionalProperties:
            type: boolean
        openCircuits:
          type: array
          items:
            type: string
    IngestEvent:
      type: object
      properties:
        provider:
          type: string
          maxLength: 64
          example: openai
        model:
          type: string
          maxLength: 128
          example: gpt-4o
        route:
          type: string
          maxLength: 128
          nullable: true
        agentId:
          type: string
          maxLength: 128
          nullable: true
        workflowId:
          type: string
          maxLength: 128
          nullable: true
        inputTokens:
          type: integer
          minimum: 0
          example: 512
        outputTokens:
          type: integer
          minimum: 0
          example: 128
        costUsd:
          type: number
          minimum: 0
          example: 0.0042
        latencyMs:
          type: integer
          minimum: 0
          example: 340
        cacheHit:
          type: boolean
        optimizationApplied:
          type: boolean
        estimatedSavings:
          type: number
          minimum: 0
        status:
          type: string
          enum:
            - ok
            - error
            - cached
          default: ok
        tracedAt:
          type: string
          format: date-time
    RegressionAssertion:
      type: object
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - contains
            - not_contains
            - equals
            - max_tokens
            - min_length
            - max_length
            - regex
        value:
          oneOf:
            - type: string
            - type: number
    RegressionCase:
      type: object
      required:
        - prompt
      properties:
        id:
          type: string
          description: Auto-assigned if omitted (tc-001
          tc-002…): null
        prompt:
          type: string
          minLength: 1
        assertions:
          type: array
          items:
            $ref: '#/components/schemas/RegressionAssertion'
    RegressionRun:
      type: object
      required:
        - id
        - suite_id
        - status
      properties:
        id:
          type: string
          format: uuid
        suite_id:
          type: string
          format: uuid
        provider:
          type: string
        model:
          type: string
        status:
          type: string
          enum:
            - running
            - completed
            - failed
        total_cases:
          type: integer
        passed:
          type: integer
          nullable: true
        failed:
          type: integer
          nullable: true
        pass_rate:
          type: number
          nullable: true
          description: 'Computed column: passed / total_cases × 100'
        total_cost_usd:
          type: number
          nullable: true
        avg_latency_ms:
          type: integer
          nullable: true
        results:
          type: array
          items:
            type: object
          description: Per-case results (only present on GET /api/v1/regression/runs/{id})
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
    RegressionSuite:
      type: object
      required:
        - id
        - name
        - provider
        - model
        - case_count
        - created_at
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        provider:
          type: string
          example: openai
        model:
          type: string
          example: gpt-4o-mini
        case_count:
          type: integer
          description: Generated column — number of cases in the suite
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Azoth-API-Key
      description: >-
        A workspace API key (`az_live_…`, or `az_test_…` on the Free plan), from Settings › Access. Every route that
        takes an API key accepts it here or as a Bearer token.
    BearerToken:
      type: http
      scheme: bearer
      description: 'A workspace API key, as `Authorization: Bearer <key>`.'
    ScimBearer:
      type: http
      scheme: bearer
      description: |
        SCIM provisioning token — `Authorization: Bearer <scim_token>`. Minted by
        a workspace admin/owner at `POST /api/settings/scim/tokens`; the token row
        is workspace-scoped, so every SCIM call is isolated to one workspace.
    SessionCookie:
      type: apiKey
      in: cookie
      name: sb-access-token
      description: >-
        A signed-in session of the dashboard. The routes that take one serve the dashboard's own screens and never
        accept an API key.
