openapi.yaml

openapi: 3.1.0
info:
  title: BitRouter API
  description: |-
    The BitRouter API exposes the routing proxy and account-bound services of the hosted BitRouter Cloud node.

    ## Base URL

    ```
    https://api.bitrouter.ai
    ```

    Most endpoints are served under `/v1`. The healthcheck (`/ping`) lives at the root.

    ## Authentication

    Routing endpoints (`/v1/chat/completions`, `/v1/messages`, `/v1/responses`, `/v1beta/models/{model_action}`) accept either:

    - `x-api-key: <api-key>` — Anthropic-compatible header.
    - `Authorization: Bearer <api-key | JWT>` — issued via the BitRouter console or minted from a wallet (CAIP-10 issuer).

    Discovery endpoints (`/v1/models`, `/v1/providers`, `/v1/byok/encryption-pubkey`) and the healthcheck are public.

    ## Multi-Protocol Routing

    BitRouter accepts requests in the native format of each supported provider:

    - **OpenAI Chat Completions** — `/v1/chat/completions`
    - **OpenAI Responses** — `/v1/responses`
    - **Anthropic Messages** — `/v1/messages`
    - **Google Generative Language** — `/v1beta/models/{model}:generateContent`

    The router resolves the requested model to a configured upstream provider, forwards the request, and returns the response in the same provider format.
  version: 1.0.0
servers:
- url: https://api.bitrouter.ai
  description: Production
paths:
  /ping:
    get:
      tags:
      - Health
      summary: Liveness check
      description: Returns `200 OK` with an empty body if the node is up.
      operationId: ping
      responses:
        '200':
          description: Node is up.
  /v1/models:
    get:
      tags:
      - Discovery
      summary: List available models
      description: Returns all models available across configured providers. Supports optional query filters for provider, model ID substring, and modality.
      operationId: listModels
      parameters:
      - in: query
        name: provider
        description: Filter by provider name (exact match against the model's `providers` array).
        schema:
          type: string
        style: form
      - in: query
        name: id
        description: Filter by model ID (case-insensitive substring match).
        schema:
          type: string
        style: form
      - in: query
        name: input_modality
        description: Filter by supported input modality (e.g. `text`, `image`).
        schema:
          type: string
        style: form
      - in: query
        name: output_modality
        description: Filter by supported output modality.
        schema:
          type: string
        style: form
      responses:
        '200':
          description: List of models.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ModelListResponse
                description: |-
                  Envelope shape for `GET /v1/models`. Wraps the catalogue in `{ "data": [...] }`
                  so future top-level fields (pagination cursors, etc.) can be added without a
                  breaking change.
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/$defs/ModelResponse'
                required:
                - data
                $defs:
                  ContextTier:
                    description: |-
                      A higher context-pricing bracket. Some upstreams bill a model at a steeper
                      rate once the prompt crosses a context-length threshold (e.g. one rate up
                      to 128k input tokens, a higher one between 128k and 256k). The selected
                      bracket's rates apply to the **whole** request — a step function, not
                      graduated marginal brackets — and the bracket is chosen by the request's
                      total input (prompt) token count.

                      Upstreams that publish such tiers:
                      - Alibaba Qwen Model Studio:
                        <https://help.aliyun.com/en/model-studio/models>
                      - Google Gemini API long-context pricing:
                        <https://ai.google.dev/gemini-api/docs/pricing>
                    type: object
                    properties:
                      above_input_tokens:
                        description: |-
                          **Exclusive** lower bound on total input tokens. A request whose input
                          size is strictly greater than this is eligible for the bracket; a
                          request exactly at the bound stays in the lower bracket (so a base
                          bracket documented as "≤ 128k" is expressed as a tier with
                          `above_input_tokens: 128000`).
                        type: integer
                        format: uint64
                        minimum: 0
                      input_tokens:
                        $ref: '#/$defs/InputTokenPricing'
                      output_tokens:
                        $ref: '#/$defs/OutputTokenPricing'
                    required:
                    - above_input_tokens
                  InputTokenPricing:
                    description: Input token pricing per million tokens.
                    type: object
                    properties:
                      cache_read:
                        description: Cost per million cache-read input tokens.
                        type:
                        - number
                        - 'null'
                        format: double
                      cache_write:
                        description: Cost per million cache-write input tokens.
                        type:
                        - number
                        - 'null'
                        format: double
                      no_cache:
                        description: Cost per million non-cached input tokens.
                        type:
                        - number
                        - 'null'
                        format: double
                  ModelPricing:
                    description: |-
                      Token pricing per million tokens for a model.

                      `input_tokens`/`output_tokens` are the **base bracket**: the rates for the
                      lowest context range and the fallback when no [`context_tiers`] entry
                      applies. When `context_tiers` is empty the pricing is a single flat rate
                      for every request size (the historical behaviour).

                      [`context_tiers`]: ModelPricing::context_tiers
                    type: object
                    properties:
                      context_tiers:
                        description: |-
                          Optional higher context brackets. Empty ⇒ flat pricing. The registry
                          validator enforces ascending, unique `above_input_tokens` and a
                          complete base bracket, so the per-request resolver does not depend on
                          list order.
                        type: array
                        items:
                          $ref: '#/$defs/ContextTier'
                      input_tokens:
                        $ref: '#/$defs/InputTokenPricing'
                      output_tokens:
                        $ref: '#/$defs/OutputTokenPricing'
                  ModelResponse:
                    type: object
                    properties:
                      capabilities:
                        description: |-
                          Union of inference capabilities advertised across this model's providers
                          (e.g. `structured_outputs`). Omitted when empty.
                        type: array
                        items:
                          type: string
                      description:
                        type:
                        - string
                        - 'null'
                      id:
                        type: string
                      input_modalities:
                        type: array
                        items:
                          type: string
                      max_input_tokens:
                        type:
                        - integer
                        - 'null'
                        format: uint64
                        minimum: 0
                      max_output_tokens:
                        type:
                        - integer
                        - 'null'
                        format: uint64
                        minimum: 0
                      name:
                        type:
                        - string
                        - 'null'
                      output_modalities:
                        type: array
                        items:
                          type: string
                      pricing:
                        anyOf:
                        - $ref: '#/$defs/ModelPricing'
                        - type: 'null'
                      providers:
                        $ref: '#/$defs/ProvidersSummary'
                    required:
                    - id
                    - input_modalities
                    - output_modalities
                    - capabilities
                    - providers
                  OutputTokenPricing:
                    description: Output token pricing per million tokens.
                    type: object
                    properties:
                      audio:
                        description: Cost per million audio output tokens. Reserved — see `image`.
                        type:
                        - number
                        - 'null'
                        format: double
                      image:
                        description: |-
                          Cost per million image output tokens. Reserved — not yet wired
                          into `calculate_charge_micro_usd`.
                        type:
                        - number
                        - 'null'
                        format: double
                      reasoning:
                        description: Cost per million reasoning output tokens.
                        type:
                        - number
                        - 'null'
                        format: double
                      text:
                        description: Cost per million text output tokens.
                        type:
                        - number
                        - 'null'
                        format: double
                  ProvidersSummary:
                    type: object
                    properties:
                      total_online:
                        type: integer
                        format: uint
                        minimum: 0
                    required:
                    - total_online
  /v1/providers:
    get:
      tags:
      - Discovery
      summary: List providers
      description: Public registry of providers the node knows about, sourced from the upstream `bitrouter-providers` builtins. Used by the console to render the BYOK page without hard-coding the list.
      operationId: listProviders
      responses:
        '200':
          description: List of providers.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ProviderListResponse
                description: |-
                  Envelope for `GET /v1/providers`. Same `{ "data": [...] }` shape as
                  `/v1/models` so the two listings stay consistent for SDK consumers.
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/$defs/ProviderCatalogEntry'
                required:
                - data
                $defs:
                  ContextTier:
                    description: |-
                      A higher context-pricing bracket. Some upstreams bill a model at a steeper
                      rate once the prompt crosses a context-length threshold (e.g. one rate up
                      to 128k input tokens, a higher one between 128k and 256k). The selected
                      bracket's rates apply to the **whole** request — a step function, not
                      graduated marginal brackets — and the bracket is chosen by the request's
                      total input (prompt) token count.

                      Upstreams that publish such tiers:
                      - Alibaba Qwen Model Studio:
                        <https://help.aliyun.com/en/model-studio/models>
                      - Google Gemini API long-context pricing:
                        <https://ai.google.dev/gemini-api/docs/pricing>
                    type: object
                    properties:
                      above_input_tokens:
                        description: |-
                          **Exclusive** lower bound on total input tokens. A request whose input
                          size is strictly greater than this is eligible for the bracket; a
                          request exactly at the bound stays in the lower bracket (so a base
                          bracket documented as "≤ 128k" is expressed as a tier with
                          `above_input_tokens: 128000`).
                        type: integer
                        format: uint64
                        minimum: 0
                      input_tokens:
                        $ref: '#/$defs/InputTokenPricing'
                      output_tokens:
                        $ref: '#/$defs/OutputTokenPricing'
                    required:
                    - above_input_tokens
                  InputTokenPricing:
                    description: Input token pricing per million tokens.
                    type: object
                    properties:
                      cache_read:
                        description: Cost per million cache-read input tokens.
                        type:
                        - number
                        - 'null'
                        format: double
                      cache_write:
                        description: Cost per million cache-write input tokens.
                        type:
                        - number
                        - 'null'
                        format: double
                      no_cache:
                        description: Cost per million non-cached input tokens.
                        type:
                        - number
                        - 'null'
                        format: double
                  ModelPricing:
                    description: |-
                      Token pricing per million tokens for a model.

                      `input_tokens`/`output_tokens` are the **base bracket**: the rates for the
                      lowest context range and the fallback when no [`context_tiers`] entry
                      applies. When `context_tiers` is empty the pricing is a single flat rate
                      for every request size (the historical behaviour).

                      [`context_tiers`]: ModelPricing::context_tiers
                    type: object
                    properties:
                      context_tiers:
                        description: |-
                          Optional higher context brackets. Empty ⇒ flat pricing. The registry
                          validator enforces ascending, unique `above_input_tokens` and a
                          complete base bracket, so the per-request resolver does not depend on
                          list order.
                        type: array
                        items:
                          $ref: '#/$defs/ContextTier'
                      input_tokens:
                        $ref: '#/$defs/InputTokenPricing'
                      output_tokens:
                        $ref: '#/$defs/OutputTokenPricing'
                  OutputTokenPricing:
                    description: Output token pricing per million tokens.
                    type: object
                    properties:
                      audio:
                        description: Cost per million audio output tokens. Reserved — see `image`.
                        type:
                        - number
                        - 'null'
                        format: double
                      image:
                        description: |-
                          Cost per million image output tokens. Reserved — not yet wired
                          into `calculate_charge_micro_usd`.
                        type:
                        - number
                        - 'null'
                        format: double
                      reasoning:
                        description: Cost per million reasoning output tokens.
                        type:
                        - number
                        - 'null'
                        format: double
                      text:
                        description: Cost per million text output tokens.
                        type:
                        - number
                        - 'null'
                        format: double
                  ProviderAggregateMetrics:
                    type: object
                    properties:
                      cache_hit_rate:
                        type: number
                        format: double
                      p50_latency_ms:
                        description: |-
                          Request-weighted average of per-model p50 latencies. Not a true
                          cross-bucket p50 (that would need a separate query), but cheap
                          and close enough for a discovery panel.
                        type: integer
                        format: uint64
                        minimum: 0
                      request_count:
                        type: integer
                        format: uint64
                        minimum: 0
                      success_rate:
                        description: |-
                          Successful responses divided by (success + provider_error +
                          timeout). 0.0 when no scored requests fell in the window.
                        type: number
                        format: double
                    required:
                    - request_count
                    - success_rate
                    - p50_latency_ms
                    - cache_hit_rate
                  ProviderCatalogEntry:
                    description: One provider as it appears to public discovery clients.
                    type: object
                    properties:
                      aggregate:
                        $ref: '#/$defs/ProviderAggregateMetrics'
                      byok:
                        description: |-
                          `true` when a caller may bring their own key for this provider
                          (registry `byok`, default true — every publicly-registerable
                          upstream). `false` for non-self-registerable providers (the
                          platform pool / aggregators), which route platform-only.
                        type: boolean
                      community:
                        description: |-
                          `true` for an unaffiliated community reseller; `false` (default) for
                          a first-party or official upstream.
                        type: boolean
                      id:
                        description: 'Stable public handle: the provider''s registry name.'
                        type: string
                      metrics_window_seconds:
                        type: integer
                        format: uint64
                        minimum: 0
                      models:
                        type: array
                        items:
                          $ref: '#/$defs/ProviderModelCatalogEntry'
                      name:
                        description: |-
                          Human-readable provider name. Always present — providers are no
                          longer anonymized.
                        type: string
                      rate_limit:
                        $ref: '#/$defs/ProviderRateLimit'
                      status:
                        $ref: '#/$defs/ProviderStatus'
                    required:
                    - id
                    - name
                    - community
                    - byok
                    - status
                    - rate_limit
                    - metrics_window_seconds
                    - aggregate
                    - models
                  ProviderModelCatalogEntry:
                    type: object
                    properties:
                      id:
                        description: |-
                          Canonical model id (e.g. `claude-sonnet-4-6`). The vendor's own
                          `provider_model_id` is deliberately not exposed.
                        type: string
                      metrics:
                        $ref: '#/$defs/ProviderModelMetrics'
                      pricing:
                        $ref: '#/$defs/ModelPricing'
                    required:
                    - id
                    - pricing
                    - metrics
                  ProviderModelMetrics:
                    type: object
                    properties:
                      p50_latency_ms:
                        type: integer
                        format: uint64
                        minimum: 0
                      request_count:
                        type: integer
                        format: uint64
                        minimum: 0
                      success_rate:
                        type: number
                        format: double
                    required:
                    - request_count
                    - success_rate
                    - p50_latency_ms
                  ProviderRateLimit:
                    type: object
                    properties:
                      current_rpm:
                        description: In-process sliding-window admission count for this provider.
                        type: integer
                        format: uint32
                        minimum: 0
                      declared_rpm:
                        description: |-
                          Provider-wide declared RPM from the wildcard `*` pattern in
                          `rate_limits`. Omitted when the provider's YAML declares no
                          wildcard entry — per-model overrides are intentionally not
                          surfaced, since the response shape is one rate per provider.
                        type:
                        - integer
                        - 'null'
                        format: uint32
                        minimum: 0
                    required:
                    - current_rpm
                  ProviderStatus:
                    description: Provider lifecycle state.
                    type: string
                    enum:
                    - active
                    - staging
                    - suspended
                    - withdrawn
  /v1/byok/encryption-pubkey:
    get:
      tags:
      - BYOK
      summary: Get BYOK sealed-box public key
      description: |-
        Returns the node's current X25519 sealed-box public key plus its `kek_id` fingerprint. The console encrypts the user's provider key against this pubkey before storing the ciphertext — the node never sees plaintext on the write path.

        Honors `If-None-Match: "<kek_id>"` for cheap caching, returning `304 Not Modified` when the cached fingerprint still matches.
      operationId: getEncryptionPubkey
      parameters:
      - in: header
        name: If-None-Match
        description: Quoted `kek_id` from a prior response.
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Current sealed-box public key.
          headers:
            ETag:
              description: Quoted `kek_id` of the returned key.
              style: simple
              schema:
                type: string
            Cache-Control:
              description: '`private, max-age=300` — encourages a 5-minute client cache.'
              style: simple
              schema:
                type: string
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: EncryptionPubkeyResponse
                description: |-
                  Response body for `GET /v1/byok/encryption-pubkey`. Carries the current
                  sealed-box public key plus its fingerprint so the console can encrypt
                  provider keys against it.
                type: object
                properties:
                  kek_id:
                    description: |-
                      Fingerprint of the current sealed-box keypair. Pin this when caching;
                      pass it back via `If-None-Match` to short-circuit on `304 Not Modified`.
                    type: string
                  public_key:
                    description: |-
                      Base64-encoded X25519 public key. Use it with libsodium's `crypto_box_seal`
                      (or any sealed-box implementation) to encrypt provider keys client-side.
                    type: string
                required:
                - kek_id
                - public_key
        '304':
          description: Cached `kek_id` still matches — body is empty.
  /v1/namespaces:
    get:
      tags:
      - Management
      summary: List the caller's namespaces
      description: |-
        Every live namespace owned by the calling user, oldest first.

        _Requires the `namespace:read` scope._
      operationId: listNamespaces
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    post:
      tags:
      - Management
      summary: Create a namespace
      description: |-
        Creates a namespace owned by the caller. The name must be unique among the caller's live namespaces (409 on collision).

        _Requires the `namespace:write` scope._
      operationId: createNamespace
      requestBody:
        description: Request body. See the endpoint description for shape.
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}:
    delete:
      tags:
      - Management
      summary: Delete a namespace and cascade its resources
      description: |-
        Ownership-checked. Refuses the caller's last namespace (409). Destroys the namespace's keys, OAuth tokens/clients, and policies; archives the row; detaches usage history. The wallet and BYOK keys (user-keyed) are retained.

        _Requires the `namespace:write` scope._
      operationId: deleteNamespace
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/account:
    get:
      tags:
      - Management
      summary: Read the caller's user profile
      description: |-
        Returns id, email, display_name, created_at.

        _Requires the `user:read` scope._
      operationId: getAccount
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    delete:
      tags:
      - Management
      summary: Delete the caller's account
      description: |-
        Rust-first account deletion: destroys every credential under the user (API keys, OAuth tokens/clients, BYOK keys), archives all owned namespaces, and tombstones the IdP subject so the account cannot be re-provisioned. Irreversible; the caller's own session is revoked.

        _Requires the `user:write` scope._
      operationId: deleteAccount
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    patch:
      tags:
      - Management
      summary: Update the caller's profile
      description: |-
        Edits the one user-mutable field, `display_name`. `email` and the IdP identifier are read-only here.

        _Requires the `user:write` scope._
      operationId: updateAccount
      requestBody:
        description: Request body. See the endpoint description for shape.
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/billing/balance:
    get:
      tags:
      - Management
      summary: Credit account balance
      description: |-
        Returns the raw balance, pending debits, and effective available amount in micro-USD.

        _Requires the `billing:read` scope._
      operationId: getBillingBalance
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/billing/transactions:
    get:
      tags:
      - Management
      summary: Paginated credit ledger history
      description: |-
        Credit ledger entries (topups, usage debits, refunds), newest first. `amount_micro_usd` is signed: positive for credits, negative for debits.

        _Requires the `billing:read` scope._
      operationId: listBillingTransactions
      parameters:
      - in: query
        name: limit
        description: Page size. Default 25, max 100.
        schema:
          type: string
        style: form
      - in: query
        name: offset
        description: Offset within the newest-first listing.
        schema:
          type: string
        style: form
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/billing/checkout/sessions:
    post:
      tags:
      - Management
      summary: Create a Stripe Checkout Session
      description: |-
        Creates a Stripe Checkout Session to buy credits. Returns the hosted URL the user must visit to complete payment.

        _Requires the `billing:write` scope._
      operationId: createCheckoutSession
      requestBody:
        description: Request body. See the endpoint description for shape.
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/byok/keys:
    get:
      tags:
      - Management
      summary: List BYOK provider keys
      description: |-
        Metadata-only — never returns the sealed ciphertext.

        _Requires the `byok:read` scope._
      operationId: listByokKeys
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    post:
      tags:
      - Management
      summary: Upsert a BYOK provider key
      description: |-
        Stores a sealed-box ciphertext for one provider. Refuses any payload sealed against a `kek_id` other than the cloud's current encryption pubkey (`/v1/byok/encryption-pubkey`).

        _Requires the `byok:write` scope._
      operationId: upsertByokKey
      requestBody:
        description: Request body. See the endpoint description for shape.
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/byok/keys/{provider}:
    delete:
      tags:
      - Management
      summary: Delete a BYOK provider key
      description: |2-


        _Requires the `byok:write` scope._
      operationId: deleteByokKey
      parameters:
      - in: path
        name: provider
        description: Provider name as registered in the cloud's provider catalog.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/keys:
    get:
      tags:
      - Management
      summary: List API keys for the calling account
      description: |-
        Account-scoped list of brk_ API keys. Never returns the secret.

        _Requires the `keys:read` scope._
      operationId: listApiKeys
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    post:
      tags:
      - Management
      summary: Mint a new API key
      description: |-
        Mint a brk_ API key. Returns the plaintext token exactly once.

        The requested `scopes` must be a subset of the caller's effective scopes — no upscaling (RFC 6749 §3.3).

        _Requires the `keys:write` scope._
      operationId: mintApiKey
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Request body. See the endpoint description for shape.
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/keys/{id}:
    delete:
      tags:
      - Management
      summary: Revoke an API key
      description: |-
        Stamps `revoked_at` on the row. Subsequent verifies fail with 401.

        _Requires the `keys:write` scope._
      operationId: revokeApiKey
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the api_keys row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/usage:
    get:
      tags:
      - Management
      summary: Aggregate spend / tokens for a window
      description: |-
        Sums `usage` / `pending_debit_recovery` ledger entries and the `requests` rows over the window. Defaults to the last 30 days.

        _Requires the `usage:read` scope._
      operationId: getUsageAggregate
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: from
        description: Inclusive RFC 3339 timestamp lower bound.
        schema:
          type: string
        style: form
      - in: query
        name: to
        description: Exclusive RFC 3339 timestamp upper bound.
        schema:
          type: string
        style: form
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/requests:
    get:
      tags:
      - Management
      summary: Paginated request history
      description: |-
        Per-request metadata. Never includes the prompt or response body.

        _Requires the `usage:read` scope._
      operationId: listRequests
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: limit
        description: Page size. Default 25, max 100.
        schema:
          type: string
        style: form
      - in: query
        name: offset
        description: Offset within the newest-first listing.
        schema:
          type: string
        style: form
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/policies:
    get:
      tags:
      - Management
      summary: List account policies
      description: |2-


        _Requires the `policy:read` scope._
      operationId: listPolicies
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: kind
        description: Optional filter — `budget`, `rate_limit`, `guardrail`, or `preset`. Unknown values return 400.
        schema:
          type: string
        style: form
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    post:
      tags:
      - Management
      summary: Create a policy
      description: |-
        Create a `budget` / `rate_limit` / `guardrail` / `preset` policy. The `spec` body must match the requested `kind`.

        _Requires the `policy:write` scope._
      operationId: createPolicy
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Request body. See the endpoint description for shape.
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/policies/effective:
    get:
      tags:
      - Management
      summary: Preview the engine's effective policy for a principal
      description: |-
        Returns the engine's combined view (budgets, rate_limits, guardrail) without making a real inference request. The queried principal must belong to the caller's account.

        _Requires the `policy:read` scope._
      operationId: getEffectivePolicy
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: principal_type
        description: One of `namespace`, `api_key`, `oauth_token`, `oauth_client`.
        schema:
          type: string
        style: form
      - in: query
        name: principal_id
        description: Id of the principal. Must belong to the caller's account or 404.
        schema:
          type: string
        style: form
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/policies/{id}:
    get:
      tags:
      - Management
      summary: Read a single policy by id
      description: |-
        Returns the policy if it exists and belongs to the caller's account; 404 otherwise (no cross-tenant existence leak).

        _Requires the `policy:read` scope._
      operationId: getPolicy
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `policies` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    put:
      tags:
      - Management
      summary: Update a policy's name or spec
      description: |-
        In-place update of a policy's `name` and / or `spec`. Kind changes are not supported — recreate the policy if the kind needs to differ.

        _Requires the `policy:write` scope._
      operationId: updatePolicy
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Request body. See the endpoint description for shape.
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    delete:
      tags:
      - Management
      summary: Delete a policy and its bindings
      description: |2-


        _Requires the `policy:write` scope._
      operationId: deletePolicy
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `policies` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/policies/{id}/bind:
    post:
      tags:
      - Management
      summary: Bind a policy to a principal
      description: |-
        Attaches the policy to a principal (account / api_key / oauth_token / oauth_client). The engine sums all bindings most-restrictive-wins at request time.

        _Requires the `policy:write` scope._
      operationId: bindPolicy
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Request body. See the endpoint description for shape.
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/policies/{id}/bind/{binding_id}:
    delete:
      tags:
      - Management
      summary: Remove a policy binding
      description: |2-


        _Requires the `policy:write` scope._
      operationId: unbindPolicy
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the policy.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: binding_id
        description: Surrogate id of the binding row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/policies/{id}/disable:
    post:
      tags:
      - Management
      summary: Park a policy without deleting it
      description: |-
        Stamps `disabled_at = now()`. The engine skips disabled rows when computing effective policy; the management surface still surfaces them so an operator can re-enable. Idempotent — re-disabling returns 200.

        _Requires the `policy:write` scope._
      operationId: disablePolicy
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `policies` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/policies/{id}/enable:
    post:
      tags:
      - Management
      summary: Re-enable a previously disabled policy
      description: |-
        Clears `disabled_at`. The engine starts honouring the row again on the next request. Idempotent.

        _Requires the `policy:write` scope._
      operationId: enablePolicy
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `policies` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/policies/{id}/bindings:
    get:
      tags:
      - Management
      summary: List bindings attached to one policy
      description: |-
        Returns every binding referencing the policy. The policy must belong to the caller's account or 404 is returned.

        _Requires the `policy:read` scope._
      operationId: listPolicyBindings
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `policies` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/principals/{principal_type}/{principal_id}/policies:
    get:
      tags:
      - Management
      summary: List policies bound to a principal
      description: |-
        Returns every policy directly bound to the named principal. The principal must belong to the caller's account — mismatch returns 404 (no cross-tenant enumeration).

        _Requires the `policy:read` scope._
      operationId: listPrincipalPolicies
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: principal_type
        description: One of `namespace`, `api_key`, `oauth_token`, `oauth_client`.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: principal_id
        description: Id of the principal. Must belong to the caller's account or 404.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/budgets:
    get:
      tags:
      - Management
      summary: List the account's budget policies
      description: |-
        Typed list of `kind = 'budget'` rows. Same storage as `/v1/policies?kind=budget` but the response carries flat budget objects instead of `{ kind, spec }` envelopes.

        _Requires the `policy:read` scope._
      operationId: listBudgets
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Budget list.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: BudgetListResponse
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/$defs/BudgetEnvelope'
                required:
                - data
                $defs:
                  BudgetEnvelope:
                    description: |-
                      One budget as it appears on the wire. The shape is flat — no
                      `kind`/`spec` envelope — because this endpoint only ever produces
                      budgets.
                    type: object
                    properties:
                      disabled_at:
                        description: |-
                          `None` for enabled rows. See
                          [`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]
                          for semantics — toggle via `POST /v1/policies/{id}/disable`
                          / `/enable`.
                        type:
                        - string
                        - 'null'
                        format: date-time
                      id:
                        type: string
                      limit_micro_usd:
                        type: integer
                        format: int64
                      name:
                        type: string
                      window:
                        $ref: '#/$defs/BudgetWindow'
                    required:
                    - id
                    - name
                    - window
                    - limit_micro_usd
                  BudgetWindow:
                    description: |-
                      A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                      time-bucket query against `credit_ledger_entries`.
                    oneOf:
                    - description: 24 hours rolling.
                      type: string
                      const: day
                    - description: 30 days rolling.
                      type: string
                      const: month
                    - description: Lifetime — accumulates indefinitely.
                      type: string
                      const: total
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    post:
      tags:
      - Management
      summary: Create a budget policy
      description: |-
        Creates a new budget. `limit_micro_usd` must be strictly positive — the engine treats `<= 0` as "no policy", so the API refuses the value up-front.

        _Requires the `policy:write` scope._
      operationId: createBudget
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Budget request body.
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              title: CreateBudgetRequest
              type: object
              properties:
                limit_micro_usd:
                  description: |-
                    Spend cap in micro-USD. Must be strictly positive — the
                    engine treats `<= 0` as "no policy" so the API refuses the
                    pathological value up-front.
                  type: integer
                  format: int64
                name:
                  type: string
                window:
                  $ref: '#/$defs/BudgetWindow'
              required:
              - name
              - window
              - limit_micro_usd
              $defs:
                BudgetWindow:
                  description: |-
                    A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                    time-bucket query against `credit_ledger_entries`.
                  oneOf:
                  - description: 24 hours rolling.
                    type: string
                    const: day
                  - description: 30 days rolling.
                    type: string
                    const: month
                  - description: Lifetime — accumulates indefinitely.
                    type: string
                    const: total
        required: true
      responses:
        '200':
          description: Created budget.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: BudgetEnvelope
                description: |-
                  One budget as it appears on the wire. The shape is flat — no
                  `kind`/`spec` envelope — because this endpoint only ever produces
                  budgets.
                type: object
                properties:
                  disabled_at:
                    description: |-
                      `None` for enabled rows. See
                      [`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]
                      for semantics — toggle via `POST /v1/policies/{id}/disable`
                      / `/enable`.
                    type:
                    - string
                    - 'null'
                    format: date-time
                  id:
                    type: string
                  limit_micro_usd:
                    type: integer
                    format: int64
                  name:
                    type: string
                  window:
                    $ref: '#/$defs/BudgetWindow'
                required:
                - id
                - name
                - window
                - limit_micro_usd
                $defs:
                  BudgetWindow:
                    description: |-
                      A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                      time-bucket query against `credit_ledger_entries`.
                    oneOf:
                    - description: 24 hours rolling.
                      type: string
                      const: day
                    - description: 30 days rolling.
                      type: string
                      const: month
                    - description: Lifetime — accumulates indefinitely.
                      type: string
                      const: total
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/budgets/{id}:
    get:
      tags:
      - Management
      summary: Read a budget by id
      description: |-
        Returns the budget if it exists, belongs to the caller's account, and has `kind = 'budget'`. Any other case yields 404 (no cross-kind or cross-tenant leak).

        _Requires the `policy:read` scope._
      operationId: getBudget
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `policies` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Budget row.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: BudgetEnvelope
                description: |-
                  One budget as it appears on the wire. The shape is flat — no
                  `kind`/`spec` envelope — because this endpoint only ever produces
                  budgets.
                type: object
                properties:
                  disabled_at:
                    description: |-
                      `None` for enabled rows. See
                      [`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]
                      for semantics — toggle via `POST /v1/policies/{id}/disable`
                      / `/enable`.
                    type:
                    - string
                    - 'null'
                    format: date-time
                  id:
                    type: string
                  limit_micro_usd:
                    type: integer
                    format: int64
                  name:
                    type: string
                  window:
                    $ref: '#/$defs/BudgetWindow'
                required:
                - id
                - name
                - window
                - limit_micro_usd
                $defs:
                  BudgetWindow:
                    description: |-
                      A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                      time-bucket query against `credit_ledger_entries`.
                    oneOf:
                    - description: 24 hours rolling.
                      type: string
                      const: day
                    - description: 30 days rolling.
                      type: string
                      const: month
                    - description: Lifetime — accumulates indefinitely.
                      type: string
                      const: total
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    put:
      tags:
      - Management
      summary: Update a budget's name, window, or limit
      description: |-
        Partial patch. Each field is optional; absent fields are left unchanged. A non-positive `limit_micro_usd` is refused.

        _Requires the `policy:write` scope._
      operationId: updateBudget
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `policies` row.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Budget patch.
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              title: UpdateBudgetRequest
              type: object
              properties:
                limit_micro_usd:
                  description: |-
                    New cap. `None` ⇒ unchanged. When set, must be strictly
                    positive.
                  type:
                  - integer
                  - 'null'
                  format: int64
                  default: null
                name:
                  description: New name. `None` ⇒ unchanged.
                  type:
                  - string
                  - 'null'
                  default: null
                window:
                  description: New window. `None` ⇒ unchanged.
                  anyOf:
                  - $ref: '#/$defs/BudgetWindow'
                  - type: 'null'
                  default: null
              $defs:
                BudgetWindow:
                  description: |-
                    A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                    time-bucket query against `credit_ledger_entries`.
                  oneOf:
                  - description: 24 hours rolling.
                    type: string
                    const: day
                  - description: 30 days rolling.
                    type: string
                    const: month
                  - description: Lifetime — accumulates indefinitely.
                    type: string
                    const: total
        required: true
      responses:
        '200':
          description: Updated budget.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: BudgetEnvelope
                description: |-
                  One budget as it appears on the wire. The shape is flat — no
                  `kind`/`spec` envelope — because this endpoint only ever produces
                  budgets.
                type: object
                properties:
                  disabled_at:
                    description: |-
                      `None` for enabled rows. See
                      [`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]
                      for semantics — toggle via `POST /v1/policies/{id}/disable`
                      / `/enable`.
                    type:
                    - string
                    - 'null'
                    format: date-time
                  id:
                    type: string
                  limit_micro_usd:
                    type: integer
                    format: int64
                  name:
                    type: string
                  window:
                    $ref: '#/$defs/BudgetWindow'
                required:
                - id
                - name
                - window
                - limit_micro_usd
                $defs:
                  BudgetWindow:
                    description: |-
                      A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                      time-bucket query against `credit_ledger_entries`.
                    oneOf:
                    - description: 24 hours rolling.
                      type: string
                      const: day
                    - description: 30 days rolling.
                      type: string
                      const: month
                    - description: Lifetime — accumulates indefinitely.
                      type: string
                      const: total
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    delete:
      tags:
      - Management
      summary: Delete a budget and its bindings
      description: |-
        Refuses to delete a row whose kind is not `budget` (returns 404). Bindings on the row cascade via the same path as the generic delete.

        _Requires the `policy:write` scope._
      operationId: deleteBudget
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `policies` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Delete acknowledgement.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: DeleteBudgetResponse
                type: object
                properties:
                  deleted:
                    type: boolean
                required:
                - deleted
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/presets:
    get:
      tags:
      - Management
      summary: List the account's preset bundles
      description: |-
        Typed list of `kind = 'preset'` rows. Each preset carries optional `guardrail`, `budget`, and `rate_limit` clauses.

        _Requires the `policy:read` scope._
      operationId: listPresets
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Preset list.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: PresetListResponse
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/$defs/PresetEnvelope'
                required:
                - data
                $defs:
                  Action:
                    description: What to do when a rule matches.
                    oneOf:
                    - description: |-
                        Block the content — upstream this is a 400 deny, downstream a stream
                        abort. The default when a rule omits its action (block is the safe one).
                      type: string
                      const: block
                    - description: Redact the matched span — replace it with the redaction placeholder.
                      type: string
                      const: redact
                  BudgetSpec:
                    description: |-
                      A spend cap over a rolling window. Spend is measured in
                      micro-USD — the same unit the credit ledger uses, so engine code
                      can sum `credit_ledger_entries.amount_micro_usd` directly.
                    type: object
                    properties:
                      limit_micro_usd:
                        description: |-
                          Spend cap in micro-USD. Must be positive; a non-positive cap
                          would deny every request and is treated as "no policy" by the
                          engine (it's clamped out during validation in a later phase
                          when CRUD lands).
                        type: integer
                        format: int64
                      window:
                        $ref: '#/$defs/BudgetWindow'
                    required:
                    - window
                    - limit_micro_usd
                  BudgetWindow:
                    description: |-
                      A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                      time-bucket query against `credit_ledger_entries`.
                    oneOf:
                    - description: 24 hours rolling.
                      type: string
                      const: day
                    - description: 30 days rolling.
                      type: string
                      const: month
                    - description: Lifetime — accumulates indefinitely.
                      type: string
                      const: total
                  ByokRequirement:
                    description: |-
                      Strictness requirement on bring-your-own-key usage for the
                      inference call. Mapped from the caller's per-provider BYOK key.
                    oneOf:
                    - description: |-
                        The request MUST be served via a BYOK provider key. Used by
                        teams who never want platform credits to be spent.
                      type: string
                      const: required
                    - description: |-
                        The request MUST NOT be served via a BYOK key. Useful for
                        suppressing accidental BYOK shadowing on shared namespaces.
                      type: string
                      const: forbidden
                    - description: Either path is acceptable. Equivalent to no constraint.
                      type: string
                      const: optional
                  GuardrailSpec:
                    description: |-
                      Per-request constraints on the inference call (model allowlists,
                      max generation length, streaming / BYOK switches). Each field is
                      optional; an unset axis adds no constraint.
                    type: object
                    properties:
                      allow_streaming:
                        description: |-
                          Permit-only one-way gate on streaming responses.
                          `Some(false)` forbids streaming: a request with `stream: true`
                          is denied. `Some(true)` and `None` both permit streaming
                          (`Some(true)` is the explicit "no constraint here" form;
                          `None` is the absence of any opinion). Guardrails cannot
                          *require* streaming — there is no way to refuse a
                          `stream: false` request via this field. The combiner
                          ([`crate::policy::engine`]) is forbid-wins for the same
                          reason: the union of permits is still a permit, and any one
                          `Some(false)` makes the effective policy a forbid.
                        type:
                        - boolean
                        - 'null'
                      byok:
                        description: |-
                          BYOK posture (see [`ByokRequirement`]). `None` = no
                          constraint.
                        anyOf:
                        - $ref: '#/$defs/ByokRequirement'
                        - type: 'null'
                      content_patterns:
                        description: |-
                          Content-firewall rules: regex `block` / `redact` patterns run over
                          the request prompt and the response stream by the
                          `bitrouter-guardrails` hooks. Empty = no content filtering. Combined
                          as a union across policies (every rule from every applicable policy
                          applies — more rules is strictly more restrictive).
                        type: array
                        items:
                          $ref: '#/$defs/RuleSpec'
                      max_request_tokens:
                        description: |-
                          Hard cap on the request's `prompt.params.max_tokens`. When
                          the request leaves `max_tokens` unset, the call is admitted —
                          the engine can't enforce a cap on an undeclared value.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      model_allow:
                        description: |-
                          If set, only these (canonical) model ids may be requested.
                          An empty allowlist denies every model — same as no policy.
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                      model_deny:
                        description: |-
                          If set, these model ids are explicitly refused even when the
                          allowlist would otherwise admit them. Deny wins over allow.
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                  PresetEnvelope:
                    description: |-
                      One preset as it appears on the wire. The sub-policy fields are
                      optional so an empty preset (no clauses) is representable; the
                      engine ignores empty presets at request time so this is a no-op
                      row rather than a denial.
                    type: object
                    properties:
                      budget:
                        anyOf:
                        - $ref: '#/$defs/BudgetSpec'
                        - type: 'null'
                      disabled_at:
                        description: |-
                          `None` for enabled rows. See
                          [`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]
                          for semantics — toggle via `POST /v1/policies/{id}/disable`
                          / `/enable`.
                        type:
                        - string
                        - 'null'
                        format: date-time
                      guardrail:
                        anyOf:
                        - $ref: '#/$defs/GuardrailSpec'
                        - type: 'null'
                      id:
                        type: string
                      name:
                        type: string
                      rate_limit:
                        anyOf:
                        - $ref: '#/$defs/RateLimitSpec'
                        - type: 'null'
                    required:
                    - id
                    - name
                  RateLimitSpec:
                    description: |-
                      A request-frequency cap over a sliding window. Enforced with
                      Redis counters keyed per principal + window. At least one of
                      `max_requests` / `max_tokens` must be set for the policy to bite.
                    type: object
                    properties:
                      max_requests:
                        description: Hard cap on completed (admitted) requests in the window.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      max_tokens:
                        description: |-
                          Hard cap on the caller's declared prompt-token budget
                          (`prompt.params.max_tokens`) in the window. Optional — most
                          rate-limit policies in practice only cap request rate.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      window_secs:
                        description: Sliding-window width in seconds. Must be positive.
                        type: integer
                        format: int64
                    required:
                    - window_secs
                  RuleSpec:
                    description: |-
                      One guardrail rule in serializable form: a name, a regex pattern, and a
                      match action. Compile it into a runtime rule with `RuleSpec::compile`.
                    type: object
                    properties:
                      action:
                        description: What to do on a match. Defaults to `block` when omitted.
                        $ref: '#/$defs/Action'
                        default: block
                      name:
                        description: Human-readable rule name (surfaced in deny reasons / logs).
                        type: string
                      pattern:
                        description: The regex pattern to match.
                        type: string
                    required:
                    - name
                    - pattern
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    post:
      tags:
      - Management
      summary: Create a preset bundle
      description: |-
        Creates a named bundle of sub-policies. Validation is stricter than the generic create: a rate-limit clause must declare at least one of `max_requests` / `max_tokens`, and `budget.limit_micro_usd` must be strictly positive.

        _Requires the `policy:write` scope._
      operationId: createPreset
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Preset request body.
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              title: CreatePresetRequest
              type: object
              properties:
                budget:
                  anyOf:
                  - $ref: '#/$defs/BudgetSpec'
                  - type: 'null'
                  default: null
                guardrail:
                  anyOf:
                  - $ref: '#/$defs/GuardrailSpec'
                  - type: 'null'
                  default: null
                name:
                  type: string
                rate_limit:
                  anyOf:
                  - $ref: '#/$defs/RateLimitSpec'
                  - type: 'null'
                  default: null
              required:
              - name
              $defs:
                Action:
                  description: What to do when a rule matches.
                  oneOf:
                  - description: |-
                      Block the content — upstream this is a 400 deny, downstream a stream
                      abort. The default when a rule omits its action (block is the safe one).
                    type: string
                    const: block
                  - description: Redact the matched span — replace it with the redaction placeholder.
                    type: string
                    const: redact
                BudgetSpec:
                  description: |-
                    A spend cap over a rolling window. Spend is measured in
                    micro-USD — the same unit the credit ledger uses, so engine code
                    can sum `credit_ledger_entries.amount_micro_usd` directly.
                  type: object
                  properties:
                    limit_micro_usd:
                      description: |-
                        Spend cap in micro-USD. Must be positive; a non-positive cap
                        would deny every request and is treated as "no policy" by the
                        engine (it's clamped out during validation in a later phase
                        when CRUD lands).
                      type: integer
                      format: int64
                    window:
                      $ref: '#/$defs/BudgetWindow'
                  required:
                  - window
                  - limit_micro_usd
                BudgetWindow:
                  description: |-
                    A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                    time-bucket query against `credit_ledger_entries`.
                  oneOf:
                  - description: 24 hours rolling.
                    type: string
                    const: day
                  - description: 30 days rolling.
                    type: string
                    const: month
                  - description: Lifetime — accumulates indefinitely.
                    type: string
                    const: total
                ByokRequirement:
                  description: |-
                    Strictness requirement on bring-your-own-key usage for the
                    inference call. Mapped from the caller's per-provider BYOK key.
                  oneOf:
                  - description: |-
                      The request MUST be served via a BYOK provider key. Used by
                      teams who never want platform credits to be spent.
                    type: string
                    const: required
                  - description: |-
                      The request MUST NOT be served via a BYOK key. Useful for
                      suppressing accidental BYOK shadowing on shared namespaces.
                    type: string
                    const: forbidden
                  - description: Either path is acceptable. Equivalent to no constraint.
                    type: string
                    const: optional
                GuardrailSpec:
                  description: |-
                    Per-request constraints on the inference call (model allowlists,
                    max generation length, streaming / BYOK switches). Each field is
                    optional; an unset axis adds no constraint.
                  type: object
                  properties:
                    allow_streaming:
                      description: |-
                        Permit-only one-way gate on streaming responses.
                        `Some(false)` forbids streaming: a request with `stream: true`
                        is denied. `Some(true)` and `None` both permit streaming
                        (`Some(true)` is the explicit "no constraint here" form;
                        `None` is the absence of any opinion). Guardrails cannot
                        *require* streaming — there is no way to refuse a
                        `stream: false` request via this field. The combiner
                        ([`crate::policy::engine`]) is forbid-wins for the same
                        reason: the union of permits is still a permit, and any one
                        `Some(false)` makes the effective policy a forbid.
                      type:
                      - boolean
                      - 'null'
                    byok:
                      description: |-
                        BYOK posture (see [`ByokRequirement`]). `None` = no
                        constraint.
                      anyOf:
                      - $ref: '#/$defs/ByokRequirement'
                      - type: 'null'
                    content_patterns:
                      description: |-
                        Content-firewall rules: regex `block` / `redact` patterns run over
                        the request prompt and the response stream by the
                        `bitrouter-guardrails` hooks. Empty = no content filtering. Combined
                        as a union across policies (every rule from every applicable policy
                        applies — more rules is strictly more restrictive).
                      type: array
                      items:
                        $ref: '#/$defs/RuleSpec'
                    max_request_tokens:
                      description: |-
                        Hard cap on the request's `prompt.params.max_tokens`. When
                        the request leaves `max_tokens` unset, the call is admitted —
                        the engine can't enforce a cap on an undeclared value.
                      type:
                      - integer
                      - 'null'
                      format: int64
                    model_allow:
                      description: |-
                        If set, only these (canonical) model ids may be requested.
                        An empty allowlist denies every model — same as no policy.
                      type:
                      - array
                      - 'null'
                      items:
                        type: string
                    model_deny:
                      description: |-
                        If set, these model ids are explicitly refused even when the
                        allowlist would otherwise admit them. Deny wins over allow.
                      type:
                      - array
                      - 'null'
                      items:
                        type: string
                RateLimitSpec:
                  description: |-
                    A request-frequency cap over a sliding window. Enforced with
                    Redis counters keyed per principal + window. At least one of
                    `max_requests` / `max_tokens` must be set for the policy to bite.
                  type: object
                  properties:
                    max_requests:
                      description: Hard cap on completed (admitted) requests in the window.
                      type:
                      - integer
                      - 'null'
                      format: int64
                    max_tokens:
                      description: |-
                        Hard cap on the caller's declared prompt-token budget
                        (`prompt.params.max_tokens`) in the window. Optional — most
                        rate-limit policies in practice only cap request rate.
                      type:
                      - integer
                      - 'null'
                      format: int64
                    window_secs:
                      description: Sliding-window width in seconds. Must be positive.
                      type: integer
                      format: int64
                  required:
                  - window_secs
                RuleSpec:
                  description: |-
                    One guardrail rule in serializable form: a name, a regex pattern, and a
                    match action. Compile it into a runtime rule with `RuleSpec::compile`.
                  type: object
                  properties:
                    action:
                      description: What to do on a match. Defaults to `block` when omitted.
                      $ref: '#/$defs/Action'
                      default: block
                    name:
                      description: Human-readable rule name (surfaced in deny reasons / logs).
                      type: string
                    pattern:
                      description: The regex pattern to match.
                      type: string
                  required:
                  - name
                  - pattern
        required: true
      responses:
        '200':
          description: Created preset.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: PresetEnvelope
                description: |-
                  One preset as it appears on the wire. The sub-policy fields are
                  optional so an empty preset (no clauses) is representable; the
                  engine ignores empty presets at request time so this is a no-op
                  row rather than a denial.
                type: object
                properties:
                  budget:
                    anyOf:
                    - $ref: '#/$defs/BudgetSpec'
                    - type: 'null'
                  disabled_at:
                    description: |-
                      `None` for enabled rows. See
                      [`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]
                      for semantics — toggle via `POST /v1/policies/{id}/disable`
                      / `/enable`.
                    type:
                    - string
                    - 'null'
                    format: date-time
                  guardrail:
                    anyOf:
                    - $ref: '#/$defs/GuardrailSpec'
                    - type: 'null'
                  id:
                    type: string
                  name:
                    type: string
                  rate_limit:
                    anyOf:
                    - $ref: '#/$defs/RateLimitSpec'
                    - type: 'null'
                required:
                - id
                - name
                $defs:
                  Action:
                    description: What to do when a rule matches.
                    oneOf:
                    - description: |-
                        Block the content — upstream this is a 400 deny, downstream a stream
                        abort. The default when a rule omits its action (block is the safe one).
                      type: string
                      const: block
                    - description: Redact the matched span — replace it with the redaction placeholder.
                      type: string
                      const: redact
                  BudgetSpec:
                    description: |-
                      A spend cap over a rolling window. Spend is measured in
                      micro-USD — the same unit the credit ledger uses, so engine code
                      can sum `credit_ledger_entries.amount_micro_usd` directly.
                    type: object
                    properties:
                      limit_micro_usd:
                        description: |-
                          Spend cap in micro-USD. Must be positive; a non-positive cap
                          would deny every request and is treated as "no policy" by the
                          engine (it's clamped out during validation in a later phase
                          when CRUD lands).
                        type: integer
                        format: int64
                      window:
                        $ref: '#/$defs/BudgetWindow'
                    required:
                    - window
                    - limit_micro_usd
                  BudgetWindow:
                    description: |-
                      A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                      time-bucket query against `credit_ledger_entries`.
                    oneOf:
                    - description: 24 hours rolling.
                      type: string
                      const: day
                    - description: 30 days rolling.
                      type: string
                      const: month
                    - description: Lifetime — accumulates indefinitely.
                      type: string
                      const: total
                  ByokRequirement:
                    description: |-
                      Strictness requirement on bring-your-own-key usage for the
                      inference call. Mapped from the caller's per-provider BYOK key.
                    oneOf:
                    - description: |-
                        The request MUST be served via a BYOK provider key. Used by
                        teams who never want platform credits to be spent.
                      type: string
                      const: required
                    - description: |-
                        The request MUST NOT be served via a BYOK key. Useful for
                        suppressing accidental BYOK shadowing on shared namespaces.
                      type: string
                      const: forbidden
                    - description: Either path is acceptable. Equivalent to no constraint.
                      type: string
                      const: optional
                  GuardrailSpec:
                    description: |-
                      Per-request constraints on the inference call (model allowlists,
                      max generation length, streaming / BYOK switches). Each field is
                      optional; an unset axis adds no constraint.
                    type: object
                    properties:
                      allow_streaming:
                        description: |-
                          Permit-only one-way gate on streaming responses.
                          `Some(false)` forbids streaming: a request with `stream: true`
                          is denied. `Some(true)` and `None` both permit streaming
                          (`Some(true)` is the explicit "no constraint here" form;
                          `None` is the absence of any opinion). Guardrails cannot
                          *require* streaming — there is no way to refuse a
                          `stream: false` request via this field. The combiner
                          ([`crate::policy::engine`]) is forbid-wins for the same
                          reason: the union of permits is still a permit, and any one
                          `Some(false)` makes the effective policy a forbid.
                        type:
                        - boolean
                        - 'null'
                      byok:
                        description: |-
                          BYOK posture (see [`ByokRequirement`]). `None` = no
                          constraint.
                        anyOf:
                        - $ref: '#/$defs/ByokRequirement'
                        - type: 'null'
                      content_patterns:
                        description: |-
                          Content-firewall rules: regex `block` / `redact` patterns run over
                          the request prompt and the response stream by the
                          `bitrouter-guardrails` hooks. Empty = no content filtering. Combined
                          as a union across policies (every rule from every applicable policy
                          applies — more rules is strictly more restrictive).
                        type: array
                        items:
                          $ref: '#/$defs/RuleSpec'
                      max_request_tokens:
                        description: |-
                          Hard cap on the request's `prompt.params.max_tokens`. When
                          the request leaves `max_tokens` unset, the call is admitted —
                          the engine can't enforce a cap on an undeclared value.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      model_allow:
                        description: |-
                          If set, only these (canonical) model ids may be requested.
                          An empty allowlist denies every model — same as no policy.
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                      model_deny:
                        description: |-
                          If set, these model ids are explicitly refused even when the
                          allowlist would otherwise admit them. Deny wins over allow.
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                  RateLimitSpec:
                    description: |-
                      A request-frequency cap over a sliding window. Enforced with
                      Redis counters keyed per principal + window. At least one of
                      `max_requests` / `max_tokens` must be set for the policy to bite.
                    type: object
                    properties:
                      max_requests:
                        description: Hard cap on completed (admitted) requests in the window.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      max_tokens:
                        description: |-
                          Hard cap on the caller's declared prompt-token budget
                          (`prompt.params.max_tokens`) in the window. Optional — most
                          rate-limit policies in practice only cap request rate.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      window_secs:
                        description: Sliding-window width in seconds. Must be positive.
                        type: integer
                        format: int64
                    required:
                    - window_secs
                  RuleSpec:
                    description: |-
                      One guardrail rule in serializable form: a name, a regex pattern, and a
                      match action. Compile it into a runtime rule with `RuleSpec::compile`.
                    type: object
                    properties:
                      action:
                        description: What to do on a match. Defaults to `block` when omitted.
                        $ref: '#/$defs/Action'
                        default: block
                      name:
                        description: Human-readable rule name (surfaced in deny reasons / logs).
                        type: string
                      pattern:
                        description: The regex pattern to match.
                        type: string
                    required:
                    - name
                    - pattern
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/presets/{id}:
    get:
      tags:
      - Management
      summary: Read a preset by id
      description: |-
        Returns the preset if it exists, belongs to the caller's account, and has `kind = 'preset'`. Any other case yields 404.

        _Requires the `policy:read` scope._
      operationId: getPreset
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `policies` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Preset row.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: PresetEnvelope
                description: |-
                  One preset as it appears on the wire. The sub-policy fields are
                  optional so an empty preset (no clauses) is representable; the
                  engine ignores empty presets at request time so this is a no-op
                  row rather than a denial.
                type: object
                properties:
                  budget:
                    anyOf:
                    - $ref: '#/$defs/BudgetSpec'
                    - type: 'null'
                  disabled_at:
                    description: |-
                      `None` for enabled rows. See
                      [`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]
                      for semantics — toggle via `POST /v1/policies/{id}/disable`
                      / `/enable`.
                    type:
                    - string
                    - 'null'
                    format: date-time
                  guardrail:
                    anyOf:
                    - $ref: '#/$defs/GuardrailSpec'
                    - type: 'null'
                  id:
                    type: string
                  name:
                    type: string
                  rate_limit:
                    anyOf:
                    - $ref: '#/$defs/RateLimitSpec'
                    - type: 'null'
                required:
                - id
                - name
                $defs:
                  Action:
                    description: What to do when a rule matches.
                    oneOf:
                    - description: |-
                        Block the content — upstream this is a 400 deny, downstream a stream
                        abort. The default when a rule omits its action (block is the safe one).
                      type: string
                      const: block
                    - description: Redact the matched span — replace it with the redaction placeholder.
                      type: string
                      const: redact
                  BudgetSpec:
                    description: |-
                      A spend cap over a rolling window. Spend is measured in
                      micro-USD — the same unit the credit ledger uses, so engine code
                      can sum `credit_ledger_entries.amount_micro_usd` directly.
                    type: object
                    properties:
                      limit_micro_usd:
                        description: |-
                          Spend cap in micro-USD. Must be positive; a non-positive cap
                          would deny every request and is treated as "no policy" by the
                          engine (it's clamped out during validation in a later phase
                          when CRUD lands).
                        type: integer
                        format: int64
                      window:
                        $ref: '#/$defs/BudgetWindow'
                    required:
                    - window
                    - limit_micro_usd
                  BudgetWindow:
                    description: |-
                      A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                      time-bucket query against `credit_ledger_entries`.
                    oneOf:
                    - description: 24 hours rolling.
                      type: string
                      const: day
                    - description: 30 days rolling.
                      type: string
                      const: month
                    - description: Lifetime — accumulates indefinitely.
                      type: string
                      const: total
                  ByokRequirement:
                    description: |-
                      Strictness requirement on bring-your-own-key usage for the
                      inference call. Mapped from the caller's per-provider BYOK key.
                    oneOf:
                    - description: |-
                        The request MUST be served via a BYOK provider key. Used by
                        teams who never want platform credits to be spent.
                      type: string
                      const: required
                    - description: |-
                        The request MUST NOT be served via a BYOK key. Useful for
                        suppressing accidental BYOK shadowing on shared namespaces.
                      type: string
                      const: forbidden
                    - description: Either path is acceptable. Equivalent to no constraint.
                      type: string
                      const: optional
                  GuardrailSpec:
                    description: |-
                      Per-request constraints on the inference call (model allowlists,
                      max generation length, streaming / BYOK switches). Each field is
                      optional; an unset axis adds no constraint.
                    type: object
                    properties:
                      allow_streaming:
                        description: |-
                          Permit-only one-way gate on streaming responses.
                          `Some(false)` forbids streaming: a request with `stream: true`
                          is denied. `Some(true)` and `None` both permit streaming
                          (`Some(true)` is the explicit "no constraint here" form;
                          `None` is the absence of any opinion). Guardrails cannot
                          *require* streaming — there is no way to refuse a
                          `stream: false` request via this field. The combiner
                          ([`crate::policy::engine`]) is forbid-wins for the same
                          reason: the union of permits is still a permit, and any one
                          `Some(false)` makes the effective policy a forbid.
                        type:
                        - boolean
                        - 'null'
                      byok:
                        description: |-
                          BYOK posture (see [`ByokRequirement`]). `None` = no
                          constraint.
                        anyOf:
                        - $ref: '#/$defs/ByokRequirement'
                        - type: 'null'
                      content_patterns:
                        description: |-
                          Content-firewall rules: regex `block` / `redact` patterns run over
                          the request prompt and the response stream by the
                          `bitrouter-guardrails` hooks. Empty = no content filtering. Combined
                          as a union across policies (every rule from every applicable policy
                          applies — more rules is strictly more restrictive).
                        type: array
                        items:
                          $ref: '#/$defs/RuleSpec'
                      max_request_tokens:
                        description: |-
                          Hard cap on the request's `prompt.params.max_tokens`. When
                          the request leaves `max_tokens` unset, the call is admitted —
                          the engine can't enforce a cap on an undeclared value.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      model_allow:
                        description: |-
                          If set, only these (canonical) model ids may be requested.
                          An empty allowlist denies every model — same as no policy.
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                      model_deny:
                        description: |-
                          If set, these model ids are explicitly refused even when the
                          allowlist would otherwise admit them. Deny wins over allow.
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                  RateLimitSpec:
                    description: |-
                      A request-frequency cap over a sliding window. Enforced with
                      Redis counters keyed per principal + window. At least one of
                      `max_requests` / `max_tokens` must be set for the policy to bite.
                    type: object
                    properties:
                      max_requests:
                        description: Hard cap on completed (admitted) requests in the window.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      max_tokens:
                        description: |-
                          Hard cap on the caller's declared prompt-token budget
                          (`prompt.params.max_tokens`) in the window. Optional — most
                          rate-limit policies in practice only cap request rate.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      window_secs:
                        description: Sliding-window width in seconds. Must be positive.
                        type: integer
                        format: int64
                    required:
                    - window_secs
                  RuleSpec:
                    description: |-
                      One guardrail rule in serializable form: a name, a regex pattern, and a
                      match action. Compile it into a runtime rule with `RuleSpec::compile`.
                    type: object
                    properties:
                      action:
                        description: What to do on a match. Defaults to `block` when omitted.
                        $ref: '#/$defs/Action'
                        default: block
                      name:
                        description: Human-readable rule name (surfaced in deny reasons / logs).
                        type: string
                      pattern:
                        description: The regex pattern to match.
                        type: string
                    required:
                    - name
                    - pattern
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    put:
      tags:
      - Management
      summary: Update a preset's name or clauses
      description: |-
        Partial patch. Each clause replacement is optional; an absent clause is left unchanged. Use the explicit `clear_guardrail` / `clear_budget` / `clear_rate_limit` flags to remove a clause — `null` body fields are NOT interpreted as clears.

        _Requires the `policy:write` scope._
      operationId: updatePreset
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `policies` row.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Preset patch.
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              title: UpdatePresetRequest
              description: |-
                Partial update for a preset. Each clause is independently
                optional: `None` means "leave this clause unchanged"; a
                JSON `null` (deserialised as `Some(None)` via
                `#[serde(default, with = "serde_with::rust::double_option")]`
                — not used here, see the explicit `clear_*` flags) is not
                supported. Use the explicit `clear_*` flags to remove a clause.

                This shape was chosen over `serde_with::double_option` because
                `Option<Option<T>>` is awkward for callers and the `clear_*`
                flag is unambiguous on the wire.
              type: object
              properties:
                budget:
                  description: Replace the budget clause. `None` ⇒ unchanged.
                  anyOf:
                  - $ref: '#/$defs/BudgetSpec'
                  - type: 'null'
                  default: null
                clear_budget:
                  type: boolean
                  default: false
                clear_guardrail:
                  description: |-
                    When true, drop the guardrail clause from the stored preset.
                    Overrides `guardrail` if both are present (the spec body
                    would have to be re-set on a subsequent PUT to add it back).
                  type: boolean
                  default: false
                clear_rate_limit:
                  type: boolean
                  default: false
                guardrail:
                  description: Replace the guardrail clause. `None` ⇒ unchanged.
                  anyOf:
                  - $ref: '#/$defs/GuardrailSpec'
                  - type: 'null'
                  default: null
                name:
                  description: New name. `None` ⇒ unchanged.
                  type:
                  - string
                  - 'null'
                  default: null
                rate_limit:
                  description: Replace the rate-limit clause. `None` ⇒ unchanged.
                  anyOf:
                  - $ref: '#/$defs/RateLimitSpec'
                  - type: 'null'
                  default: null
              $defs:
                Action:
                  description: What to do when a rule matches.
                  oneOf:
                  - description: |-
                      Block the content — upstream this is a 400 deny, downstream a stream
                      abort. The default when a rule omits its action (block is the safe one).
                    type: string
                    const: block
                  - description: Redact the matched span — replace it with the redaction placeholder.
                    type: string
                    const: redact
                BudgetSpec:
                  description: |-
                    A spend cap over a rolling window. Spend is measured in
                    micro-USD — the same unit the credit ledger uses, so engine code
                    can sum `credit_ledger_entries.amount_micro_usd` directly.
                  type: object
                  properties:
                    limit_micro_usd:
                      description: |-
                        Spend cap in micro-USD. Must be positive; a non-positive cap
                        would deny every request and is treated as "no policy" by the
                        engine (it's clamped out during validation in a later phase
                        when CRUD lands).
                      type: integer
                      format: int64
                    window:
                      $ref: '#/$defs/BudgetWindow'
                  required:
                  - window
                  - limit_micro_usd
                BudgetWindow:
                  description: |-
                    A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                    time-bucket query against `credit_ledger_entries`.
                  oneOf:
                  - description: 24 hours rolling.
                    type: string
                    const: day
                  - description: 30 days rolling.
                    type: string
                    const: month
                  - description: Lifetime — accumulates indefinitely.
                    type: string
                    const: total
                ByokRequirement:
                  description: |-
                    Strictness requirement on bring-your-own-key usage for the
                    inference call. Mapped from the caller's per-provider BYOK key.
                  oneOf:
                  - description: |-
                      The request MUST be served via a BYOK provider key. Used by
                      teams who never want platform credits to be spent.
                    type: string
                    const: required
                  - description: |-
                      The request MUST NOT be served via a BYOK key. Useful for
                      suppressing accidental BYOK shadowing on shared namespaces.
                    type: string
                    const: forbidden
                  - description: Either path is acceptable. Equivalent to no constraint.
                    type: string
                    const: optional
                GuardrailSpec:
                  description: |-
                    Per-request constraints on the inference call (model allowlists,
                    max generation length, streaming / BYOK switches). Each field is
                    optional; an unset axis adds no constraint.
                  type: object
                  properties:
                    allow_streaming:
                      description: |-
                        Permit-only one-way gate on streaming responses.
                        `Some(false)` forbids streaming: a request with `stream: true`
                        is denied. `Some(true)` and `None` both permit streaming
                        (`Some(true)` is the explicit "no constraint here" form;
                        `None` is the absence of any opinion). Guardrails cannot
                        *require* streaming — there is no way to refuse a
                        `stream: false` request via this field. The combiner
                        ([`crate::policy::engine`]) is forbid-wins for the same
                        reason: the union of permits is still a permit, and any one
                        `Some(false)` makes the effective policy a forbid.
                      type:
                      - boolean
                      - 'null'
                    byok:
                      description: |-
                        BYOK posture (see [`ByokRequirement`]). `None` = no
                        constraint.
                      anyOf:
                      - $ref: '#/$defs/ByokRequirement'
                      - type: 'null'
                    content_patterns:
                      description: |-
                        Content-firewall rules: regex `block` / `redact` patterns run over
                        the request prompt and the response stream by the
                        `bitrouter-guardrails` hooks. Empty = no content filtering. Combined
                        as a union across policies (every rule from every applicable policy
                        applies — more rules is strictly more restrictive).
                      type: array
                      items:
                        $ref: '#/$defs/RuleSpec'
                    max_request_tokens:
                      description: |-
                        Hard cap on the request's `prompt.params.max_tokens`. When
                        the request leaves `max_tokens` unset, the call is admitted —
                        the engine can't enforce a cap on an undeclared value.
                      type:
                      - integer
                      - 'null'
                      format: int64
                    model_allow:
                      description: |-
                        If set, only these (canonical) model ids may be requested.
                        An empty allowlist denies every model — same as no policy.
                      type:
                      - array
                      - 'null'
                      items:
                        type: string
                    model_deny:
                      description: |-
                        If set, these model ids are explicitly refused even when the
                        allowlist would otherwise admit them. Deny wins over allow.
                      type:
                      - array
                      - 'null'
                      items:
                        type: string
                RateLimitSpec:
                  description: |-
                    A request-frequency cap over a sliding window. Enforced with
                    Redis counters keyed per principal + window. At least one of
                    `max_requests` / `max_tokens` must be set for the policy to bite.
                  type: object
                  properties:
                    max_requests:
                      description: Hard cap on completed (admitted) requests in the window.
                      type:
                      - integer
                      - 'null'
                      format: int64
                    max_tokens:
                      description: |-
                        Hard cap on the caller's declared prompt-token budget
                        (`prompt.params.max_tokens`) in the window. Optional — most
                        rate-limit policies in practice only cap request rate.
                      type:
                      - integer
                      - 'null'
                      format: int64
                    window_secs:
                      description: Sliding-window width in seconds. Must be positive.
                      type: integer
                      format: int64
                  required:
                  - window_secs
                RuleSpec:
                  description: |-
                    One guardrail rule in serializable form: a name, a regex pattern, and a
                    match action. Compile it into a runtime rule with `RuleSpec::compile`.
                  type: object
                  properties:
                    action:
                      description: What to do on a match. Defaults to `block` when omitted.
                      $ref: '#/$defs/Action'
                      default: block
                    name:
                      description: Human-readable rule name (surfaced in deny reasons / logs).
                      type: string
                    pattern:
                      description: The regex pattern to match.
                      type: string
                  required:
                  - name
                  - pattern
        required: true
      responses:
        '200':
          description: Updated preset.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: PresetEnvelope
                description: |-
                  One preset as it appears on the wire. The sub-policy fields are
                  optional so an empty preset (no clauses) is representable; the
                  engine ignores empty presets at request time so this is a no-op
                  row rather than a denial.
                type: object
                properties:
                  budget:
                    anyOf:
                    - $ref: '#/$defs/BudgetSpec'
                    - type: 'null'
                  disabled_at:
                    description: |-
                      `None` for enabled rows. See
                      [`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]
                      for semantics — toggle via `POST /v1/policies/{id}/disable`
                      / `/enable`.
                    type:
                    - string
                    - 'null'
                    format: date-time
                  guardrail:
                    anyOf:
                    - $ref: '#/$defs/GuardrailSpec'
                    - type: 'null'
                  id:
                    type: string
                  name:
                    type: string
                  rate_limit:
                    anyOf:
                    - $ref: '#/$defs/RateLimitSpec'
                    - type: 'null'
                required:
                - id
                - name
                $defs:
                  Action:
                    description: What to do when a rule matches.
                    oneOf:
                    - description: |-
                        Block the content — upstream this is a 400 deny, downstream a stream
                        abort. The default when a rule omits its action (block is the safe one).
                      type: string
                      const: block
                    - description: Redact the matched span — replace it with the redaction placeholder.
                      type: string
                      const: redact
                  BudgetSpec:
                    description: |-
                      A spend cap over a rolling window. Spend is measured in
                      micro-USD — the same unit the credit ledger uses, so engine code
                      can sum `credit_ledger_entries.amount_micro_usd` directly.
                    type: object
                    properties:
                      limit_micro_usd:
                        description: |-
                          Spend cap in micro-USD. Must be positive; a non-positive cap
                          would deny every request and is treated as "no policy" by the
                          engine (it's clamped out during validation in a later phase
                          when CRUD lands).
                        type: integer
                        format: int64
                      window:
                        $ref: '#/$defs/BudgetWindow'
                    required:
                    - window
                    - limit_micro_usd
                  BudgetWindow:
                    description: |-
                      A rolling spend window for [`BudgetSpec`]. Maps to a SQL
                      time-bucket query against `credit_ledger_entries`.
                    oneOf:
                    - description: 24 hours rolling.
                      type: string
                      const: day
                    - description: 30 days rolling.
                      type: string
                      const: month
                    - description: Lifetime — accumulates indefinitely.
                      type: string
                      const: total
                  ByokRequirement:
                    description: |-
                      Strictness requirement on bring-your-own-key usage for the
                      inference call. Mapped from the caller's per-provider BYOK key.
                    oneOf:
                    - description: |-
                        The request MUST be served via a BYOK provider key. Used by
                        teams who never want platform credits to be spent.
                      type: string
                      const: required
                    - description: |-
                        The request MUST NOT be served via a BYOK key. Useful for
                        suppressing accidental BYOK shadowing on shared namespaces.
                      type: string
                      const: forbidden
                    - description: Either path is acceptable. Equivalent to no constraint.
                      type: string
                      const: optional
                  GuardrailSpec:
                    description: |-
                      Per-request constraints on the inference call (model allowlists,
                      max generation length, streaming / BYOK switches). Each field is
                      optional; an unset axis adds no constraint.
                    type: object
                    properties:
                      allow_streaming:
                        description: |-
                          Permit-only one-way gate on streaming responses.
                          `Some(false)` forbids streaming: a request with `stream: true`
                          is denied. `Some(true)` and `None` both permit streaming
                          (`Some(true)` is the explicit "no constraint here" form;
                          `None` is the absence of any opinion). Guardrails cannot
                          *require* streaming — there is no way to refuse a
                          `stream: false` request via this field. The combiner
                          ([`crate::policy::engine`]) is forbid-wins for the same
                          reason: the union of permits is still a permit, and any one
                          `Some(false)` makes the effective policy a forbid.
                        type:
                        - boolean
                        - 'null'
                      byok:
                        description: |-
                          BYOK posture (see [`ByokRequirement`]). `None` = no
                          constraint.
                        anyOf:
                        - $ref: '#/$defs/ByokRequirement'
                        - type: 'null'
                      content_patterns:
                        description: |-
                          Content-firewall rules: regex `block` / `redact` patterns run over
                          the request prompt and the response stream by the
                          `bitrouter-guardrails` hooks. Empty = no content filtering. Combined
                          as a union across policies (every rule from every applicable policy
                          applies — more rules is strictly more restrictive).
                        type: array
                        items:
                          $ref: '#/$defs/RuleSpec'
                      max_request_tokens:
                        description: |-
                          Hard cap on the request's `prompt.params.max_tokens`. When
                          the request leaves `max_tokens` unset, the call is admitted —
                          the engine can't enforce a cap on an undeclared value.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      model_allow:
                        description: |-
                          If set, only these (canonical) model ids may be requested.
                          An empty allowlist denies every model — same as no policy.
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                      model_deny:
                        description: |-
                          If set, these model ids are explicitly refused even when the
                          allowlist would otherwise admit them. Deny wins over allow.
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                  RateLimitSpec:
                    description: |-
                      A request-frequency cap over a sliding window. Enforced with
                      Redis counters keyed per principal + window. At least one of
                      `max_requests` / `max_tokens` must be set for the policy to bite.
                    type: object
                    properties:
                      max_requests:
                        description: Hard cap on completed (admitted) requests in the window.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      max_tokens:
                        description: |-
                          Hard cap on the caller's declared prompt-token budget
                          (`prompt.params.max_tokens`) in the window. Optional — most
                          rate-limit policies in practice only cap request rate.
                        type:
                        - integer
                        - 'null'
                        format: int64
                      window_secs:
                        description: Sliding-window width in seconds. Must be positive.
                        type: integer
                        format: int64
                    required:
                    - window_secs
                  RuleSpec:
                    description: |-
                      One guardrail rule in serializable form: a name, a regex pattern, and a
                      match action. Compile it into a runtime rule with `RuleSpec::compile`.
                    type: object
                    properties:
                      action:
                        description: What to do on a match. Defaults to `block` when omitted.
                        $ref: '#/$defs/Action'
                        default: block
                      name:
                        description: Human-readable rule name (surfaced in deny reasons / logs).
                        type: string
                      pattern:
                        description: The regex pattern to match.
                        type: string
                    required:
                    - name
                    - pattern
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    delete:
      tags:
      - Management
      summary: Delete a preset and its bindings
      description: |-
        Refuses to delete a row whose kind is not `preset` (returns 404).

        _Requires the `policy:write` scope._
      operationId: deletePreset
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `policies` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Delete acknowledgement.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: DeletePresetResponse
                type: object
                properties:
                  deleted:
                    type: boolean
                required:
                - deleted
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/routing-presets:
    get:
      tags:
      - Management
      summary: List the namespace's routing presets
      description: |-
        Typed list of routing presets. Each preset bundles request defaults (`model`, `system_prompt`, generation `params`) with provider-routing constraints (`routing`).

        _Requires the `routing_preset:read` scope._
      operationId: listRoutingPresets
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Routing preset list.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: RoutingPresetListResponse
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/$defs/RoutingPresetEnvelope'
                required:
                - data
                $defs:
                  RoutingConfig:
                    description: |-
                      Provider-routing constraints carried by a preset. All fields optional;
                      an empty `RoutingConfig` is a valid no-op.
                    type: object
                    properties:
                      ignore:
                        description: Provider deny-list (`provider_name`).
                        type: array
                        items:
                          type: string
                      only:
                        description: Provider allow-list (`provider_name`). Empty = no restriction.
                        type: array
                        items:
                          type: string
                      sort:
                        description: Optimization axis; reuses the global `RoutingProfile` vocabulary.
                        type:
                        - string
                        - 'null'
                  RoutingPresetEnvelope:
                    description: |-
                      One routing preset as it appears on the wire. The spec fields are
                      flattened alongside `id` / `name`; `disabled_at` is `None` for
                      enabled rows.
                    type: object
                    properties:
                      disabled_at:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      id:
                        type: string
                      model:
                        description: Base model substitution. When absent, the request must supply a base.
                        type:
                        - string
                        - 'null'
                      name:
                        type: string
                      params:
                        description: Generation-param defaults, shallow-merged into the request (request wins).
                        type: object
                        additionalProperties: true
                      routing:
                        description: Routing constraints.
                        $ref: '#/$defs/RoutingConfig'
                      system_prompt:
                        description: System-prompt default (filled only if the request omits one).
                        type:
                        - string
                        - 'null'
                    required:
                    - id
                    - name
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    post:
      tags:
      - Management
      summary: Create a routing preset
      description: |-
        Creates a named bundle of request defaults plus routing constraints, selectable per-request via `@<name>`. The request pipeline shallow-merges the preset's fields into the inbound request.

        _Requires the `routing_preset:write` scope._
      operationId: createRoutingPreset
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Routing preset request body.
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              title: CreateRoutingPresetRequest
              type: object
              properties:
                model:
                  type:
                  - string
                  - 'null'
                  default: null
                name:
                  type: string
                params:
                  type: object
                  additionalProperties: true
                  default: {}
                routing:
                  $ref: '#/$defs/RoutingConfig'
                  default: {}
                system_prompt:
                  type:
                  - string
                  - 'null'
                  default: null
              required:
              - name
              $defs:
                RoutingConfig:
                  description: |-
                    Provider-routing constraints carried by a preset. All fields optional;
                    an empty `RoutingConfig` is a valid no-op.
                  type: object
                  properties:
                    ignore:
                      description: Provider deny-list (`provider_name`).
                      type: array
                      items:
                        type: string
                    only:
                      description: Provider allow-list (`provider_name`). Empty = no restriction.
                      type: array
                      items:
                        type: string
                    sort:
                      description: Optimization axis; reuses the global `RoutingProfile` vocabulary.
                      type:
                      - string
                      - 'null'
        required: true
      responses:
        '200':
          description: Created routing preset.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: RoutingPresetEnvelope
                description: |-
                  One routing preset as it appears on the wire. The spec fields are
                  flattened alongside `id` / `name`; `disabled_at` is `None` for
                  enabled rows.
                type: object
                properties:
                  disabled_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  id:
                    type: string
                  model:
                    description: Base model substitution. When absent, the request must supply a base.
                    type:
                    - string
                    - 'null'
                  name:
                    type: string
                  params:
                    description: Generation-param defaults, shallow-merged into the request (request wins).
                    type: object
                    additionalProperties: true
                  routing:
                    description: Routing constraints.
                    $ref: '#/$defs/RoutingConfig'
                  system_prompt:
                    description: System-prompt default (filled only if the request omits one).
                    type:
                    - string
                    - 'null'
                required:
                - id
                - name
                $defs:
                  RoutingConfig:
                    description: |-
                      Provider-routing constraints carried by a preset. All fields optional;
                      an empty `RoutingConfig` is a valid no-op.
                    type: object
                    properties:
                      ignore:
                        description: Provider deny-list (`provider_name`).
                        type: array
                        items:
                          type: string
                      only:
                        description: Provider allow-list (`provider_name`). Empty = no restriction.
                        type: array
                        items:
                          type: string
                      sort:
                        description: Optimization axis; reuses the global `RoutingProfile` vocabulary.
                        type:
                        - string
                        - 'null'
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/routing-presets/{id}:
    get:
      tags:
      - Management
      summary: Read a routing preset by id
      description: |-
        Returns the routing preset if it exists and belongs to the named namespace. Any other case yields 404.

        _Requires the `routing_preset:read` scope._
      operationId: getRoutingPreset
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `routing_presets` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Routing preset row.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: RoutingPresetEnvelope
                description: |-
                  One routing preset as it appears on the wire. The spec fields are
                  flattened alongside `id` / `name`; `disabled_at` is `None` for
                  enabled rows.
                type: object
                properties:
                  disabled_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  id:
                    type: string
                  model:
                    description: Base model substitution. When absent, the request must supply a base.
                    type:
                    - string
                    - 'null'
                  name:
                    type: string
                  params:
                    description: Generation-param defaults, shallow-merged into the request (request wins).
                    type: object
                    additionalProperties: true
                  routing:
                    description: Routing constraints.
                    $ref: '#/$defs/RoutingConfig'
                  system_prompt:
                    description: System-prompt default (filled only if the request omits one).
                    type:
                    - string
                    - 'null'
                required:
                - id
                - name
                $defs:
                  RoutingConfig:
                    description: |-
                      Provider-routing constraints carried by a preset. All fields optional;
                      an empty `RoutingConfig` is a valid no-op.
                    type: object
                    properties:
                      ignore:
                        description: Provider deny-list (`provider_name`).
                        type: array
                        items:
                          type: string
                      only:
                        description: Provider allow-list (`provider_name`). Empty = no restriction.
                        type: array
                        items:
                          type: string
                      sort:
                        description: Optimization axis; reuses the global `RoutingProfile` vocabulary.
                        type:
                        - string
                        - 'null'
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    put:
      tags:
      - Management
      summary: Replace a routing preset's spec
      description: |-
        Full replace of the preset's spec body (not a per-field merge) — every request carries the complete spec it wants persisted. `name` is optional; an absent `name` leaves it unchanged.

        _Requires the `routing_preset:write` scope._
      operationId: updateRoutingPreset
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `routing_presets` row.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Routing preset replacement.
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              title: UpdateRoutingPresetRequest
              type: object
              properties:
                model:
                  type:
                  - string
                  - 'null'
                  default: null
                name:
                  type:
                  - string
                  - 'null'
                  default: null
                params:
                  type: object
                  additionalProperties: true
                  default: {}
                routing:
                  $ref: '#/$defs/RoutingConfig'
                  default: {}
                system_prompt:
                  type:
                  - string
                  - 'null'
                  default: null
              $defs:
                RoutingConfig:
                  description: |-
                    Provider-routing constraints carried by a preset. All fields optional;
                    an empty `RoutingConfig` is a valid no-op.
                  type: object
                  properties:
                    ignore:
                      description: Provider deny-list (`provider_name`).
                      type: array
                      items:
                        type: string
                    only:
                      description: Provider allow-list (`provider_name`). Empty = no restriction.
                      type: array
                      items:
                        type: string
                    sort:
                      description: Optimization axis; reuses the global `RoutingProfile` vocabulary.
                      type:
                      - string
                      - 'null'
        required: true
      responses:
        '200':
          description: Updated routing preset.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: RoutingPresetEnvelope
                description: |-
                  One routing preset as it appears on the wire. The spec fields are
                  flattened alongside `id` / `name`; `disabled_at` is `None` for
                  enabled rows.
                type: object
                properties:
                  disabled_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  id:
                    type: string
                  model:
                    description: Base model substitution. When absent, the request must supply a base.
                    type:
                    - string
                    - 'null'
                  name:
                    type: string
                  params:
                    description: Generation-param defaults, shallow-merged into the request (request wins).
                    type: object
                    additionalProperties: true
                  routing:
                    description: Routing constraints.
                    $ref: '#/$defs/RoutingConfig'
                  system_prompt:
                    description: System-prompt default (filled only if the request omits one).
                    type:
                    - string
                    - 'null'
                required:
                - id
                - name
                $defs:
                  RoutingConfig:
                    description: |-
                      Provider-routing constraints carried by a preset. All fields optional;
                      an empty `RoutingConfig` is a valid no-op.
                    type: object
                    properties:
                      ignore:
                        description: Provider deny-list (`provider_name`).
                        type: array
                        items:
                          type: string
                      only:
                        description: Provider allow-list (`provider_name`). Empty = no restriction.
                        type: array
                        items:
                          type: string
                      sort:
                        description: Optimization axis; reuses the global `RoutingProfile` vocabulary.
                        type:
                        - string
                        - 'null'
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    delete:
      tags:
      - Management
      summary: Delete a routing preset
      description: |-
        Deletes the routing preset by id within the named namespace. Returns 404 if no such row exists in the namespace.

        _Requires the `routing_preset:write` scope._
      operationId: deleteRoutingPreset
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `routing_presets` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Delete acknowledgement.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: DeleteRoutingPresetResponse
                type: object
                properties:
                  deleted:
                    type: boolean
                required:
                - deleted
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/routing-presets/{id}/disable:
    post:
      tags:
      - Management
      summary: Park a routing preset without deleting it
      description: |-
        Stamps `disabled_at = now()`. The resolver skips disabled presets when selecting a preset per-request; the management surface still surfaces them so an operator can re-enable. Idempotent — re-disabling returns 200. Responds with the updated envelope carrying `disabled_at`.

        _Requires the `routing_preset:write` scope._
      operationId: disableRoutingPreset
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `routing_presets` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Updated routing preset.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: RoutingPresetEnvelope
                description: |-
                  One routing preset as it appears on the wire. The spec fields are
                  flattened alongside `id` / `name`; `disabled_at` is `None` for
                  enabled rows.
                type: object
                properties:
                  disabled_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  id:
                    type: string
                  model:
                    description: Base model substitution. When absent, the request must supply a base.
                    type:
                    - string
                    - 'null'
                  name:
                    type: string
                  params:
                    description: Generation-param defaults, shallow-merged into the request (request wins).
                    type: object
                    additionalProperties: true
                  routing:
                    description: Routing constraints.
                    $ref: '#/$defs/RoutingConfig'
                  system_prompt:
                    description: System-prompt default (filled only if the request omits one).
                    type:
                    - string
                    - 'null'
                required:
                - id
                - name
                $defs:
                  RoutingConfig:
                    description: |-
                      Provider-routing constraints carried by a preset. All fields optional;
                      an empty `RoutingConfig` is a valid no-op.
                    type: object
                    properties:
                      ignore:
                        description: Provider deny-list (`provider_name`).
                        type: array
                        items:
                          type: string
                      only:
                        description: Provider allow-list (`provider_name`). Empty = no restriction.
                        type: array
                        items:
                          type: string
                      sort:
                        description: Optimization axis; reuses the global `RoutingProfile` vocabulary.
                        type:
                        - string
                        - 'null'
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/routing-presets/{id}/enable:
    post:
      tags:
      - Management
      summary: Re-enable a previously disabled routing preset
      description: |-
        Clears `disabled_at`. The resolver starts honouring the preset again on the next request. Idempotent. Responds with the updated envelope (with `disabled_at` cleared).

        _Requires the `routing_preset:write` scope._
      operationId: enableRoutingPreset
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: id
        description: Surrogate id of the `routing_presets` row.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Updated routing preset.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: RoutingPresetEnvelope
                description: |-
                  One routing preset as it appears on the wire. The spec fields are
                  flattened alongside `id` / `name`; `disabled_at` is `None` for
                  enabled rows.
                type: object
                properties:
                  disabled_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  id:
                    type: string
                  model:
                    description: Base model substitution. When absent, the request must supply a base.
                    type:
                    - string
                    - 'null'
                  name:
                    type: string
                  params:
                    description: Generation-param defaults, shallow-merged into the request (request wins).
                    type: object
                    additionalProperties: true
                  routing:
                    description: Routing constraints.
                    $ref: '#/$defs/RoutingConfig'
                  system_prompt:
                    description: System-prompt default (filled only if the request omits one).
                    type:
                    - string
                    - 'null'
                required:
                - id
                - name
                $defs:
                  RoutingConfig:
                    description: |-
                      Provider-routing constraints carried by a preset. All fields optional;
                      an empty `RoutingConfig` is a valid no-op.
                    type: object
                    properties:
                      ignore:
                        description: Provider deny-list (`provider_name`).
                        type: array
                        items:
                          type: string
                      only:
                        description: Provider allow-list (`provider_name`). Empty = no restriction.
                        type: array
                        items:
                          type: string
                      sort:
                        description: Optimization axis; reuses the global `RoutingProfile` vocabulary.
                        type:
                        - string
                        - 'null'
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/oauth/clients:
    get:
      tags:
      - Management
      summary: List the caller's OAuth clients
      description: |-
        Never returns the `client_secret_hash`.

        _Requires the `clients:read` scope._
      operationId: listOauthClients
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    post:
      tags:
      - Management
      summary: Register a new OAuth client
      description: |-
        Confidential clients receive the freshly minted `client_secret` once in the response — the cloud retains only the hash.

        _Requires the `clients:write` scope._
      operationId: registerOauthClient
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Request body. See the endpoint description for shape.
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/namespaces/{nsid}/oauth/clients/{client_id}:
    put:
      tags:
      - Management
      summary: Update an OAuth client
      description: |-
        Mutate the client's name, redirect URIs, allowed scopes, or allowed grant types. Each field is optional.

        _Requires the `clients:write` scope._
      operationId: updateOauthClient
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Request body. See the endpoint description for shape.
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
    delete:
      tags:
      - Management
      summary: Delete an OAuth client
      description: |2-


        _Requires the `clients:write` scope._
      operationId: deleteOauthClient
      parameters:
      - in: path
        name: nsid
        description: Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: client_id
        description: The client's public `client_id` (e.g. `brc_…`).
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Credential missing or did not verify.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '403':
          description: Credential is valid but lacks the required scope.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: Resource not found (or owned by a different account).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/chat/completions:
    post:
      tags:
      - OpenAI Compatible
      summary: Create chat completion
      description: |-
        Creates a chat completion for the given messages. Drop-in replacement for the OpenAI Chat Completions API — accepts the same request schema and returns the same response format, including `usage` with token counts.

        The router resolves the requested model to an upstream provider, forwards the request, and returns the response. Supports both synchronous and streaming modes.

        When `stream: true`, the response is sent as Server-Sent Events (SSE) where each `data` line contains a `ChatCompletionChunk` JSON object. The stream ends with `data: [DONE]`.
      operationId: createChatCompletion
      requestBody:
        description: Chat completion request. The router forwards a slightly enriched version of this body to the resolved upstream provider.
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              title: ChatRequest
              description: |-
                Chat Completions request body
                (<https://platform.openai.com/docs/api-reference/chat/create>).

                `pub` so downstream crates (notably `bitrouter-cloud`) can derive an
                OpenAPI schema from the canonical wire shape without redeclaring it.
              type: object
              properties:
                frequency_penalty:
                  description: |-
                    Frequency penalty. Promoted to the canonical `frequency_penalty` slot.
                    <https://platform.openai.com/docs/api-reference/chat/create#chat-create-frequency_penalty>
                  type:
                  - number
                  - 'null'
                  format: double
                  default: null
                max_completion_tokens:
                  type:
                  - integer
                  - 'null'
                  format: uint32
                  default: null
                  minimum: 0
                max_tokens:
                  type:
                  - integer
                  - 'null'
                  format: uint32
                  default: null
                  minimum: 0
                messages:
                  type: array
                  items:
                    $ref: '#/$defs/ChatMessage'
                model:
                  type: string
                presence_penalty:
                  description: |-
                    Presence penalty. Promoted to the canonical `presence_penalty` slot.
                    <https://platform.openai.com/docs/api-reference/chat/create#chat-create-presence_penalty>
                  type:
                  - number
                  - 'null'
                  format: double
                  default: null
                reasoning_effort:
                  type:
                  - string
                  - 'null'
                  default: null
                response_format:
                  description: |-
                    Output-format constraint. The `json_schema` variant is the
                    structured-output contract; `json_object` is the legacy JSON mode and
                    `text` is the default. Promoted to the canonical `response_format` slot
                    at parse time (`json_object` / `text` pass through opaquely).
                    <https://platform.openai.com/docs/guides/structured-outputs>
                  anyOf:
                  - $ref: '#/$defs/ChatResponseFormat'
                  - type: 'null'
                  default: null
                seed:
                  description: |-
                    Deterministic-sampling seed. Promoted to the canonical `seed` slot so it
                    translates across protocols (e.g. to a Gemini upstream's
                    `generationConfig.seed`) instead of no-op'ing as a top-level key on a
                    nested-config wire.
                    <https://platform.openai.com/docs/api-reference/chat/create#chat-create-seed>
                  type:
                  - integer
                  - 'null'
                  format: int64
                  default: null
                stop:
                  description: |-
                    Stop sequences — a single string or an array of up to four. Promoted to
                    the canonical `stop` slot.
                    <https://platform.openai.com/docs/api-reference/chat/create#chat-create-stop>
                  default: null
                stream:
                  type: boolean
                  default: false
                temperature:
                  type:
                  - number
                  - 'null'
                  format: double
                  default: null
                tools:
                  type: array
                  items:
                    $ref: '#/$defs/ChatTool'
                top_p:
                  type:
                  - number
                  - 'null'
                  format: double
                  default: null
              required:
              - model
              - messages
              $defs:
                ChatFunctionCall:
                  description: 'The `function` payload of a [`ChatToolCall`]: name + raw JSON argument string.'
                  type: object
                  properties:
                    arguments:
                      type: string
                      default: ''
                    name:
                      type: string
                      default: ''
                ChatJsonSchema:
                  description: The `json_schema` payload of [`ChatResponseFormat::JsonSchema`].
                  type: object
                  properties:
                    description:
                      description: |-
                        Optional schema description — extra LLM guidance OpenAI passes through to
                        the model. Promoted to the canonical `response_format` description.
                        <https://platform.openai.com/docs/guides/structured-outputs>
                      type:
                      - string
                      - 'null'
                    name:
                      description: Schema name (OpenAI requires it).
                      type: string
                    schema:
                      description: The JSON Schema.
                    strict:
                      description: Strict-mode flag.
                      type:
                      - boolean
                      - 'null'
                  required:
                  - name
                  - schema
                ChatMessage:
                  description: |-
                    One element of [`ChatRequest`]'s `messages` array — a chat turn carrying
                    role + optional content + optional tool calls / tool-call reply id.
                  type: object
                  properties:
                    content:
                      description: |-
                        `content` may be a plain string or an array of content parts, or absent
                        (an assistant turn that is purely `tool_calls`).
                      default: null
                    reasoning_content:
                      description: |-
                        Reasoning content — **not** in OpenAI's Chat Completions spec; this is
                        a vendor extension used by DeepSeek
                        (<https://api-docs.deepseek.com/api/create-chat-completion>), Moonshot
                        (Kimi), Qwen, and other OpenAI-compatible providers that expose the
                        model's chain-of-thought on the Chat envelope. v0 #454-1: it must
                        not be dropped. `parse_response` additionally accepts `reasoning`
                        (some OpenRouter passthroughs) and `thinking` (Aliyun) as aliases.
                      type:
                      - string
                      - 'null'
                      default: null
                    role:
                      type: string
                    tool_call_id:
                      type:
                      - string
                      - 'null'
                      default: null
                    tool_calls:
                      type: array
                      items:
                        $ref: '#/$defs/ChatToolCall'
                  required:
                  - role
                ChatResponseFormat:
                  description: |-
                    Chat Completions `response_format`
                    (<https://platform.openai.com/docs/guides/structured-outputs>) — a closed
                    union over OpenAI's three output modes.
                  oneOf:
                  - description: Free-form text — the default.
                    type: object
                    properties:
                      type:
                        type: string
                        const: text
                    required:
                    - type
                  - description: 'Legacy JSON mode: valid JSON with no schema.'
                    type: object
                    properties:
                      type:
                        type: string
                        const: json_object
                    required:
                    - type
                  - description: JSON constrained to a schema.
                    type: object
                    properties:
                      json_schema:
                        description: The schema spec.
                        $ref: '#/$defs/ChatJsonSchema'
                      type:
                        type: string
                        const: json_schema
                    required:
                    - type
                    - json_schema
                ChatTool:
                  description: 'One element of [`ChatRequest`]''s `tools` array — a `{ function: { … } }` envelope.'
                  type: object
                  properties:
                    function:
                      $ref: '#/$defs/ChatToolFunction'
                ChatToolCall:
                  description: One assistant tool-call entry on a [`ChatMessage`].
                  type: object
                  properties:
                    function:
                      $ref: '#/$defs/ChatFunctionCall'
                    id:
                      type: string
                  required:
                  - id
                ChatToolFunction:
                  description: |-
                    The `function` payload of a [`ChatTool`]: name + description + JSON-Schema
                    parameters + optional `strict` flag.
                    <https://platform.openai.com/docs/guides/function-calling#strict-mode>
                  type: object
                  properties:
                    description:
                      type:
                      - string
                      - 'null'
                      default: null
                    name:
                      type: string
                    parameters:
                      default: null
                    strict:
                      description: |-
                        OpenAI strict-mode flag (V3 `strict`). Captured so it is not lost across
                        the canonical boundary.
                      type:
                      - boolean
                      - 'null'
                      default: null
                  required:
                  - name
        required: true
      responses:
        '200':
          description: |-
            Chat completion response (non-streaming).

            Streamed chat completion — Server-Sent Events with one `ChatCompletionChunk` per `data:` line, terminated by `data: [DONE]`.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ChatCompletionResponseDoc
                description: 'MIRROR: `bitrouter_sdk::language_model::protocol::chat_completions` response'
                type: object
                properties:
                  choices:
                    type: array
                    items:
                      $ref: '#/$defs/ChatCompletionChoiceDoc'
                  created:
                    description: Unix timestamp (seconds) of when the completion was created.
                    type: integer
                    format: uint64
                    minimum: 0
                  id:
                    description: A unique identifier for the completion.
                    type: string
                  model:
                    description: The model used for the completion.
                    type: string
                  object:
                    description: Object type — always `chat.completion`.
                    type: string
                  usage:
                    anyOf:
                    - $ref: '#/$defs/ChatCompletionUsageDoc'
                    - type: 'null'
                required:
                - id
                - object
                - created
                - model
                - choices
                $defs:
                  ChatCompletionChoiceDoc:
                    type: object
                    properties:
                      finish_reason:
                        type:
                        - string
                        - 'null'
                      index:
                        type: integer
                        format: uint32
                        minimum: 0
                      message:
                        $ref: '#/$defs/ChatCompletionMessageDoc'
                    required:
                    - index
                    - message
                  ChatCompletionMessageDoc:
                    type: object
                    properties:
                      content:
                        type:
                        - string
                        - 'null'
                      role:
                        type: string
                    required:
                    - role
                  ChatCompletionUsageDoc:
                    type: object
                    properties:
                      completion_tokens:
                        type: integer
                        format: uint32
                        minimum: 0
                      prompt_tokens:
                        type: integer
                        format: uint32
                        minimum: 0
                      total_tokens:
                        type: integer
                        format: uint32
                        minimum: 0
                    required:
                    - prompt_tokens
                    - completion_tokens
                    - total_tokens
            text/event-stream:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ChatCompletionChunkDoc
                description: |-
                  MIRROR: a single SSE `data:` payload in the streaming `/v1/chat/completions`
                  response. Used to type the `text/event-stream` content for the same route.
                type: object
                properties:
                  choices:
                    type: array
                    items:
                      $ref: '#/$defs/ChatCompletionChunkChoiceDoc'
                  created:
                    type: integer
                    format: uint64
                    minimum: 0
                  id:
                    type: string
                  model:
                    type: string
                  object:
                    type: string
                  usage:
                    anyOf:
                    - $ref: '#/$defs/ChatCompletionUsageDoc'
                    - type: 'null'
                required:
                - id
                - object
                - created
                - model
                - choices
                $defs:
                  ChatCompletionChunkChoiceDoc:
                    type: object
                    properties:
                      delta:
                        $ref: '#/$defs/ChatCompletionChunkDeltaDoc'
                      finish_reason:
                        type:
                        - string
                        - 'null'
                      index:
                        type: integer
                        format: uint32
                        minimum: 0
                    required:
                    - index
                    - delta
                  ChatCompletionChunkDeltaDoc:
                    type: object
                    properties:
                      content:
                        type:
                        - string
                        - 'null'
                      role:
                        type:
                        - string
                        - 'null'
                  ChatCompletionUsageDoc:
                    type: object
                    properties:
                      completion_tokens:
                        type: integer
                        format: uint32
                        minimum: 0
                      prompt_tokens:
                        type: integer
                        format: uint32
                        minimum: 0
                      total_tokens:
                        type: integer
                        format: uint32
                        minimum: 0
                    required:
                    - prompt_tokens
                    - completion_tokens
                    - total_tokens
        '400':
          description: Bad request — invalid model or malformed request body.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '402':
          description: Payment required — insufficient balance or missing payment proof.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: No route found for the requested model.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/responses:
    post:
      tags:
      - OpenAI Responses
      summary: Create response
      description: |-
        Creates a response using the OpenAI Responses API format. Drop-in replacement for OpenAI's newer stateful-conversation surface.

        When `stream: true`, the response is sent as Server-Sent Events (SSE) with the full output-item lifecycle (`response.created`, `response.output_item.added`, `response.output_text.delta`, `response.completed`, …). The cloud forwards the upstream provider's SSE stream unchanged.
      operationId: createResponse
      requestBody:
        description: OpenAI Responses API request.
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              title: ResponsesRequest
              description: |-
                Responses request body
                (<https://platform.openai.com/docs/api-reference/responses/create>).

                `pub` so downstream crates (notably `bitrouter-cloud`) can derive an
                OpenAPI schema from the canonical wire shape without redeclaring it.

                `input` stays `serde_json::Value` on purpose — the Responses API accepts
                either a plain string or a heterogeneous item array (Codex multi-turn,
                #454-3), and the deeper walk happens in `parse_input` (private). Mirrors
                how Anthropic's `system` / `content` are typed.
              type: object
              properties:
                input: true
                instructions:
                  type:
                  - string
                  - 'null'
                  default: null
                max_output_tokens:
                  type:
                  - integer
                  - 'null'
                  format: uint32
                  default: null
                  minimum: 0
                model:
                  type: string
                  default: ''
                reasoning:
                  anyOf:
                  - $ref: '#/$defs/ResponsesReasoningConfig'
                  - type: 'null'
                stream:
                  type: boolean
                  default: false
                temperature:
                  type:
                  - number
                  - 'null'
                  format: double
                  default: null
                text:
                  description: |-
                    Output `text` config — `format` is the structured-output constraint
                    (`json_schema` is promoted to the canonical slot; `text` / `json_object`
                    pass through). Sibling keys (e.g. `verbosity`) survive via `extra`.
                  anyOf:
                  - $ref: '#/$defs/ResponsesText'
                  - type: 'null'
                tools:
                  type: array
                  items:
                    $ref: '#/$defs/ResponsesTool'
                top_p:
                  type:
                  - number
                  - 'null'
                  format: double
                  default: null
              required:
              - input
              $defs:
                ResponsesReasoningConfig:
                  description: |-
                    `reasoning` knob on [`ResponsesRequest`] — only `effort` is read; other
                    fields (`summary`, …) round-trip via no slot today (matching v0 behavior).
                  type: object
                  properties:
                    effort:
                      type:
                      - string
                      - 'null'
                      default: null
                ResponsesText:
                  description: |-
                    Responses `text` config. `format` constrains output shape; sibling keys
                    (e.g. `verbosity`) pass through via `extra`.
                  type: object
                  properties:
                    format:
                      anyOf:
                      - $ref: '#/$defs/ResponsesTextFormat'
                      - type: 'null'
                      default: null
                ResponsesTextFormat:
                  description: |-
                    Responses `text.format`
                    (<https://platform.openai.com/docs/api-reference/responses/create>) — a
                    closed union over OpenAI's three output modes.
                  oneOf:
                  - description: Free-form text — the default.
                    type: object
                    properties:
                      type:
                        type: string
                        const: text
                    required:
                    - type
                  - description: Legacy JSON mode.
                    type: object
                    properties:
                      type:
                        type: string
                        const: json_object
                    required:
                    - type
                  - description: JSON constrained to a schema.
                    type: object
                    properties:
                      description:
                        description: |-
                          Optional schema description — extra LLM guidance OpenAI passes to the
                          model. Promoted to the canonical `response_format` description.
                          <https://platform.openai.com/docs/api-reference/responses/create>
                        type:
                        - string
                        - 'null'
                      name:
                        description: Schema name (OpenAI requires it).
                        type: string
                      schema:
                        description: The JSON Schema.
                      strict:
                        description: Strict-mode flag.
                        type:
                        - boolean
                        - 'null'
                      type:
                        type: string
                        const: json_schema
                    required:
                    - type
                    - name
                    - schema
                ResponsesTool:
                  description: |-
                    One element of [`ResponsesRequest`]'s `tools` array.

                    Responses uses one flat array for both kinds of tool:
                    - a **function** tool — `{type:"function", name, description?, parameters, strict?}`;
                    - a **provider-defined** server tool — `{type:"web_search_preview"|…, …config}`
                      (`code_interpreter`, `file_search`, `image_generation`, `computer_use_preview`).

                    `kind` (`type`) discriminates the two; for a server tool the configuration
                    keys ride in `extra` so they are preserved verbatim into the canonical
                    `Tool::ProviderDefined.args`.
                    <https://platform.openai.com/docs/api-reference/responses/create#responses-create-tools>
                  type: object
                  properties:
                    description:
                      type:
                      - string
                      - 'null'
                      default: null
                    name:
                      type:
                      - string
                      - 'null'
                      default: null
                    parameters:
                      default: null
                    strict:
                      description: |-
                        OpenAI strict-mode flag (V3 `strict`) on a function tool. Captured so it
                        is not lost across the canonical boundary.
                      type:
                      - boolean
                      - 'null'
                      default: null
                    type:
                      type:
                      - string
                      - 'null'
                      default: null
        required: true
      responses:
        '200':
          description: |-
            Response object (non-streaming).

            Streamed Responses output — Server-Sent Events with the full output-item lifecycle (`response.created`, `response.output_item.added`, `response.completed`, …).
          content:
            application/json:
              schema:
                description: OpenAI Responses API response envelope. Refer to OpenAI's published Responses spec for the full field set; bitrouter forwards the upstream body unchanged.
                type: object
            text/event-stream:
              schema:
                description: A single Responses SSE event. The `type` field discriminates the lifecycle stage.
                type: object
        '400':
          description: Bad request — invalid model or malformed request body.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '402':
          description: Payment required — insufficient balance or missing payment proof.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: No route found for the requested model.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1/messages:
    post:
      tags:
      - Anthropic Compatible
      summary: Create message
      description: |-
        Creates a message using the Anthropic Messages API format. Drop-in replacement for the Anthropic API.

        When `stream: true`, the response is sent as Server-Sent Events (SSE). Each event has a `type` field indicating the event kind (`message_start`, `content_block_delta`, `message_delta`, `message_stop`).
      operationId: createMessage
      requestBody:
        description: Anthropic Messages request.
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              title: MessagesRequest
              description: |-
                Messages request body (<https://docs.anthropic.com/en/api/messages>).

                `pub` so downstream crates (notably `bitrouter-cloud`) can derive an
                OpenAPI schema from the canonical wire shape without redeclaring it.
              type: object
              properties:
                max_tokens:
                  type:
                  - integer
                  - 'null'
                  format: uint32
                  default: null
                  minimum: 0
                messages:
                  type: array
                  items:
                    $ref: '#/$defs/MessagesMessage'
                model:
                  type: string
                output_config:
                  description: |-
                    Structured-output + reasoning config — `format` (`json_schema`) is
                    promoted to the canonical `response_format` and `effort` to the canonical
                    reasoning effort. Sibling keys pass through via `extra`.
                    <https://platform.claude.com/docs/en/build-with-claude/structured-outputs>
                  anyOf:
                  - $ref: '#/$defs/MessagesOutputConfig'
                  - type: 'null'
                stop_sequences:
                  description: |-
                    Custom stop sequences. Promoted to the canonical `stop` slot, so it can
                    render as a Chat Completions `stop` or a Gemini `stopSequences`.
                    <https://docs.anthropic.com/en/api/messages#body-stop-sequences>
                  type:
                  - array
                  - 'null'
                  default: null
                  items:
                    type: string
                stream:
                  type: boolean
                  default: false
                system:
                  description: 'String or an array of `{type:"text", text}` blocks (#227 → #228).'
                  default: null
                temperature:
                  type:
                  - number
                  - 'null'
                  format: double
                  default: null
                tools:
                  type: array
                  items:
                    $ref: '#/$defs/MessagesTool'
                top_k:
                  description: |-
                    Top-k sampling. Promoted to the canonical `top_k` slot so it translates
                    across protocols (e.g. to a Gemini upstream's `generationConfig.topK`).
                    <https://docs.anthropic.com/en/api/messages#body-top-k>
                  type:
                  - integer
                  - 'null'
                  format: uint32
                  default: null
                  minimum: 0
                top_p:
                  type:
                  - number
                  - 'null'
                  format: double
                  default: null
              required:
              - model
              - messages
              $defs:
                MessagesMessage:
                  description: One element of [`MessagesRequest`]'s `messages` array — a `{ role, content }` turn.
                  type: object
                  properties:
                    content:
                      description: String or an array of content blocks.
                    role:
                      type: string
                  required:
                  - role
                  - content
                MessagesOutputConfig:
                  description: Messages `output_config` — structured output + reasoning effort.
                  type: object
                  properties:
                    effort:
                      description: Reasoning effort (`low` | `medium` | `high` | `xhigh` | `max`).
                      type:
                      - string
                      - 'null'
                      default: null
                    format:
                      anyOf:
                      - $ref: '#/$defs/MessagesOutputFormat'
                      - type: 'null'
                MessagesOutputFormat:
                  description: |-
                    Messages `output_config.format`
                    (<https://platform.claude.com/docs/en/build-with-claude/structured-outputs>).
                    Anthropic's GA structured-output format carries no name / strict.
                  oneOf:
                  - description: JSON constrained to a schema.
                    type: object
                    properties:
                      schema:
                        description: The JSON Schema.
                      type:
                        type: string
                        const: json_schema
                    required:
                    - type
                    - schema
                MessagesTool:
                  description: |-
                    One element of [`MessagesRequest`]'s `tools` array.

                    Anthropic uses one array for both kinds of tool:
                    - a **client (function) tool** — `{name, description?, input_schema}` (no `type`);
                    - a **provider-defined (server) tool** — `{type:"web_search_20250305"|…, name, …config}`
                      (web search, code execution, computer use, bash, text editor), where `type`
                      is the dated tool version and `name` is the stable tool name.

                    A versioned `type` discriminates a server tool; its config keys ride in
                    `extra` so they are preserved verbatim into `Tool::ProviderDefined.args`.
                    <https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview>
                    <https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool>
                  type: object
                  properties:
                    description:
                      type:
                      - string
                      - 'null'
                      default: null
                    input_schema:
                      default: null
                    name:
                      type:
                      - string
                      - 'null'
                      default: null
                    type:
                      type:
                      - string
                      - 'null'
                      default: null
        required: true
      responses:
        '200':
          description: |-
            Messages response (non-streaming).

            Streamed Messages response — Server-Sent Events. Each event has a `type` field (`message_start`, `content_block_delta`, …).
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: MessagesResponseDoc
                description: 'MIRROR: `bitrouter_sdk::language_model::protocol::messages` response'
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/$defs/MessagesContentBlockDoc'
                  id:
                    type: string
                  model:
                    type: string
                  role:
                    description: Always `assistant`.
                    type: string
                  stop_reason:
                    type:
                    - string
                    - 'null'
                  stop_sequence:
                    type:
                    - string
                    - 'null'
                  type:
                    description: Always `message`.
                    type: string
                  usage:
                    $ref: '#/$defs/MessagesUsageDoc'
                required:
                - id
                - type
                - role
                - content
                - model
                - usage
                $defs:
                  MessagesContentBlockDoc:
                    type: object
                    properties:
                      text:
                        type: string
                      type:
                        description: Block type — `text` is the only variant emitted today.
                        type: string
                    required:
                    - type
                    - text
                  MessagesUsageDoc:
                    type: object
                    properties:
                      cache_creation_input_tokens:
                        description: |-
                          Number of tokens written to the prompt cache by this request. Present
                          (non-zero) only when the request enabled prompt caching.
                        type:
                        - integer
                        - 'null'
                        format: uint32
                        minimum: 0
                      cache_read_input_tokens:
                        description: |-
                          Number of tokens read from the prompt cache by this request. Present
                          (non-zero) only when the request reused a cached prompt.
                        type:
                        - integer
                        - 'null'
                        format: uint32
                        minimum: 0
                      input_tokens:
                        type: integer
                        format: uint32
                        minimum: 0
                      output_tokens:
                        type: integer
                        format: uint32
                        minimum: 0
                    required:
                    - input_tokens
                    - output_tokens
            text/event-stream:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: MessagesStreamEventDoc
                description: 'MIRROR: a single SSE event in the streaming `/v1/messages` response.'
                type: object
                properties:
                  delta:
                    anyOf:
                    - $ref: '#/$defs/MessagesStreamDeltaDoc'
                    - type: 'null'
                  index:
                    type:
                    - integer
                    - 'null'
                    format: uint32
                    minimum: 0
                  message:
                    anyOf:
                    - $ref: '#/$defs/MessagesStreamMessageDoc'
                    - type: 'null'
                  type:
                    description: |-
                      Event type — `message_start`, `content_block_delta`, `message_delta`,
                      `message_stop`, etc.
                    type: string
                required:
                - type
                $defs:
                  MessagesStreamDeltaDoc:
                    type: object
                    properties:
                      stop_reason:
                        type:
                        - string
                        - 'null'
                      text:
                        type:
                        - string
                        - 'null'
                      type:
                        type:
                        - string
                        - 'null'
                  MessagesStreamMessageDoc:
                    type: object
                    properties:
                      id:
                        type: string
                      model:
                        type: string
                      role:
                        type: string
                    required:
                    - id
                    - model
                    - role
        '400':
          description: Bad request — invalid model or malformed request body.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '402':
          description: Payment required — insufficient balance or missing payment proof.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: No route found for the requested model.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
  /v1beta/models/{model_action}:
    post:
      tags:
      - Google Compatible
      summary: Generate content (Google)
      description: |-
        Generates content using the Google Generative Language API format. Drop-in replacement for `generativelanguage.googleapis.com/v1beta`.

        The model id and streaming verb are both encoded in the `model_action` path segment — for example `gemini-2.0-flash:generateContent` (synchronous) or `gemini-2.0-flash:streamGenerateContent` (SSE). The cloud injects the model id into the request body before dispatching, so callers can use the same URL convention as Google's own API.
      operationId: googleGenerateContent
      parameters:
      - in: path
        name: model_action
        description: '`{model}:{action}` segment — Google encodes both the model id and the streaming verb in one path component. `action` is either `generateContent` (synchronous) or `streamGenerateContent` (SSE). Example: `gemini-2.0-flash:generateContent`.'
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: Google Generative Language `:generateContent` request.
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              title: GenerateContentRequest
              description: |-
                Generate Content `generateContent` request body
                (<https://ai.google.dev/api/generate-content>).

                `pub` so downstream crates (notably `bitrouter-cloud`) can derive an
                OpenAPI schema from the canonical wire shape without redeclaring it.
              type: object
              properties:
                contents:
                  type: array
                  items:
                    $ref: '#/$defs/GenerateContentContent'
                generationConfig:
                  anyOf:
                  - $ref: '#/$defs/GenerateContentGenerationConfig'
                  - type: 'null'
                model:
                  description: |-
                    Carried as a field so the inbound HTTP route's `{model}` path param can
                    override it; defaults empty.
                  type: string
                  default: ''
                stream:
                  description: |-
                    Injected by `server::generate_content` from the path verb
                    (`:streamGenerateContent` → true, `:generateContent` → false).
                  type: boolean
                  default: false
                systemInstruction:
                  anyOf:
                  - $ref: '#/$defs/GenerateContentContent'
                  - type: 'null'
                tools:
                  type: array
                  items:
                    $ref: '#/$defs/GenerateContentTool'
              required:
              - contents
              $defs:
                GenerateContentContent:
                  description: |-
                    One element of [`GenerateContentRequest`]'s `contents` array — a turn
                    carrying optional role + `parts[]`.
                  type: object
                  properties:
                    parts:
                      type: array
                      default: []
                      items: true
                    role:
                      type:
                      - string
                      - 'null'
                      default: null
                GenerateContentFunctionDecl:
                  description: |-
                    One function declaration inside a [`GenerateContentTool`]: name + description +
                    JSON-Schema parameters.
                  type: object
                  properties:
                    description:
                      type:
                      - string
                      - 'null'
                      default: null
                    name:
                      type: string
                    parameters:
                      default: null
                  required:
                  - name
                GenerateContentGenerationConfig:
                  description: '`generationConfig` knobs on a [`GenerateContentRequest`].'
                  type: object
                  properties:
                    frequencyPenalty:
                      description: |-
                        Frequency penalty. Promoted to the canonical `frequency_penalty` slot.
                        <https://ai.google.dev/api/generate-content#GenerationConfig>
                      type:
                      - number
                      - 'null'
                      format: double
                      default: null
                    maxOutputTokens:
                      type:
                      - integer
                      - 'null'
                      format: uint32
                      default: null
                      minimum: 0
                    presencePenalty:
                      description: |-
                        Presence penalty. Promoted to the canonical `presence_penalty` slot.
                        <https://ai.google.dev/api/generate-content#GenerationConfig>
                      type:
                      - number
                      - 'null'
                      format: double
                      default: null
                    responseMimeType:
                      description: |-
                        Response MIME type. `application/json` paired with `response_schema` is
                        the structured-output contract; other values (e.g. `text/x.enum`) pass
                        through opaquely.
                        <https://ai.google.dev/gemini-api/docs/structured-output>
                      type:
                      - string
                      - 'null'
                      default: null
                    responseSchema:
                      description: |-
                        JSON Schema constraining the response (with
                        `response_mime_type: "application/json"`).
                      default: null
                    seed:
                      description: |-
                        Deterministic-sampling seed. Promoted to the canonical `seed` slot.
                        <https://ai.google.dev/api/generate-content#GenerationConfig>
                      type:
                      - integer
                      - 'null'
                      format: int64
                      default: null
                    stopSequences:
                      description: |-
                        Stop sequences. Promoted to the canonical `stop` slot, so it can render
                        as a Chat Completions `stop` or an Anthropic `stop_sequences`.
                        <https://ai.google.dev/api/generate-content#GenerationConfig>
                      type:
                      - array
                      - 'null'
                      default: null
                      items:
                        type: string
                    temperature:
                      type:
                      - number
                      - 'null'
                      format: double
                      default: null
                    topK:
                      description: |-
                        Top-k sampling. Promoted to the canonical `top_k` slot so it translates
                        across protocols (e.g. to an Anthropic upstream's `top_k`).
                        <https://ai.google.dev/api/generate-content#GenerationConfig>
                      type:
                      - integer
                      - 'null'
                      format: uint32
                      default: null
                      minimum: 0
                    topP:
                      type:
                      - number
                      - 'null'
                      format: double
                      default: null
                GenerateContentTool:
                  description: |-
                    One element of [`GenerateContentRequest`]'s `tools` array.

                    A single Google tool object may carry client function declarations
                    (`functionDeclarations`) **and/or** one or more provider-defined ("built-in")
                    tool keys on the same object — `googleSearch`, `codeExecution`,
                    `googleSearchRetrieval`, `urlContext`. Function declarations parse to
                    [`Tool::Function`]; every other key is a provider-defined tool namespaced
                    `google.<key>`, its value preserved verbatim as `args`. The non-function keys
                    ride in `extra`.
                    <https://ai.google.dev/gemini-api/docs/function-calling>
                    <https://ai.google.dev/gemini-api/docs/google-search>
                    <https://ai.google.dev/gemini-api/docs/code-execution>
                  type: object
                  properties:
                    functionDeclarations:
                      type: array
                      items:
                        $ref: '#/$defs/GenerateContentFunctionDecl'
        required: true
      responses:
        '200':
          description: |-
            Generated content (non-streaming).

            Streamed generation — Server-Sent Events, one JSON object per `data:` line. Use the `:streamGenerateContent` action to opt in.
          content:
            application/json:
              schema:
                description: Google Generative Language response envelope. Refer to Google's published spec for the full field set; bitrouter forwards the upstream body unchanged.
                type: object
            text/event-stream:
              schema:
                description: A single Google streaming chunk.
                type: object
        '400':
          description: Bad request — invalid model or malformed request body.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '402':
          description: Payment required — insufficient balance or missing payment proof.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
        '404':
          description: No route found for the requested model.
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: ErrorResponseDoc
                description: |-
                  MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into
                  (`{ "error": { "code": ..., "message": ... } }`). Cloud handlers map to
                  this envelope via `BitrouterError::into_response`.
                type: object
                properties:
                  error:
                    $ref: '#/$defs/ErrorBodyDoc'
                required:
                - error
                $defs:
                  ErrorBodyDoc:
                    type: object
                    properties:
                      code:
                        description: Machine-readable error code (e.g. `unauthorized`, `bad_request`).
                        type:
                        - string
                        - 'null'
                      message:
                        description: Human-readable error description.
                        type: string
                    required:
                    - message
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Anthropic-style API key header.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or JWT
      description: '`Authorization: Bearer <token>` where `<token>` is either an API key issued by the BitRouter console or a JWT minted from a wallet (CAIP-10 issuer).'
tags:
- name: OpenAI Compatible
  description: OpenAI Chat Completions format. Drop-in compatible with the OpenAI Chat Completions API — accepts the same request schema and returns the same response format.
- name: OpenAI Responses
  description: OpenAI Responses API format. Newer stateful-conversation surface; distinct request/response shape from `/v1/chat/completions`.
- name: Anthropic Compatible
  description: Anthropic-format endpoints. Drop-in compatible with the Anthropic Messages API.
- name: Google Compatible
  description: Google Generative Language API format. The URL encodes the model and streaming verb in a single segment (`models/{model}:generateContent` or `:streamGenerateContent`) — same convention as Google's own API.
- name: Discovery
  description: Public read-only endpoints for inspecting the router's configuration — what models and providers it knows about.
- name: BYOK
  description: Bring-Your-Own-Key endpoints. Returns the node's sealed-box public key so the console can encrypt provider keys client-side; the node never sees plaintext on the write path.
- name: Health
  description: Liveness check.
- name: Management
  description: Account-bound management endpoints — API keys, usage, billing, policies, BYOK provider keys, OAuth clients. Every endpoint requires a credential whose principal carries the per-endpoint scope (e.g. `keys:read`, `billing:write`).