{
  "openapi": "3.1.0",
  "info": {
    "title": "Trellis API",
    "version": "1.0.0",
    "description": "Launch surface: a router runs LAUNCH_SURFACE=core by default and then serves only the operations marked `x-launch-surface: core` in this document (chat completions, completions, embeddings, models, keys, prepaid credits, wallet sign-in, x402 per call, generations and receipts, attestation, status). Every other operation answers 404 `not_enabled` (components.responses.NotEnabled) on such a router; `GET /api/v1/status` reports the surface under `data.launch_surface`. Scope: a documented subset of the public HTTP API that the Trellis router implements. It covers the model catalog, chat completions, embeddings, key creation and listing, generations, status, health and receipts, plus the blind-token issuer keys and purchase (present only when the router enables blind tokens) the Oblivious HTTP gateway keys, gateway and relay list (present only when the router enables Oblivious HTTP) the transparency log of keys and configurations with its tiles, checkpoints and witness cosignatures (present only when the router enables it) the Lane: model variants, day-zero candidates and creator royalty claims, Private RAG (answers from documents sent with the question, nothing kept), and the Batch API (many chat or embeddings requests run in the background, with the lines and answers kept sealed outside the database until the results expire). It also covers teams as pseudonymous organisations: roles, passkey and wallet (Solana) members, org budgets and the hash-chained audit log with its export, and characters: Tavern cards called as @character/<id>, with a memory ledger encrypted on the client. It also covers prepaid USDC credits on Solana (deposit transactions, account closure, spend-only balances), wallet sign-in, the hosted x402 facilitator (schemes exact and tab), the Harvest Index and $TRLS holder tiers (membership levels that give access and priority, never a price change: the tier table, early access to newly listed models and advisory polls). Other implemented routes (for example legacy completions, the /v1 aliases, key updates, BYOK, rankings and provider onboarding) are not described here, and a route's absence from this document does not mean it is absent from the router. Endpoint availability, payment modes and model capabilities are deployment-specific. Errors share the OpenRouter-shaped ApiError body; the 4xx responses each operation can return are declared with the reusable responses in components.responses. Chain: Solana; amounts are USDC (6 decimals); addresses are base58 ed25519 public keys and transaction references are base58 signatures. Payment headers: X-PAYMENT / PAYMENT-SIGNATURE (x402 exact), X-Trellis-Tab and X-Trellis-Tab-Voucher (the tab scheme), X-Pay-With (pay with a tokenized stock), X-Wallet-Auth (a wallet spending its change or an operator view).",
    "contact": {
      "name": "Trellis support",
      "email": "support@trellis.example"
    },
    "license": {
      "name": "PolyForm Noncommercial License 1.0.0",
      "identifier": "PolyForm-Noncommercial-1.0.0"
    },
    "x-api-coverage": "subset"
  },
  "externalDocs": {
    "description": "Developer documentation and endpoint overview",
    "url": "/docs/"
  },
  "servers": [
    {
      "url": "/",
      "description": "Current router origin"
    }
  ],
  "security": [
    {}
  ],
  "tags": [
    {
      "name": "Webhooks",
      "description": "Optional signed account event notices; WEBHOOK_SIGNING_ENABLED defaults to false."
    },
    {
      "name": "Data tools",
      "description": "Read-only market data for agents, charged per call: Stock Token prices from Chainlink feeds on Solana, corporate-action (multiplier) status and the inference price index. DATA_TOOLS_ENABLED defaults to false; every route answers 404 data_tools_disabled while it is off. A refusal (unknown symbol, stale feed, paused token, index without fills) is answered before any payment and is never charged."
    },
    {
      "name": "Agent rulebook",
      "description": "Deterministic router enforcement for requests through Trellis only; AGENT_POLICY_ENABLED defaults to false. No on-chain enforcement."
    },
    {
      "name": "Playbooks",
      "description": "One named rulebook that many keys of an account or team follow; a change applies to every following key from its next request. Same switch, roles and validation as the agent rulebook: AGENT_POLICY_ENABLED defaults to false."
    },
    {
      "name": "Network host policy",
      "description": "Versioned signed build pins for future network host admission; existing provider admission is unchanged."
    },
    {
      "name": "Models",
      "description": "Public model catalog and capabilities."
    },
    {
      "name": "Chat",
      "description": "Chat completion requests and streaming responses."
    },
    {
      "name": "Embeddings",
      "description": "Authenticated prepaid embedding requests."
    },
    {
      "name": "Keys",
      "description": "API key creation and account key metadata."
    },
    {
      "name": "Generations",
      "description": "Authenticated generation summaries and details."
    },
    {
      "name": "Status",
      "description": "Public process and router configuration status."
    },
    {
      "name": "Receipts",
      "description": "Public signed receipt retrieval and verification."
    },
    {
      "name": "Saved Routes",
      "description": "Named routing policies callable as model @route/<slug>."
    },
    {
      "name": "Presets",
      "description": "Versioned configs callable as model @preset/<name> or @preset/<name>@<version>: a saved route plus a system prompt, tools and a response_format, with diff and rollback."
    },
    {
      "name": "Agent Sessions",
      "description": "Short-lived, budget-capped session keys for agent runs."
    },
    {
      "name": "Spend Watch",
      "description": "Spend reports, key budgets and alert rules."
    },
    {
      "name": "MCP",
      "description": "Remote Model Context Protocol server: every live model as a tool."
    },
    {
      "name": "Anthropic Messages",
      "description": "Anthropic Messages API (POST /v1/messages, count_tokens) for the Anthropic SDKs and Claude Code, on the same keys, lanes and signed receipts as chat completions."
    },
    {
      "name": "Blind tokens",
      "description": "Unlinkable paid access with Privacy Pass tokens (RFC 9578 type 0x0002, blind RSA per RFC 9474). Present only when the router enables blind tokens."
    },
    {
      "name": "Oblivious HTTP",
      "description": "Oblivious HTTP gateway (RFC 9458) and the relays that reach it, behind the unlinkable lane. Present only when the router enables Oblivious HTTP."
    },
    {
      "name": "Disclosure",
      "description": "What each provider has documented about how it handles a prompt (retention, jurisdiction, legal hold, training use), and the request options that route on it."
    },
    {
      "name": "Lane",
      "description": "Model variants (mainstream, native_low_refusal, abliterated) with license and weights provenance, the rule that keeps restricted variants on attested providers, and the operator's day-zero candidate pipeline."
    },
    {
      "name": "Creator royalties",
      "description": "Claim a model's creator royalty by publishing a challenge in the Hugging Face repository the weights come from."
    },
    {
      "name": "Responses",
      "description": "OpenAI Responses API compatible endpoint for the OpenAI Agents SDK, the Codex CLI and other Responses clients. Stateless: nothing is stored."
    },
    {
      "name": "Private RAG",
      "description": "Answers from documents sent with the question, ranked in memory and kept nowhere, through the router's own embeddings and chat routes."
    },
    {
      "name": "Transparency log",
      "description": "An append-only log (C2SP tlog-tiles, RFC 6962 hashing) of the keys and configurations clients encrypt to or verify against: receipt keys, Oblivious HTTP key configurations, blind-token issuer keys, measurement bundles and sidecar key bindings. Checkpoints are signed notes (C2SP tlog-checkpoint) that witnesses cosign (C2SP tlog-cosignature, cosignature/v1). With TLOG_REKOR_ENABLED, each new checkpoint is also recorded in Sigstore's Rekor log (a hashedrekord entry signed with an ECDSA P-256 anchoring key), an alternative to witnesses. Present only when the router enables it (TLOG_ENABLED)."
    },
    {
      "name": "Ollama",
      "description": "The Ollama API under /ollama for Ollama clients (Open WebUI, Continue, the ollama libraries, LangChain's ChatOllama): set the client's host to <router>/ollama. Chat, generate and embed calls run on the same keys, lanes and signed receipts as chat completions; the key is sent as Authorization: Bearer."
    },
    {
      "name": "Batches",
      "description": "The Batch API: many chat completions or embeddings requests sent in one call and run in the background on the router's worker, with results kept for 24 hours after the batch finishes. A line costs what the same call costs: BATCH_DISCOUNT_BPS is 0 by default. Not on the core launch surface."
    },
    {
      "name": "Rerank",
      "description": "Rerank documents against a query (Cohere and Jina shape), billed per token or per search unit, with a signed receipt."
    },
    {
      "name": "Teams",
      "description": "Anonymous organisations: an owner that is an account or a Solana wallet (base58 address, ed25519 signature over the router's challenge message; a multisig vault cannot sign a message and is not bindable yet), members who join by passkey or wallet, roles (owner, admin, dev, viewer, agent), an org budget, and a hash-chained audit log you can export and verify offline."
    },
    {
      "name": "Status page",
      "description": "The public status page: availability, latency and error budgets per privacy lane and API surface, and incidents with Atom and RSS feeds. The public lane is summed from request outcomes; the attested and unlinkable lanes come only from the differentially private hourly releases at /api/v1/stats (source: dp-noised)."
    },
    {
      "name": "Characters",
      "description": "Tavern character cards (V2 and V3, as JSON or PNG) called as model @character/<id>: public, unlisted or private (encrypted on the client), with a chat endpoint that defaults to the attested lane, group turn order and creator attribution (counts and cost only)."
    },
    {
      "name": "Memory",
      "description": "A memory ledger for characters, encrypted on the client: the router stores ciphertext under a scope it cannot link to a character, and embeddings only when the caller opts in."
    },
    {
      "name": "Skills",
      "description": "Secured Skills Hub for agent skills (a folder with SKILL.md and its scripts and resources): import from a git repository or an archive, a static scan for data exfiltration, prompt injection, obfuscation, dangerous shell commands, untrusted package indexes and binaries, a sha256 content hash of a canonical tar, gated downloads and paid installs (90% to the author, 10% network fee) with a signed receipt. Scanned, not guaranteed."
    },
    {
      "name": "Paid tools",
      "description": "Pay any x402 tool priced in USDC on Solana from a Trellis balance: rulebook price limits, holds, signed tool.call receipts, a listing catalog with daily known-answer canaries, and MCP tools trellis_tools_search and trellis_tools_call. Off unless TOOLS_MARKET_ENABLED."
    },
    {
      "name": "Agent identity",
      "description": "Portable agent identity for opted-in agent profiles (an ERC-8004-shaped registration file served by the router; no identity registry is deployed on Solana yet), paid-receipt feedback, liveness probes and portable track records. Off by default."
    },
    {
      "name": "Credits",
      "description": "Prepaid USDC credits on Solana (program trellis_credits): deposits are spend-only; the only outflows are fair-fail refunds, account-closure refunds and settlement to hosts. Deposits move USDC from the payer's wallet into the program vault under the key's hash; balances are credited once the transaction is finalized."
    },
    {
      "name": "Wallet sign-in",
      "description": "Sign in with a Solana wallet: a server-issued single-use challenge, an ed25519 signature by the wallet's key, and a management key for the wallet's account (w_<address>), the same account a per-call x402 payer's change is kept on."
    },
    {
      "name": "Facilitator",
      "description": "The hosted x402 facilitator (docs §5.2) for schemes exact and tab on Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp; devnet when the router runs there). Non-custodial: funds move payer to payee; the relay key only co-signs as fee payer. The facilitator charges no fee. Request and answer shapes follow Coinbase's facilitator so any x402 seller library can point at this URL. Present only when the router enables it (data.facilitator.enabled in GET /api/v1/status)."
    },
    {
      "name": "HVX",
      "description": "The Harvest Index: the public hourly $/1M-token price of sealed open-model inference per grade (G-S, G-M, G-L), built from paid receipts with self-dealing and circular volume excluded. Public, read-only, cached a minute."
    },
    {
      "name": "Holder tiers",
      "description": "$TRLS holder tiers: the tier table, the tier of the wallet behind a key, early access to newly listed models, and advisory polls. Holder tiers are membership levels with fixed thresholds. Their perks are access and priority only; no tier changes a price, and every caller pays the host's price. Describes current behaviour, which can change. Present only when the router sets thresholds (data.enabled in GET /api/v1/holders/tiers); no thresholds are set by default."
    }
  ],
  "paths": {
    "/api/v1/agents/approvals/{id}/approve-and-allow": {
      "get": {
        "summary": "Preview an approval's ask-first amount change",
        "description": "B118: management or same-team owner/admin auth as Approve. Inference and session keys refused. Only amount-only approvals for the current own rulebook; playbook followers return 409 playbook_linked with playbook_id and playbook_name. AGENT_POLICY_ENABLED false returns 404; actions require AGENT_GUARD_ENABLED. Returns data.field, before_usd, after_usd, amount_usd and policy_sha256. Preview changes nothing.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Exact threshold change; amounts are decimal USD strings."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Not pending, not amount-only, rules changed or playbook followed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      },
      "post": {
        "summary": "Approve and allow next time",
        "description": "B118: same auth and eligibility as GET. In one transaction approves once and saves only approval.above_usd for model calls or actions.approval_above_usd for actions, rounded up to the cent, with the schema version and hash-chained policy_set and approval_approved events. Caps are unchanged. Original single-use retry binding and expiry remain. Changed hash returns 409. Telegram unchanged.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "policy_sha256"
                ],
                "properties": {
                  "policy_sha256": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "data contains approval (existing approval shape), change (the GET preview), policy (updated rulebook), version (schema version) and sha256 (new policy digest)."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Not pending, not amount-only, rules changed or playbook followed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/statements/{yyyy-mm}": {
      "get": {
        "operationId": "getMonthlyStatement",
        "tags": [
          "Statements"
        ],
        "summary": "Download a signed monthly statement",
        "description": "V87: STATEMENTS_ENABLED defaults false; disabled route returns 404. Management and owner/admin keys see the account; ordinary and session keys see only their own attributed movements labelled scope=key. Exact USDC decimal strings reconcile to the ledger in one snapshot: opening + deposits + refunds - usage - separate fees + other changes = closing. Usage groups reconcile to usage. UTC month; usage by settlement time, calls by generation time. Current month is so_far. Months before account creation and future months return 404. Holds, external payments and embedded usage fees are not added to totals. Canonical payload JSON is signed with the existing receipt Ed25519 key and key_id; verify with published receipt keys. Print the account-shell HTML view for PDF. No new storage.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "yyyy-mm",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Signed statement with Cache-Control: no-store",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "payload",
                        "alg",
                        "key_id",
                        "sig"
                      ],
                      "properties": {
                        "alg": {
                          "type": "string",
                          "enum": [
                            "Ed25519"
                          ]
                        },
                        "key_id": {
                          "type": "string"
                        },
                        "sig": {
                          "type": "string",
                          "description": "Base64 signature of canonical payload JSON"
                        },
                        "payload": {
                          "type": "object",
                          "description": "trellis.statement.v1: month, currency, UTC bounds, generated_at, account_created_at, scope, key_hash, opening_balance, deposits, refunds, usage, fees, other_changes, closing_balance, calls, usage_by_model, usage_by_key_agent, usage_by_lane, movements_by_kind, reconciliation, limits. Money and calls are decimal strings. Group ids can be null."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/refunds": {
      "get": {
        "operationId": "listRefunds",
        "tags": [
          "Receipts"
        ],
        "summary": "List make-good refunds",
        "description": "V6 R: MAKEGOOD_ENABLED defaults to false; the route returns 404 while it is off (GET /api/v1/status reports makegood.enabled). Deterministic refunds decided from facts recorded when a call is served or fails: upstream_failure (a per-call payment for a request no provider served, 100%, on-chain), fallback_price (failover to a pricier provider, the price difference), truncated_stream (billed output tokens never delivered), structured_output (the JSON repair answer still does not parse, 100% of the repair call) and unattested_lane (100% plus a host strike). Capped by what the ledger charged; at most one refund per call or payment. Management and owner/admin keys see the account, other keys their own calls; a per-call wallet payer can read its refunds with X-Wallet-Auth signed for this GET (the request path with its query string, and the hash of the empty body). Each issued refund has a signed v1 receipt of kind refund at GET /api/v1/receipts/{id} naming original_receipt_id. Cache-Control: no-store.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 100, default 50",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Refunds, newest first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "rule": {
                            "type": "string",
                            "enum": [
                              "upstream_failure",
                              "fallback_price",
                              "truncated_stream",
                              "structured_output",
                              "unattested_lane"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "issued"
                            ]
                          },
                          "amount": {
                            "type": "string",
                            "description": "Refund in USD, exact decimal"
                          },
                          "charged": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "generation_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "receipt_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "receipt_url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "provider": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "strike": {
                            "type": "boolean"
                          },
                          "evidence": {
                            "type": "object"
                          },
                          "settlement": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "enum": [
                              "credit",
                              "onchain",
                              null
                            ]
                          },
                          "onchain": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "usdc_units": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "owed",
                                  "batched",
                                  "paid"
                                ]
                              }
                            }
                          },
                          "detected_at": {
                            "type": "string"
                          },
                          "issued_at": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List owned destinations without secrets",
        "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at trellis.example. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List owned destinations without secrets"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Limit or state conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Create a destination and reveal its signing secret once",
        "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at trellis.example. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "Create a destination and reveal its signing secret once"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Limit or state conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "webhook_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "events": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "enum": [
                        "spend.alert",
                        "agent.alert",
                        "approval.requested",
                        "approval.decided",
                        "deposit.credited",
                        "agreement.funded",
                        "agreement.disputed",
                        "agreement.ruled",
                        "host.status_changed",
                        "refund.issued"
                      ]
                    }
                  }
                },
                "required": [
                  "webhook_url",
                  "events"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/webhooks/{id}": {
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Update event subscriptions",
        "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at trellis.example. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Update event subscriptions"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Limit or state conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "events": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "enum": [
                        "spend.alert",
                        "agent.alert",
                        "approval.requested",
                        "approval.decided",
                        "deposit.credited",
                        "agreement.funded",
                        "agreement.disputed",
                        "agreement.ruled",
                        "host.status_changed",
                        "refund.issued"
                      ]
                    }
                  }
                },
                "required": [
                  "events"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "x-launch-surface": "all"
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Remove an independent destination",
        "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at trellis.example. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Remove an independent destination"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Limit or state conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/webhooks/{id}/rotate": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Rotate and reveal a replacement signing secret once",
        "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at trellis.example. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Rotate and reveal a replacement signing secret once"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Limit or state conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/webhooks/{id}/revoke": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Erase signing secret and stop future delivery",
        "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at trellis.example. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Erase signing secret and stop future delivery"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Limit or state conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/webhooks/{id}/deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Read the last 100 attempt metadata entries",
        "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at trellis.example. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Read the last 100 attempt metadata entries"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Limit or state conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/webhooks/{id}/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Queue an endpoint check event",
        "description": "WEBHOOK_SIGNING_ENABLED defaults to false; switched on at trellis.example. Requires owner/admin access outside agent sessions. Account-wide destinations require a management key; other callers manage only linked destinations scoped to their own key. Secrets appear only on creation or rotation. All responses use Cache-Control: no-store. See /docs/#signed-webhooks for exact-byte HMAC verification, five-minute timestamp tolerance, signed event_id binding and durable duplicate suppression. Delivery can repeat after a crash. Activity discovery has bounded source-retention limits. Approval and operated host status writers queue references atomically. Direct database writes do not create those notices.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "202": {
            "description": "Queue an endpoint check event"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Limit or state conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/activity": {
      "get": {
        "operationId": "listActivity",
        "summary": "List account activity",
        "description": "Calls (with receipt ids and verify links), agent approvals and rule decisions, alerts, deposits and balance changes, and agreement events, newest first, in one item shape with exact USDC amounts. A key sees its own activity; management, owner and admin keys see the account within their team boundaries. format=csv returns this page as CSV with X-Next-Cursor when another page exists.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "call, approval, alert, deposit, agreement, policy, balance or topup",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "description": "64-hex key hash to filter by",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "model",
            "in": "query",
            "required": false,
            "description": "Model id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "ISO 8601 timestamp with timezone, inclusive",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "ISO 8601 timestamp with timezone, exclusive",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 100, default 50",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "json (default) or csv",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/inbox": {
      "get": {
        "operationId": "listInbox",
        "summary": "List items that need attention",
        "description": "Pending approvals with their expiry, alerts, deposits, key auto top-ups, agreement events and status updates for hosts the account operates, under the same access rules as /api/v1/activity. Pass since (the seen time the browser keeps) to mark newer items. B119: when LOW_BALANCE_ALERTS_ENABLED is true, account-scope inboxes also include low-balance crossings with kind low_balance, id, at, title, amount (decimal USD balance), status null, href /dashboard/#money, and unread. Session and ordinary key-scope inboxes cannot see these account alerts.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO 8601 seen time, not in the future",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/inbox/seen": {
      "post": {
        "operationId": "markInboxSeen",
        "summary": "Return a seen time for the displayed inbox",
        "description": "Validates the key and returns the seen time to keep in the browser. Nothing is stored on the server.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "through",
            "in": "query",
            "required": true,
            "description": "ISO 8601 time of the displayed snapshot, not in the future",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/network/stats": {
      "get": {
        "operationId": "networkStats",
        "summary": "Read network statistics",
        "description": "Present only with NETWORK_STATS_ENABLED (default false). Public read-only snapshots cached at most 30 seconds; HTTP freshness is limited to remaining snapshot lifetime. Host counts include only network hosts. Attested capacity requires fresh successful hardware attestation and admission evidence. Public-lane token ranges use 100,000-token buckets, not differential privacy, from retained generation records only. Private-lane host totals are unavailable: existing DP counters have no host dimension or 7/30-day history. Null means absent records or a disabled optional source. Bond amounts retain index freshness. Waitlist counts express interest only.",
        "security": [],
        "responses": {
          "200": {
            "description": "Network snapshot",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                },
                "description": "public, max-age=<remaining snapshot seconds>, must-revalidate"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/NetworkStats"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "Network statistics are disabled"
          },
          "503": {
            "description": "Aggregate source unavailable; no stale response is served",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents": {
      "get": {
        "operationId": "listAgents",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "List account agent keys",
        "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Includes effective rulebooks, kill state, rolling spend plus reservations and caps. Off returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "stopped_until": {
                            "type": "string",
                            "format": "date-time",
                            "description": "B117: Optional timed stop deadline; alerts retain the deadline captured at the stop and include it in webhook and Telegram delivery."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/me": {
      "get": {
        "operationId": "agentMe",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Read the calling key’s rulebook",
        "description": "Includes own and inherited parent rulebooks, remaining rolling caps and kill state. Optional autonomy reports rung, since, clean_requests, last_clean_at, caps_multiplier and next (rung, after_days, clean_requests, caps_multiplier, elapsed_days, days_remaining, requests_remaining), or null at the top. effective_caps scales only spending caps. Progress resets on selected deny, kill or recorded breaker events and on rulebook saves. A session and its parent must both pass. Off returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "stopped_until": {
                          "type": "string",
                          "format": "date-time",
                          "description": "B117: Effective timed stop deadline; omitted when running or any stopped inherited policy has no deadline. Also reported by MCP trellis_agent_rules. Each timed policy in policies reports its own deadline."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/approvals": {
      "get": {
        "tags": [
          "Agent rulebook"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Approval list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AgentApproval"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Approval is no longer pending"
          }
        },
        "operationId": "listAgentApprovals",
        "summary": "List principal-visible approvals",
        "description": "AGENT_POLICY_ENABLED defaults false; off returns 404. Management key or same-account team owner/admin. Up to 100 newest rows. Pending by default. Expiry ends validity but does not delete approval rows.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "approved",
                "denied",
                "expired",
                "used"
              ],
              "default": "pending"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/approvals/{id}": {
      "get": {
        "tags": [
          "Agent rulebook"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Status only",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "id",
                        "status",
                        "expires_at"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "approved",
                            "denied",
                            "expired",
                            "used"
                          ]
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Approval is no longer pending"
          }
        },
        "operationId": "getAgentApprovalStatus",
        "summary": "Poll approval status",
        "description": "Principal or the requesting key; returns only id, status and expires_at. Off returns 404.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/approvals/{id}/approve": {
      "post": {
        "tags": [
          "Agent rulebook"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Approval result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Approval is no longer pending"
          }
        },
        "operationId": "approveAgentApproval",
        "summary": "Approve a pending approval",
        "description": "Management key or same-account team owner/admin of the requesting key. Session and ordinary agent keys cannot decide. Records the principal key hash and a chained event. Expired or completed rows return 409. Off returns 404. Retry inference with X-Agent-Approval: <id> after approval; it is single-use, binds key/model/lane/tools/output token limit, and permits estimated cost no greater than the approved ceiling. All rulebook restrictions still apply. AGENT_APPROVAL_TTL_S defaults to 900 seconds from request time.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/approvals/{id}/deny": {
      "post": {
        "tags": [
          "Agent rulebook"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Approval result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Approval is no longer pending"
          }
        },
        "operationId": "denyAgentApproval",
        "summary": "Deny a pending approval",
        "description": "Management key or same-account team owner/admin of the requesting key. Session and ordinary agent keys cannot decide. Records the principal key hash and a chained event. Expired or completed rows return 409. Off returns 404. Retry inference with X-Agent-Approval: <id> after approval; it is single-use, binds key/model/lane/tools/output token limit, and permits estimated cost no greater than the approved ceiling. All rulebook restrictions still apply. AGENT_APPROVAL_TTL_S defaults to 900 seconds from request time.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/check": {
      "post": {
        "operationId": "checkAgentPolicy",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Evaluate an Intent without recording it",
        "description": "Calling API key. Returns a deterministic decision with no event writes or automatic kill. Off returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentDecision"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentIntent"
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/policy": {
      "get": {
        "operationId": "getAgentPolicy",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Read a rulebook",
        "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Off returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentPolicyResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      },
      "put": {
        "operationId": "putAgentPolicy",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Set a rulebook",
        "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Replaces the specification while preserving existing kill state. Off returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentPolicyResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentPolicy"
              }
            }
          }
        },
        "x-launch-surface": "all"
      },
      "delete": {
        "operationId": "deleteAgentPolicy",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Remove a rulebook",
        "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Removes this key’s own rulebook; a session’s inherited parent rulebook still applies. Off returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/playbooks": {
      "get": {
        "operationId": "listPlaybooks",
        "tags": [
          "Playbooks"
        ],
        "summary": "List playbooks",
        "description": "Management key, or a team owner or admin; viewers, devs, agent keys and session keys are refused. A management key sees every playbook of the account; a team owner or admin sees its team's and the account-wide ones. Each lists how many keys follow it and the following keys the caller manages. Off (AGENT_POLICY_ENABLED false) returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Playbook"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      },
      "post": {
        "operationId": "createPlaybook",
        "tags": [
          "Playbooks"
        ],
        "summary": "Create a playbook",
        "description": "Management key, or a team owner or admin; viewers, devs, agent keys and session keys are refused. A team owner or admin creates a playbook for its own team; a management key creates an account-wide one, or one for a team it owns with team_id. Version starts at 1. Off (AGENT_POLICY_ENABLED false) returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlaybookInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Playbook"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "playbook_name_taken or playbook_limit_reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/playbooks/{id}": {
      "get": {
        "operationId": "getPlaybook",
        "tags": [
          "Playbooks"
        ],
        "summary": "Read a playbook",
        "description": "Management key, or a team owner or admin; viewers, devs, agent keys and session keys are refused. Adds the latest 50 recorded changes, newest first. Off (AGENT_POLICY_ENABLED false) returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Playbook"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "changes": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/PlaybookChange"
                              }
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      },
      "put": {
        "operationId": "updatePlaybook",
        "tags": [
          "Playbooks"
        ],
        "summary": "Change a playbook",
        "description": "Management key, or a team owner or admin; viewers, devs, agent keys and session keys are refused. Account-wide playbooks change only with a management key. New rules raise version by one and are copied, in the same transaction, to every key that follows the playbook, which uses them from its next request. Unchanged name and rules change nothing (changed false). For a team the change is in the team audit log, and a change of rules is in the inbox of the team's owners and admins. Off (AGENT_POLICY_ENABLED false) returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlaybookUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Playbook"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "changed": {
                              "type": "boolean"
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "playbook_name_taken",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      },
      "delete": {
        "operationId": "deletePlaybook",
        "tags": [
          "Playbooks"
        ],
        "summary": "Delete a playbook",
        "description": "Management key, or a team owner or admin; viewers, devs, agent keys and session keys are refused. Refused with 409 playbook_followed and metadata.followers while keys follow the playbook, unless unlink=copy: each following key then keeps the playbook's rules as its own rulebook. Off (AGENT_POLICY_ENABLED false) returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "unlink",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "copy"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "id",
                        "deleted",
                        "unlinked"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "deleted": {
                          "const": true
                        },
                        "unlinked": {
                          "type": "integer",
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "playbook_followed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/playbook": {
      "post": {
        "operationId": "followPlaybook",
        "tags": [
          "Playbooks"
        ],
        "summary": "Follow a playbook, or stop following",
        "description": "Management key or owner/admin of the target key's account and team, with the same permissions as editing that key. With a playbook_id, the key's rules become that playbook's current rules (its stop state is kept); a team playbook takes keys of that team only (409 playbook_team_mismatch). With null, the key stops following and keeps the playbook's current rules as its own. While a key follows a playbook, PUT and DELETE on its own rulebook answer 409 playbook_linked. Off (AGENT_POLICY_ENABLED false) returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlaybookFollow"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PlaybookFollowResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "playbook_team_mismatch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/kill": {
      "post": {
        "operationId": "killAgent",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Stop an agent",
        "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. A committed kill is read on the next request by every replica, without policy caching. Requires an existing rulebook. Off returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentPolicyResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "until": {
                    "type": "string",
                    "format": "date-time",
                    "description": "B117: Optional ISO time with timezone, future and at most 30 days ahead; omitted stops until manual Resume. The next enforcement check after expiry clears the stop atomically and appends a resume event with reason scheduled."
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 160
                  }
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/resume": {
      "post": {
        "operationId": "resumeAgent",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Resume an agent",
        "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Clears kill state without changing the specification. Off returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentPolicyResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/replay": {
      "post": {
        "operationId": "replayAgentPolicy",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Replay a draft rulebook on the last days of recorded activity",
        "description": "Same permissions as setting that key’s rulebook. Evaluates the draft against up to 5,000 of the key’s recorded calls (its own and its session keys’: model, lane, cost, tokens and time, never the text) and Agent Guard checks in the window, oldest first, with running caps, calls per hour, windows, breakers, autonomy and Stop. Read only: nothing is saved, charged or changed. Ten a minute per calling key. What the record cannot tell is listed in notes. Off returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "policy"
                ],
                "properties": {
                  "policy": {
                    "$ref": "#/components/schemas/AgentPolicy"
                  },
                  "days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 7,
                    "default": 7
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentReplay"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/events": {
      "get": {
        "operationId": "agentEvents",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Read policy events",
        "description": "Management key or owner/admin of the target key’s account and team, with the same permissions as editing that key. Newest first, 50 per page. next_cursor is a before-id cursor. Metadata-only hash chain; 90-day retention when the cleanup worker runs. Off returns 404.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/network/hosts": {
      "post": {
        "summary": "Apply or re-apply a network host using existing wallet authentication",
        "description": "Available only with NETWORK_HOSTS_ENABLED=true; default false. See /docs/#network-host-signup. Policy offer terms enable shadow offers during probation; signup does not activate payouts. Scheduled renewal checks the current signed policy without promoting hosts to live. Failed attestation blocks selection; policy refusal rejects the host and disables offers. Admission records attested retention with the policy version and leaves jurisdiction, legal hold and training use undeclared; rejection clears the disclosure profile.",
        "responses": {
          "200": {
            "description": "Current record",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "provider_id",
                    "status",
                    "reasons",
                    "dashboard"
                  ],
                  "properties": {
                    "provider_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "probation",
                        "rejected",
                        "pending"
                      ]
                    },
                    "reasons": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "dashboard": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "New host record",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "provider_id",
                    "status",
                    "reasons",
                    "dashboard"
                  ],
                  "properties": {
                    "provider_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "probation",
                        "rejected",
                        "pending"
                      ]
                    },
                    "reasons": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "dashboard": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "security": [
          {
            "WalletAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "name",
                  "endpoint",
                  "payout_address",
                  "models"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 60
                  },
                  "endpoint": {
                    "type": "string",
                    "format": "uri",
                    "description": "Sidecar root HTTPS URL. HTTP is recorded as rejected."
                  },
                  "payout_address": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$"
                  },
                  "models": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 8,
                    "uniqueItems": true,
                    "items": {
                      "type": "string",
                      "maxLength": 160
                    }
                  },
                  "contact": {
                    "type": "string",
                    "maxLength": 120
                  }
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/network/hosts/{provider_id}/status": {
      "get": {
        "summary": "Read public network host admission status",
        "description": "Available only with NETWORK_HOSTS_ENABLED=true; default false. See /docs/#network-host-signup. Policy offer terms enable shadow offers during probation; signup does not activate payouts.",
        "responses": {
          "200": {
            "description": "Current record",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "provider_id",
                    "status",
                    "reasons",
                    "attested",
                    "probation_until",
                    "weight"
                  ],
                  "properties": {
                    "provider_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "reasons": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "attested": {
                      "type": "boolean"
                    },
                    "probation_until": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "weight": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 1,
                      "description": "Current network selector multiplier, rounded to two decimals; highest across eligible model offers, not a traffic percentage. Probation starts at 0.1 and health can reduce it. Zero with hosting off, refusal, stale or failed attestation, unhealthy evidence, or no eligible offers. Status route is absent when hosting is disabled."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "provider_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/network/hosts/{provider_id}/credential": {
      "put": {
        "summary": "Supply an operator-generated sidecar inference credential",
        "description": "Available only with NETWORK_HOSTS_ENABLED=true; default false. See /docs/#network-host-signup. Policy offer terms enable shadow offers during probation; signup does not activate payouts.",
        "responses": {
          "200": {
            "description": "Current record",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provider_id": {
                      "type": "string"
                    },
                    "credential_configured": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "security": [
          {
            "WalletAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "provider_id",
                  "api_key"
                ],
                "properties": {
                  "provider_id": {
                    "type": "string",
                    "description": "Signed provider ID must match path."
                  },
                  "api_key": {
                    "type": "string",
                    "minLength": 16,
                    "maxLength": 500,
                    "writeOnly": true
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "provider_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/ledger": {
      "get": {
        "operationId": "agentLedger",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Read activity and receipt ledger",
        "description": "Principal only; same account/team permissions as editing this key. AGENT_POLICY_ENABLED defaults false; off returns 404. from inclusive, to exclusive ISO timestamps. Newest first, at most 100 rows; opaque next_cursor. JSON data.rows and data.totals_per_day (full range, UTC); CSV streams this page with X-Next-Cursor. Correlated rows group policy events and exact generation charges/tokens, receipt_id, verify_url, receipts array, approval_id only if used, policy_sha256 and policy_sha256s. Denials charge zero. Unlinked historical events/generations remain separate; associations are not inferred. Policy events/links have 90-day retention while cleanup runs. Errors before evaluation or generation creation are absent. No prompt or answer text. Router enforcement through Trellis only, no on-chain enforcement. Verify links require using the existing checker.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded request page and full-range daily totals, or a CSV page",
            "headers": {
              "X-Next-Cursor": {
                "description": "CSV continuation cursor",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "rows",
                        "totals_per_day"
                      ],
                      "properties": {
                        "rows": {
                          "type": "array",
                          "maxItems": 100,
                          "items": {
                            "type": "object"
                          }
                        },
                        "totals_per_day": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/me/ledger": {
      "get": {
        "operationId": "agentSelfLedger",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Read activity and receipt ledger",
        "description": "Calling key only, including session keys. AGENT_POLICY_ENABLED defaults false; off returns 404. from inclusive, to exclusive ISO timestamps. Newest first, at most 100 rows; opaque next_cursor. JSON data.rows and data.totals_per_day (full range, UTC); CSV streams this page with X-Next-Cursor. Correlated rows group policy events and exact generation charges/tokens, receipt_id, verify_url, receipts array, approval_id only if used, policy_sha256 and policy_sha256s. Denials charge zero. Unlinked historical events/generations remain separate; associations are not inferred. Policy events/links have 90-day retention while cleanup runs. Errors before evaluation or generation creation are absent. No prompt or answer text. Router enforcement through Trellis only, no on-chain enforcement. Verify links require using the existing checker.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded request page and full-range daily totals, or a CSV page",
            "headers": {
              "X-Next-Cursor": {
                "description": "CSV continuation cursor",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "rows",
                        "totals_per_day"
                      ],
                      "properties": {
                        "rows": {
                          "type": "array",
                          "maxItems": 100,
                          "items": {
                            "type": "object"
                          }
                        },
                        "totals_per_day": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/alerts": {
      "get": {
        "operationId": "agentAlerts",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Read owner alerts",
        "description": "AGENT_POLICY_ENABLED defaults false; off returns 404. Same principal permissions as editing the key. Newest 100 entries per account, filtered to this key, retained up to 90 days. Opt in with alerts: {}. Rolling cap percentages count charged spend plus reservations, with one notice per threshold per window-duration cooldown. Repeated denials, kills and new approvals add entries. Reuses enabled Spend Watch webhooks (currently unsigned) and authorized Telegram links; email has no account destination. Without a selected linked channel delivery becomes feed_only. Worker delivery every minute, 10 notices/account/minute, up to 20 destinations/channel and three attempts five minutes apart. At-least-once delivery; a crash may repeat a notice. No prompt or answer text. Router enforcement for Trellis requests only, no on-chain enforcement.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Alert feed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "stopped_until": {
                            "type": "string",
                            "format": "date-time",
                            "description": "B117: Optional timed stop deadline; alerts retain the deadline captured at the stop and include it in webhook and Telegram delivery."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/hosts": {
      "get": {
        "tags": [
          "Hosts"
        ],
        "operationId": "listHosts",
        "summary": "List public hosts with a hardware verification record",
        "description": "Available only with HOST_DASHBOARD_ENABLED=true (default false). Includes stale or suspended hardware hosts, labelled by their current verification status; excludes applications, unverified providers and development-only evidence. No payout settings or exact earnings.",
        "security": [],
        "responses": {
          "200": {
            "description": "Public host fields; Cache-Control: public, max-age=30.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/HostPublic"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/hosts/{providerId}": {
      "get": {
        "tags": [
          "Hosts"
        ],
        "operationId": "getHost",
        "summary": "Read one host’s evidence and invoice band",
        "description": "With NETWORK_BONDS_ENABLED, data.bond contains host_id, contract, chain_id, asset, decimals, matched_operator, amount_units, active_units, unbonding {amount_units, available_at}, delisted, indexed_block, fresh, checked_at and slashes [{id, host_id, amount_units, reason, evidence_root, executable_at, dispute_hash, status, transactions [{event, hash, url}]}]. Amounts are decimal base-unit strings. Curated hosts have null bonds. Available only with HOST_DASHBOARD_ENABLED=true (default false). Reuses existing attestation, measurements, proof-time and host-root records. Hardware evidence and recorded measurements do not establish build admission approval, source equivalence or prompt handling. Detail responses always use Cache-Control: no-store and Vary: X-Wallet-Auth. Earnings are lifetime settlement invoice totals after provider fees, including paid invoices and excluding the open hour. USDC units have six decimal places.",
        "security": [],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Wallet-Auth",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional operator view: X-Wallet-Auth <base58 address>:<unixSeconds>:<base58 ed25519 signature>, the signature over the six lines trellis:wallet-auth:v2, GET, the router's host, the path /api/v1/hosts/{encodeURIComponent(providerId)}, <unixSeconds> and sha256(scope), where scope is exactly GET /api/v1/hosts/{encodeURIComponent(providerId)} (see the WalletAuth security scheme). Five-minute validity and single use. The signing wallet must equal providers.operator (base58, case-sensitive). This signature authorizes no payment."
          }
        ],
        "responses": {
          "200": {
            "description": "Public evidence with coarse bands; operator fields present only for the signed host operator.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HostDetail"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "description": "Existing evidence endpoint could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/models": {
      "get": {
        "tags": [
          "Models"
        ],
        "operationId": "listModels",
        "summary": "List public live models",
        "parameters": [
          {
            "name": "supported_parameters",
            "in": "query",
            "required": false,
            "description": "Comma-separated capabilities to require.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lane",
            "in": "query",
            "required": false,
            "description": "public (default) lists every live model. attested lists only models with at least one endpoint served under attested retention with a fresh attestation right now. unlinkable lists the same models where the router serves that lane, through Oblivious HTTP or over its Tor onion service (otherwise 501).",
            "schema": {
              "type": "string",
              "enum": [
                "public",
                "attested",
                "unlinkable"
              ],
              "default": "public"
            }
          },
          {
            "name": "variant",
            "in": "query",
            "required": false,
            "description": "Comma-separated variants to keep: mainstream, native_low_refusal, abliterated. A restricted variant (native_low_refusal, abliterated) is listed only while an attested provider whose attestation reports the in-enclave classifier serves it, and only such endpoints are counted for it.",
            "schema": {
              "type": "string",
              "examples": [
                "abliterated,native_low_refusal"
              ]
            }
          },
          {
            "name": "output_modalities",
            "in": "query",
            "required": false,
            "description": "Comma-separated output modalities to keep (text, embeddings, rerank, ...); a model is kept when it outputs any of them. all, or unset, keeps every model.",
            "schema": {
              "type": "string",
              "examples": [
                "rerank"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Models matching the requested capabilities.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Model"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "501": {
            "$ref": "#/components/responses/LaneNotAvailable"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "description": "While a newly listed model's early-access window runs, its entry carries early_access with the time it opens to everyone and to the caller; send a key to get the caller's own time.",
        "x-launch-surface": "core"
      }
    },
    "/api/v1/chat/completions": {
      "post": {
        "tags": [
          "Chat"
        ],
        "operationId": "createChatCompletion",
        "summary": "Create a chat completion",
        "description": "Supports standard JSON responses and Server-Sent Events when stream is true. A model must support requested capabilities such as tools or response_format. Auth may use a bearer key, wallet authentication, or the per-call payment flow. A 402 response can contain a quote; follow its payment instructions before retrying the exact request. When the router has x402 enabled, the 402 body is also an x402 v1 payment requirement (x402Version, accepts) and the PAYMENT-REQUIRED header carries the same requirement as x402 v2: build the exact-scheme USDC TransferChecked transaction with extra.feePayer as fee payer, sign it as the payer and retry with X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2); the facilitator co-signs and submits it and the paid response carries the settlement in X-PAYMENT-RESPONSE and PAYMENT-RESPONSE. Change stays on the payer's wallet account and can be spent with X-Wallet-Auth. A tab (the tab x402 scheme) pays instead with X-Trellis-Tab and X-Trellis-Tab-Voucher: the payer's session key signs a cumulative voucher per request and the escrowed cap settles on close. X-Pay-With names a tokenized-stock mint to pay with instead of USDC credits. If that answer is lost, the same request with the same payment and a PAYMENT-RECOVERY signature gets the kept answer again, byte for byte, without a second payment. Two opt-in modes run several billed calls for one request and are off unless the router enables them: model trellis/council (a panel of models plus a judge; see the council field) and verify \"dual\" (the same request to two providers; see the verification field). Both are non-streaming only. Where the router enables blind tokens, Authorization: PrivateToken token=<base64url> pays with one token instead of a key (see the Blind tokens tag): the call is charged to a pooled account, the signed receipt carries the token's nullifier and no payer, and the token is spent only if the call is served. A token pays for at most its value, so a request whose worst case costs more is refused with 402 token_value_too_low; council mode and verify are refused with 400 blind_unsupported. A refused, unknown, expired or already spent token is a 401 that carries WWW-Authenticate: PrivateToken challenge=\"...\". Disclosure ceilings and lanes apply to token calls exactly as to key calls. Lane unlinkable, where the router enables Oblivious HTTP, is served only for a request that arrives through the gateway (POST /api/v1/ohttp/gateway) by way of an independent relay, paid with a blind token and never a key, and only by attested providers; where the router serves the lane over Tor (data.lanes.unlinkable.via in GET /api/v1/status includes onion), a request that arrives through its onion service (data.onion.url) and is paid with a blind token qualifies in the same way, streamed or not, and a clearnet request cannot claim to have come that way; otherwise it is refused with 403 lane_requires_anonymous_auth for an API key or a wallet (unless provider.lane_downgrade is attested, which serves it on lane attested instead), 403 unlinkable_requires_relay or unlinkable_requires_independent_relay, 401 unlinkable_requires_token with the token challenge when no token is presented, or 503 no_attested_endpoint when no attested endpoint can serve the model. A request that arrives through an independent relay, is paid with a blind token and names no lane is served on lane unlinkable. On lanes attested and unlinkable the router never falls back to an endpoint without a fresh, verified attestation: it answers 503 no_attested_endpoint instead. Within a lane endpoints are weighted uptime x quality x attested_bonus / price^2 (attested_bonus 1.25 on public, 1 elsewhere). On attested and unlinkable the router still terminates TLS and sees the prompt; end-to-end encryption through the router is planned. Through the gateway, streaming needs chunked Oblivious HTTP (message/ohttp-chunked-req), where the router enables it; stream true in a message/ohttp-req is refused with 400 stream_unsupported. Holds: before a call is sent the router holds its worst case, which is a bound and not an estimate. Prompt tokens are bounded by the UTF-8 bytes of the text (non-ASCII text counts the larger of its bytes and its NFKD-normalised bytes; characters are never divided by a ratio), plus fixed template allowances (64 tokens per request, 16 per message, 256 when tools or functions are present); every other forwarded field that is a string, array or object (tools, functions, response_format, stop, tool calls, unknown fields) counts the bytes of its indented JSON. Top-level numbers and booleans, model, stream, stream_options and router-only fields are not counted. The same bound is used for the context check and for a key's tokens-per-minute limit. Image, audio, video and file parts count the per-item token limit the model's catalog entry declares (input_token_limits in GET /api/v1/models); such input to a model that declares none, an unknown content-part type, a provider-side tool (a tools entry whose type is not function) and web_search_options are refused with 400 unboundable_input. An explicit output cap is always sent to the provider: max_tokens (and max_completion_tokens when the caller sent it) is the smallest of the caller's value, the catalog's output limit for the model (16,384 when the catalog has none) and the room the context leaves after the prompt bound. A higher value is clamped, not refused, and an omitted value is filled in; the same holds for council members, the judge and dual verification. The hold is the prompt bound at the dearest input price the model lists (the prompt price, or the cache write or read price if dearer), plus the output cap for every completion asked for (n) at the dearer of the completion and reasoning price, plus the per-request price per completion and the per-image price per image. The caller is charged at most the hold, always: when a provider reports usage priced above it, the charge stays at the hold, usage.cost_details.over_hold (number) and the receipt's cost_details.over_hold (USD string) carry the list price of the reported usage, and the provider is paid no more than the caller was charged. When a provider reports no usage at all, prompt tokens are billed at a third of the bound and marked estimated. A hold is renewed while its request is in flight; one that expired mid-request is still charged when the request settles, capped at the hold. top_logprobs must be an integer from 0 to 20 (400 invalid_request).",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "WalletAuth": []
          },
          {
            "PrivateToken": []
          },
          {}
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Referer"
          },
          {
            "$ref": "#/components/parameters/Title"
          },
          {
            "$ref": "#/components/parameters/Payment"
          },
          {
            "$ref": "#/components/parameters/PaymentSignature"
          },
          {
            "$ref": "#/components/parameters/PaymentRecovery"
          },
          {
            "$ref": "#/components/parameters/TrellisTab"
          },
          {
            "$ref": "#/components/parameters/TrellisTabVoucher"
          },
          {
            "$ref": "#/components/parameters/PayWith"
          },
          {
            "$ref": "#/components/parameters/DisclosureMax"
          },
          {
            "$ref": "#/components/parameters/Lane"
          },
          {
            "$ref": "#/components/parameters/LaneDowngrade"
          },
          {
            "$ref": "#/components/parameters/DecisionTag"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Completion JSON, or SSE events followed by data: [DONE] when stream is true.",
            "headers": {
              "X-Trellis-Route": {
                "$ref": "#/components/headers/RouteExplanation"
              },
              "X-Trellis-Json-Check": {
                "description": "V83: valid or invalid for JSON responses; pending for streams, or pending; repair-unsupported when repair was requested. Final stream validation is in receipt.structured_output, not a changed header.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "valid",
                    "invalid",
                    "pending",
                    "pending; repair-unsupported"
                  ]
                }
              },
              "X-Trellis-Disclosure": {
                "$ref": "#/components/headers/Disclosure"
              },
              "X-Trellis-Lane": {
                "$ref": "#/components/headers/LaneServed"
              },
              "X-Receipt-Id": {
                "$ref": "#/components/headers/ReceiptId"
              },
              "Inference-Id": {
                "$ref": "#/components/headers/InferenceId"
              },
              "X-Generation-Id": {
                "$ref": "#/components/headers/GenerationId"
              },
              "X-Trellis-Policy-Hash": {
                "$ref": "#/components/headers/PolicyHash"
              },
              "X-PAYMENT-RESPONSE": {
                "description": "Present on a call paid by x402: base64 JSON {success: true, transaction: <base58 Solana signature>, network, payer}.",
                "schema": {
                  "type": "string"
                }
              },
              "PAYMENT-RESPONSE": {
                "description": "Present on a call paid by x402: base64 JSON {success: true, transaction: <base58 Solana signature>, network, payer}.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "council": {
                      "$ref": "#/components/schemas/CouncilResult"
                    },
                    "verification": {
                      "$ref": "#/components/schemas/VerificationResult"
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE data events; event data carries JSON chunks."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/DisclosureUnavailable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "501": {
            "$ref": "#/components/responses/LaneNotAvailable"
          },
          "503": {
            "$ref": "#/components/responses/DisclosureProviderDown"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          },
          "504": {
            "description": "`provider_timeout`: the provider had accepted the request and did not answer within the router's time limit. It may bill the call, so the call is charged what it ordered from that provider (the prompt bound and the output limit that was sent; an embeddings call, which has no output, its input bound) and no other provider is tried. The body carries `error`, `id`, `usage` and the signed `receipt` (finish reason `timeout`, tokens marked estimated).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "id",
                    "usage",
                    "receipt"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "const": 504
                        },
                        "type": {
                          "const": "provider_timeout"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    "id": {
                      "type": "string"
                    },
                    "usage": {
                      "type": "object"
                    },
                    "receipt": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/embeddings": {
      "post": {
        "tags": [
          "Embeddings"
        ],
        "operationId": "createEmbeddings",
        "summary": "Create embeddings",
        "description": "Uses a prepaid API key, or no key with the per-call payment flow (HTTP 402, including x402 when enabled). Input may be a string or a non-empty array with at most 256 items (strings, token ids, or token-id arrays). The hold is a bound, not an estimate: each input counts its UTF-8 bytes (or one token per id) plus 16 tokens, plus 64 per request, at the dearest input price the model lists, plus one pico; the charge never exceeds the hold, and the receipt carries cost_details.over_hold when a provider reported usage priced above it. An input shape that cannot be bounded is refused with 400 unboundable_input. Where the router enables blind tokens, Authorization: PrivateToken token=<base64url> pays with one token, exactly as for chat completions.",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "PrivateToken": []
          },
          {}
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Payment"
          },
          {
            "$ref": "#/components/parameters/PaymentSignature"
          },
          {
            "$ref": "#/components/parameters/PaymentRecovery"
          },
          {
            "$ref": "#/components/parameters/TrellisTab"
          },
          {
            "$ref": "#/components/parameters/TrellisTabVoucher"
          },
          {
            "$ref": "#/components/parameters/DisclosureMax"
          },
          {
            "$ref": "#/components/parameters/Lane"
          },
          {
            "$ref": "#/components/parameters/LaneDowngrade"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Embedding response with usage and signed receipt.",
            "headers": {
              "X-Trellis-Route": {
                "$ref": "#/components/headers/RouteExplanation"
              },
              "X-Trellis-Disclosure": {
                "$ref": "#/components/headers/Disclosure"
              },
              "X-Trellis-Lane": {
                "$ref": "#/components/headers/LaneServed"
              },
              "X-Receipt-Id": {
                "$ref": "#/components/headers/ReceiptId"
              },
              "Inference-Id": {
                "$ref": "#/components/headers/InferenceId"
              },
              "X-Generation-Id": {
                "$ref": "#/components/headers/GenerationId"
              },
              "X-Trellis-Policy-Hash": {
                "$ref": "#/components/headers/PolicyHash"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "receipt"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "receipt": {
                      "$ref": "#/components/schemas/Receipt"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/DisclosureUnavailable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "501": {
            "$ref": "#/components/responses/LaneNotAvailable"
          },
          "503": {
            "$ref": "#/components/responses/DisclosureProviderDown"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          },
          "504": {
            "description": "`provider_timeout`: the provider had accepted the request and did not answer within the router's time limit. It may bill the call, so the call is charged what it ordered from that provider (the prompt bound and the output limit that was sent; an embeddings call, which has no output, its input bound) and no other provider is tried. The body carries `error`, `id`, `usage` and the signed `receipt` (finish reason `timeout`, tokens marked estimated).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "id",
                    "usage",
                    "receipt"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "const": 504
                        },
                        "type": {
                          "const": "provider_timeout"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    "id": {
                      "type": "string"
                    },
                    "usage": {
                      "type": "object"
                    },
                    "receipt": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/keys": {
      "post": {
        "tags": [
          "Keys"
        ],
        "operationId": "createKey",
        "summary": "Create a root key or authenticated sub-key",
        "description": "Without Authorization, creates an independent root key with an empty balance. With an authorized management or admin key, creates a virtual sub-key under that account. The response includes the new secret once; store it securely. Root-key creation does not fund the key. Never send a secret in a query string.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KeyCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "New key metadata and one-time key secret.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "key",
                    "deposit"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Key"
                    },
                    "key": {
                      "type": "string",
                      "readOnly": true,
                      "description": "Secret returned only on creation."
                    },
                    "deposit": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      },
      "get": {
        "tags": [
          "Keys"
        ],
        "operationId": "listKeys",
        "summary": "List keys for the authenticated account",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Key metadata for the authenticated account.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Key"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/generations": {
      "get": {
        "tags": [
          "Generations"
        ],
        "operationId": "listGenerations",
        "summary": "List generation summaries",
        "description": "Returns summaries for the authenticated account. The response's next value can be passed as before to request an older page.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Opaque cursor returned in next. Pass it through without parsing; current versions may return a legacy ISO-8601 timestamp.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Generation summaries and the next page cursor, if any.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GenerationSummary"
                      }
                    },
                    "next": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/generation": {
      "get": {
        "tags": [
          "Generations"
        ],
        "operationId": "getGeneration",
        "summary": "Read one generation record",
        "description": "Returns a full record only to the account owner, the authenticated paying wallet, or (for a call paid with a blind token, which has no account) whoever presents that spent token in Authorization: PrivateToken. The id is supplied as a query parameter because that is the implemented route; do not put API keys or other credentials in URLs.",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "WalletAuth": []
          },
          {
            "PrivateToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Generation record and receipt details.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "receipt": {
                          "$ref": "#/components/schemas/Receipt"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/data": {
      "get": {
        "tags": [
          "Data tools"
        ],
        "operationId": "listDataTools",
        "summary": "List the data tools",
        "description": "Free. The paid tools, the price per call, the Stock Token symbols with a feed, the IPX classes, and which payment methods this router accepts. Requires DATA_TOOLS_ENABLED.",
        "responses": {
          "200": {
            "description": "The data tools on this router.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DataToolsIndex"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/data/ipx/{class}": {
      "get": {
        "tags": [
          "Data tools"
        ],
        "operationId": "getDataIpx",
        "summary": "Inference price index (paid)",
        "description": "The inference price index snapshot for a model class, as GET /api/v1/ipx/{class} computes it, sold per call. Requires IPX_ENABLED; a class with no fills in its window is refused with 503 ipx_no_price before any payment.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "class",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Index class id, for example IPX-OPEN-70B (case-insensitive)."
          },
          {
            "$ref": "#/components/parameters/Payment"
          },
          {
            "$ref": "#/components/parameters/TrellisTab"
          },
          {
            "$ref": "#/components/parameters/TrellisTabVoucher"
          }
        ],
        "responses": {
          "200": {
            "description": "The data and what the call was charged. The payment response header carries the settlement of an x402 payment.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "charge"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DataIpx"
                    },
                    "charge": {
                      "$ref": "#/components/schemas/DataToolCharge"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "description": "Refused before any payment and not charged: feed_stale, feed_unreadable, feed_invalid, token_paused, multiplier_unreadable or ipx_no_price. Retry-After is set.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/status": {
      "get": {
        "tags": [
          "Status"
        ],
        "operationId": "getStatus",
        "summary": "Read public router configuration",
        "description": "Returns published runtime configuration, chain public fields, job state and catalog counts, and, where the router runs a Tor onion service, its address as data.onion.address (null otherwise). data.lanes reports each privacy lane (public, attested, unlinkable) with available, models and endpoints (how many can serve it right now) and the attested_bonus its selection weight uses; data.lanes.unlinkable.via lists the transports that carry that lane here: ohttp (an independent Oblivious HTTP relay), onion (Tor, through the onion service), both, or none when it is not available. data.per_call.x402 reports whether x402 is configured, the network names a payment may carry (versions 1 and 2), the headers the router reads and writes, and recovery: whether PAYMENT-RECOVERY is available, the message the payer signs and how long answers are kept (ttl_s). data.identity reports AGENT_IDENTITY_ENABLED (enabled), PAID_FEEDBACK_ENABLED (paid_feedback), the registration mode, the identity registry (none is deployed on Solana yet), the receipt kinds that can back feedback, the half-life and the liveness interval. data.data_tools reports whether the market-data tools are on (enabled, price_usd, tools, symbols, payment) and data.decision_tags whether X-Trellis-Decision-Tag is recorded in receipts. It is not an uptime guarantee. data.chain reports the Solana cluster (CAIP-2 network, the USDC mint, the program ids of trellis_credits, trellis_tab, trellis_bond, trellis_anchor and the vault). data.facilitator reports the hosted x402 facilitator: enabled, url, networks, schemes (exact, tab), fee_bps, fee_waived, fee_waiver_until, min_settle_units, the relay address and balance floor, tab_program and tab_settlement (payee_signed_close_relayed). data.per_call.x402 names the network (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp on mainnet), the headers and recovery.",
        "responses": {
          "200": {
            "description": "Current public status snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "launch_surface": {
                          "type": "object",
                          "description": "The launch surface this router registered (src/surface/). `core`: only the allow-listed routes and background jobs exist.",
                          "required": [
                            "surface",
                            "off"
                          ],
                          "properties": {
                            "surface": {
                              "enum": [
                                "core",
                                "all"
                              ]
                            },
                            "core": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Route groups that are mounted."
                            },
                            "jobs": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "off": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Features that are not enabled because of the surface (empty on `all`)."
                            },
                            "off_groups": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "off_routes": {
                              "type": "integer"
                            },
                            "off_jobs": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "not_enabled": {
                              "type": "object",
                              "properties": {
                                "status": {
                                  "const": 404
                                },
                                "type": {
                                  "const": "not_enabled"
                                }
                              }
                            },
                            "ignored_settings": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "note": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/health": {
      "get": {
        "tags": [
          "Status"
        ],
        "operationId": "getHealth",
        "summary": "Check process response",
        "description": "Returns { ok: true } when this process responds. It does not establish dependency health or uptime.",
        "responses": {
          "200": {
            "description": "Process responded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    }
                  }
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/receipts/verify": {
      "post": {
        "tags": [
          "Receipts"
        ],
        "operationId": "verifyReceipt",
        "summary": "Verify a signed receipt",
        "description": "A v1 receipt (payload, sig, key_id) is checked as before. A v2 receipt is sent as cose (the COSE_Sign1 bytes, base64) and is checked in order: signature, then request_sha256 and response_sha256 when given, then the chunk hash chain when chunks (the data of every streamed event before the receipt, in order) are given, then the anchor path. The result reports each step (signature_valid, hashes_valid, chain_valid, inclusion_valid; null when not run) and valid is false when any step that ran failed. Either form also reports decision_tag, the X-Trellis-Decision-Tag the receipt carries (null when none), and, when the request includes decision_tag (the SHA-256 of your order), decision_tag_valid; a mismatch makes valid false. Decision tags are recorded only while DECISION_TAGS_ENABLED is on. When an anchor with an index is given, onchain_status says what the router found on chain for that anchor of its own: verified (the root is there: a finalized transaction, signed by the router's anchorer key, in time, with no earlier root of that key for the hour, or the anchor program's account), unverified (it is not, or what is there does not verify), not_posted, or unknown (the chain was not consulted: the RPC failed, or this caller's budget of chain lookups for the minute is used up; no further RPC work is done then). onchain_root is set only when onchain_status is verified. valid covers the signature and the Merkle path and does not by itself say the root is on chain. The anchor mode, the program and the anchorer keys used here are the router's own configuration; nothing about them is read from the request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/ReceiptVerificationRequest"
                  },
                  {
                    "$ref": "#/components/schemas/ReceiptV2VerificationRequest"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Receipt verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/receipts/{id}": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "getReceipt",
        "summary": "Read a public receipt proof",
        "description": "Returns the v1 fields unchanged and, when the receipt has one, its v2 encoding in v2 (version is then 2). With format=cose the COSE_Sign1 bytes themselves are returned (application/cose), or as base64 text with encoding=base64; 404 when the receipt has no v2 encoding. The response also carries privacy, the plain-English privacy label computed from the payload (see GET /api/v1/receipts/{id}/privacy); it is added beside the signed fields and is not signed. A make-good refund id (rf_...) returns its signed v1 refund receipt (kind refund, naming original_receipt_id) in the same shape, without v2 or anchor.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "cose"
              ]
            }
          },
          {
            "name": "encoding",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "binary",
                "base64"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Signed receipt and optional anchor proof.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Receipt"
                    }
                  }
                }
              },
              "application/cose; cose-type=\"cose-sign1\"": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "application/cose"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string",
                  "contentEncoding": "base64"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/receipts/{id}/proof": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "getReceiptProof",
        "summary": "Merkle path to the hourly root",
        "description": "Public. Once the receipt's hour has been rooted, the sorted-pair sha256 Merkle path from the receipt's leaf (the v2 leaf when it has one; v=1 selects the v1 leaf, which sits in the same tree) to the root. Before that, rooted is false. anchored is true only when the root was posted to the trellis_anchor program on Solana and confirmed; a router without a configured chain keeps the root off chain (status local) and says anchored false. status is confirmed, pending, local, late or conflict. In memo mode (mode memo: the root is a line signed by the router's anchorer key in an SPL Memo transaction, given as memo) a root is confirmed only once its transaction is finalized; late means it landed after the lateness bound and is not an anchor; conflict means the anchorer key had already signed another root for the hour, so this one was not posted; both say anchored false. An hour without receipts still gets a line (count 0). mode, contract, network, anchorer and memo tell a verifier what to look for on chain; which mode, network, program and anchorer keys to trust it takes from its own configuration (see /.well-known/trellis-receipt-keys.json), never from this answer.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "v",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "2"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The path, or rooted false.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ReceiptProof"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/receipts/{id}/privacy": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "getReceiptPrivacy",
        "summary": "What we saw: the privacy label for one answer",
        "description": "Public by id, like the receipt itself. A plain-English label computed from the receipt's signed fields: who could read the prompt, who saw the caller's network address, how the call was paid, what the router kept and what hardware answered, in five short lines (summary) and as structured fields (label). The router reads every prompt in memory to route it on every lane, and the label says so. A field the receipt does not carry is reported as not recorded, never assumed; on an unlinkable receipt the address is reported hidden only because that lane is served solely to requests that arrive over Tor (or an independent relay). The label does not verify the receipt: check its signature with POST /api/v1/receipts/verify or the client library, which also computes the same label with privacyLabel(receipt). The same object is returned as `privacy` by GET /api/v1/receipts/{id}, beside the signed payload and never inside it.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The label.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PrivacyLabel"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/host-anchors/proof/{leaf}": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "getHostAnchorProof",
        "summary": "Merkle path from an enclave receipt to its host root",
        "description": "Public, where the router runs with HOST_ANCHOR_ENABLED (otherwise the path does not exist). A receipt a provider's sidecar signed with its enclave key, rooted per host: the router collected it from the host's leaf feed, kept it only because its signature verified under the receipt key the host's router-verified attestation binds, and built one Merkle root per host, attestation reference and interval. anchored is true only when that root was posted with ReceiptAnchor.anchorAttested and confirmed (tx, block and anchor_index, the index in ReceiptAnchor.attestedAnchors); a root kept off chain has status local and anchored false. 404 until the leaf has been collected and rooted. With ANCHOR_MODE=memo the root is posted as a memo line signed by the router's anchorer key (mode memo, memo, anchorer, network): status is confirmed only once that transaction is finalized, late when it landed after the lateness bound, conflict when the anchorer key had already signed another root for the host and hour; late and conflict say anchored false. A verifier takes the mode, network, program and anchorer keys from its own configuration, not from this answer.",
        "parameters": [
          {
            "name": "leaf",
            "in": "path",
            "required": true,
            "description": "The receipt's leaf, sha256(sha256(canonical payload || signature)), as 0x and 64 hex characters.",
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The host root that holds the leaf, the path to it, and its anchor status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HostAnchorProof"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/host-anchors/proof": {
      "post": {
        "tags": [
          "Receipts"
        ],
        "operationId": "postHostAnchorProof",
        "summary": "Merkle path for a sidecar receipt, by receipt or leaf",
        "description": "Public, where the router runs with HOST_ANCHOR_ENABLED (otherwise the path does not exist). A receipt a provider's sidecar signed with its enclave key, rooted per host: the router collected it from the host's leaf feed, kept it only because its signature verified under the receipt key the host's router-verified attestation binds, and built one Merkle root per host, attestation reference and interval. anchored is true only when that root was posted with ReceiptAnchor.anchorAttested and confirmed (tx, block and anchor_index, the index in ReceiptAnchor.attestedAnchors); a root kept off chain has status local and anchored false. 404 until the leaf has been collected and rooted. With receipt, the leaf is recomputed from its payload and signature, and a leaf the receipt states must match it. With ANCHOR_MODE=memo the root is posted as a memo line signed by the router's anchorer key (mode memo, memo, anchorer, network): status is confirmed only once that transaction is finalized, late when it landed after the lateness bound, conflict when the anchorer key had already signed another root for the host and hour; late and conflict say anchored false. A verifier takes the mode, network, program and anchorer keys from its own configuration, not from this answer.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "receipt": {
                    "type": "object",
                    "description": "The sidecar's receipt envelope as it was delivered.",
                    "required": [
                      "payload",
                      "sig"
                    ],
                    "properties": {
                      "payload": {
                        "type": "object"
                      },
                      "sig": {
                        "type": "string",
                        "description": "Base64 Ed25519 signature over the canonical JSON of payload."
                      },
                      "key_id": {
                        "type": "string"
                      },
                      "alg": {
                        "type": "string",
                        "enum": [
                          "Ed25519"
                        ]
                      },
                      "leaf": {
                        "type": "string"
                      }
                    }
                  },
                  "leaf": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{64}$"
                  }
                },
                "oneOf": [
                  {
                    "required": [
                      "receipt"
                    ]
                  },
                  {
                    "required": [
                      "leaf"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The host root that holds the leaf, the path to it, and its anchor status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HostAnchorProof"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/.well-known/trellis-receipt-keys.json": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "getReceiptKeys",
        "summary": "The router's receipt signing keys",
        "description": "Every Ed25519 key the router has signed receipts with, current and retired, as a JWKS. A receipt is checked by canonicalizing its payload (keys sorted, no whitespace), verifying the signature with the key whose kid is the receipt's key_id, and confirming the kid is the first 16 hex characters of SHA-256 of the raw key. The same list is served at /api/v1/receipts/keys. Beside keys, anchor says where receipt roots are posted: mode (memo or program), network (the cluster's CAIP-2 id), program (program mode), memo_program, anchorer and anchorers (the anchorer keys, oldest first, each with from_hour and the rotation_tx in which the key before it and the new key signed the hand-over), memo_v2_from_hour (memo mode: root lines of this hour and later are trellis:root:v2 lines, which name the transaction of the previous root; earlier hours have v1 lines) and max_late_seconds (memo mode: how long after its hour closed a root may land and still count). The document is not signed. A verifier uses it only as its own configuration, fetched by itself from the router's origin, and pins the first anchorer key to rely on more than that; the copy of anchor inside a proof pack, and the mode, contract, network and anchorer a proof names, are the router's statement and are never a verifier's settings.",
        "responses": {
          "200": {
            "description": "The key set.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReceiptKeys"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/attestation/{providerId}": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "getProviderAttestation",
        "summary": "What the router has verified about a provider's attestation",
        "description": "Public. status is attested only while the router holds a fresh attestation it verified itself, simulated only for development evidence outside production, and unverified otherwise (reason says why). checks lists what was established, each true or false; not_checked lists what this record does not cover. measurement, when present, is the last recorded image, compose and model digests with their transparency-log and on-chain state; attested_now says whether they are what the provider is attested as running now. Nothing here is the provider's own claim repeated back.",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The attestation record.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ProviderAttestation"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/badge/{id}.svg": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "getAttestationBadge",
        "summary": "An attestation badge image for a provider or a model",
        "description": "Public, for an <img> tag or a Markdown image. id is a provider id or a model id (author/slug). The status a prompt is served under right now: attested (a fresh attestation the router verified itself and attested retention), policy, vendor-forwarded, or unverified (unknown id, simulated evidence, or nothing current). While attested it also shows the first eight hex characters of the verified measurement (compose hash, else image digest) and of the classifier policy hash the attestation bound, and the share of the last 7 days with a fresh attestation, truncated. Only site colours, no script and no external reference. An unknown id is still an image, reading Unverified, with status 404. Nothing is checked in the viewer's browser; /badge.js does that.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A provider id, or a model id such as meta-llama/llama-3.3-70b-instruct.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "theme",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "light",
                "dark"
              ],
              "default": "light"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The badge.",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/attestation/summary": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "getAttestationSummary",
        "summary": "Proof-time: how long each attesting provider has held a fresh attestation",
        "description": "Public. For every live or shadow provider that has a TEE and an attestation endpoint: the current status (by the same rule as GET /api/v1/attestation/{providerId}), and the share of the last 24 hours and 7 days in which the router held a fresh attestation it verified itself. A fresh attestation is one the router verified at most fresh_within_ms ago (three attestor intervals) with no failed run since; a failed run, or evidence accepted only as simulated, ends the cover at once. share is the covered part of the time the record spans (observed_ms); when the record does not reach back to the start of the window (history_complete false) the earlier time is unknown and counts neither way, and share is null when nothing is recorded. buckets divides the window into equal slices, each the percent covered, or null before the record begins. Also: measurement changes in the last 7 days, the last measurement change (which fields, from and to), the last failed check as a code with a fixed message (never the provider's own text), the pass rate of the last 7 days' checks, and the latest health-probe and canary outcomes. Nothing here is raw provider output. Returns 501 not_enabled when the router keeps no history (ATTESTATION_HISTORY_DAYS is 0).",
        "responses": {
          "200": {
            "description": "The summary.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AttestationSummary"
                    }
                  }
                }
              }
            }
          },
          "501": {
            "description": "not_enabled: this router keeps no attestation history.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/attestation/{providerId}/history": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "getAttestationHistory",
        "summary": "A provider's recorded attestation, canary and probe events",
        "description": "Public. Newest first. Each event is one attestor run (kind attestation: ok or a failure code, the report hash, the TLS pin's SPKI hash when pinned, the verifiers that accepted the quote, the digests the run reported and whether they differ from the previous run's), one canary run (kind canary), or a change of the health probe's outcome (kind probe; only changes are recorded). Events are kept for history_days. Page with before set to the previous page's next: it encodes the moment and id of the last event, so events at the same instant are neither skipped nor repeated. Returns 404 for an unknown provider and 501 not_enabled when the router keeps no history.",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "The next value of the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "attestation",
                "canary",
                "probe"
              ]
            }
          },
          {
            "name": "ok",
            "in": "query",
            "required": false,
            "description": "Only events that passed (true) or failed (false).",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of events.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttestationHistory"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "description": "not_enabled: this router keeps no attestation history.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/measurements/key": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "getMeasurementKey",
        "summary": "The key measurement bundles must be signed with",
        "description": "Public; 404 until the router is configured with a measurement key. A measurement bundle names the compose hash, source commit and tarball hash, model digest and image digests of a provider's attested software, with an MRTD and RTMR3 allow-list. It counts only if it is signed with this ECDSA P-256 key (SHA-256, DER signature over the bundle's canonical JSON) and the entry recording it in the transparency log verifies. key_id is the SHA-256 of the SubjectPublicKeyInfo.",
        "responses": {
          "200": {
            "description": "The key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "algorithm",
                        "key_id",
                        "public_key_pem"
                      ],
                      "properties": {
                        "algorithm": {
                          "const": "ecdsa-p256-sha256"
                        },
                        "key_id": {
                          "type": "string"
                        },
                        "public_key_pem": {
                          "type": "string"
                        },
                        "public_key_spki_base64": {
                          "type": "string"
                        },
                        "transparency_log": {
                          "type": "string",
                          "format": "uri"
                        },
                        "note": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/measurements/bundles/{providerId}": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "getMeasurementBundles",
        "summary": "A provider's signed measurement bundles and their transparency-log entries",
        "description": "Public; 404 until the router is configured with a measurement key. Newest first. Each item carries the bundle, its signature and digest, the status the router reached (pending, verified or rejected, with the reason), the log entry it verified (uuid, index, integration time, whether the inclusion proof, checkpoint signature and signed entry timestamp verified) and, once verified, the log's own copy of the entry (entry_record: body, inclusion proof, signed entry timestamp) so a verifier can check it without asking the log.",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The bundles.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "required": [
                          "status",
                          "bundle_digest",
                          "bundle",
                          "signature",
                          "transparency_log"
                        ],
                        "properties": {
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "verified",
                              "rejected"
                            ]
                          },
                          "bundle_digest": {
                            "type": "string"
                          },
                          "compose_hash": {
                            "type": "string"
                          },
                          "signature": {
                            "type": "string"
                          },
                          "bundle": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "transparency_log": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/mcp": {
      "post": {
        "tags": [
          "MCP"
        ],
        "operationId": "mcp",
        "summary": "Trellis MCP (Streamable HTTP, stateless JSON-RPC 2.0)",
        "description": "One JSON-RPC 2.0 message per request: initialize, ping, tools/list and tools/call (list_models, list_attested_models, chat, verify_provider, get_receipt, verify_receipt), plus notifications, which get an empty 202. Replies are JSON, never a stream; there are no sessions. Only the chat tool needs an API key, which it spends like /api/v1/chat/completions. chat takes lane (public or attested) and disclosure (none, policy or any), meaning provider.lane and provider.disclosure: on the attested lane a prompt goes only to a provider with a fresh attestation the router verified and attested retention, and when none can answer the tool returns an error (no_attested_endpoint or disclosure_unavailable; nothing sent, nothing charged). Its result reports lane, the disclosure class the receipt records and, for an attested gateway, upstream_attestation (attested, gpu_attested, receipt_verified). list_attested_models lists the models the attested lane can serve now, with gpu_attested (true, false, or null before any verified gateway receipt). verify_provider takes provider_id and returns the router's attestation record for it in plain terms: status, TEE, verifiers, TLS pin, transparency-log status and not_checked; it is the same record as GET /api/v1/attestation/{providerId}. A connection can be made attested by default with the lane query parameter or the X-Trellis-Lane header on the /mcp URL (disclosure and X-Trellis-Disclosure-Max set a ceiling): the strictest setting wins, a call cannot relax it, and an unrecognised value refuses the chat call. Malformed JSON or a batch gets HTTP 400, a request carrying a foreign Origin header gets 403 and GET gets 405; all three carry a JSON-RPC error body.",
        "parameters": [
          {
            "name": "lane",
            "in": "query",
            "required": false,
            "description": "Connection default for the chat tool: public (default) or attested. attested sends every chat prompt only to attested providers and refuses the call when none can answer. Repeat or combine with the header: the strictest applies. unlinkable is not available over MCP.",
            "schema": {
              "type": "string",
              "enum": [
                "public",
                "attested"
              ],
              "default": "public"
            }
          },
          {
            "name": "disclosure",
            "in": "query",
            "required": false,
            "description": "Connection default disclosure ceiling for the chat tool: none, policy or any (default). The strictest of this, the header and the call's own setting applies.",
            "schema": {
              "type": "string",
              "enum": [
                "none",
                "policy",
                "any"
              ],
              "default": "any"
            }
          },
          {
            "name": "X-Trellis-Lane",
            "in": "header",
            "required": false,
            "description": "Same as the lane query parameter.",
            "schema": {
              "type": "string",
              "enum": [
                "public",
                "attested"
              ],
              "default": "public"
            }
          },
          {
            "name": "X-Trellis-Disclosure-Max",
            "in": "header",
            "required": false,
            "description": "Same as the disclosure query parameter.",
            "schema": {
              "type": "string",
              "enum": [
                "none",
                "policy",
                "any"
              ],
              "default": "any"
            }
          }
        ],
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "const": "2.0"
                  },
                  "id": {
                    "type": [
                      "string",
                      "integer"
                    ]
                  },
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A JSON-RPC 2.0 response: a result, or an error object with a JSON-RPC code.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "jsonrpc",
                    "id"
                  ],
                  "properties": {
                    "jsonrpc": {
                      "const": "2.0"
                    },
                    "id": {
                      "type": [
                        "string",
                        "integer",
                        "null"
                      ]
                    },
                    "result": {
                      "type": "object"
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Notification accepted; the body is empty."
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/routes": {
      "get": {
        "tags": [
          "Saved Routes"
        ],
        "operationId": "listRoutes",
        "summary": "List the account's saved routes",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Saved routes, sorted by slug.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SavedRoute"
                      }
                    },
                    "limit": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      },
      "post": {
        "tags": [
          "Saved Routes"
        ],
        "operationId": "createRoute",
        "summary": "Save a routing policy callable as model @route/<slug>",
        "description": "Owner or admin. No prompt text is stored.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SavedRouteInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SavedRoute"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "route_exists, route_limit_reached (100 per account), or route_lane_unavailable: the route pins the attested lane or a disclosure ceiling and a model in its list has no provider that meets it right now (metadata.unavailable_models names them; nothing is saved).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/routes/{slug}": {
      "get": {
        "tags": [
          "Saved Routes"
        ],
        "operationId": "getRoute",
        "summary": "Get a saved route",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The route.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SavedRoute"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      },
      "patch": {
        "tags": [
          "Saved Routes"
        ],
        "operationId": "updateRoute",
        "summary": "Update or rename a saved route",
        "description": "Each config section sent replaces that section; null clears it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SavedRouteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SavedRoute"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "route_exists, or route_lane_unavailable (see createRoute).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      },
      "delete": {
        "tags": [
          "Saved Routes"
        ],
        "operationId": "deleteRoute",
        "summary": "Delete a saved route",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/presets": {
      "get": {
        "tags": [
          "Presets"
        ],
        "operationId": "listPresets",
        "summary": "List the account's presets at their latest version",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Presets, sorted by name.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Preset"
                      }
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "limits": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/presets/{name}": {
      "get": {
        "tags": [
          "Presets"
        ],
        "operationId": "getPreset",
        "summary": "Get a preset (the latest version, or ?version=)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,47}$"
            }
          },
          {
            "name": "version",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "A version number (3 or v3) or a hash prefix of at least 7 hex characters."
          }
        ],
        "responses": {
          "200": {
            "description": "The preset version.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Preset"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      },
      "put": {
        "tags": [
          "Presets"
        ],
        "operationId": "putPreset",
        "summary": "Create a preset or save a new version",
        "description": "Owner or admin. The body is the whole document. A change appends an immutable version; an unchanged document adds nothing (changed: false). Models, the lane and the size caps are checked as for a saved route.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PresetDocument"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A new version, or the unchanged latest one.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Preset"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Created as version 1.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Preset"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "preset_limit_reached (100 per account), preset_version_limit (100 versions per preset), or route_lane_unavailable (a model has no provider that meets the preset's lane or disclosure ceiling right now).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,47}$"
            }
          }
        ],
        "x-launch-surface": "all"
      },
      "delete": {
        "tags": [
          "Presets"
        ],
        "operationId": "deletePreset",
        "summary": "Delete a preset and every version of it",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "model": {
                          "type": "string"
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "versions": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,47}$"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/presets/{name}/versions": {
      "get": {
        "tags": [
          "Presets"
        ],
        "operationId": "listPresetVersions",
        "summary": "List a preset's versions, newest first",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Versions.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PresetVersion"
                      }
                    },
                    "latest": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,47}$"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/presets/{name}/diff": {
      "get": {
        "tags": [
          "Presets"
        ],
        "operationId": "diffPresetVersions",
        "summary": "JSON diff between two versions of a preset",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,47}$"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Defaults to the version before `to`."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Defaults to the latest version."
          }
        ],
        "responses": {
          "200": {
            "description": "The changes from `from` to `to`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PresetDiff"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/presets/{name}/rollback": {
      "post": {
        "tags": [
          "Presets"
        ],
        "operationId": "rollbackPreset",
        "summary": "Restore an earlier version as a new version",
        "description": "Owner or admin. Appends a version with the content (and hash) of the one named; nothing is rewritten or deleted.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "version"
                ],
                "properties": {
                  "version": {
                    "oneOf": [
                      {
                        "type": "integer",
                        "minimum": 1
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "A version number or a hash prefix."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The new latest version (changed: false when it was already current).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Preset"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "preset_version_limit, preset_invalid, or route_lane_unavailable: the version's models can no longer be served under its lane.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,47}$"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/sessions": {
      "get": {
        "tags": [
          "Agent Sessions"
        ],
        "operationId": "listSessions",
        "summary": "List the account's agent sessions",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "maximum": 200
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Opaque cursor returned in next. Pass it through without parsing; a plain ISO-8601 timestamp is also accepted.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sessions, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AgentSession"
                      }
                    },
                    "next": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-launch-surface": "all"
      },
      "post": {
        "tags": [
          "Agent Sessions"
        ],
        "operationId": "createSession",
        "summary": "Create a short-lived, budget-capped session key for an agent run",
        "description": "Owner or admin. The secret is returned once. A session cannot exceed its creator's budget, expiry or model allowlist.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentSessionCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created; includes the one-time key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/AgentSession"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "key": {
                              "type": "string",
                              "readOnly": true
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/sessions/current": {
      "get": {
        "tags": [
          "Agent Sessions"
        ],
        "operationId": "currentSession",
        "summary": "A session key's own remaining budget and time",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "This session.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentSession"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/sessions/{id}": {
      "get": {
        "tags": [
          "Agent Sessions"
        ],
        "operationId": "getSession",
        "summary": "Session detail with recent call metadata (never content)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The session.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentSession"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      },
      "delete": {
        "tags": [
          "Agent Sessions"
        ],
        "operationId": "endSession",
        "summary": "End a session now (idempotent)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Ended.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentSession"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/spend": {
      "get": {
        "tags": [
          "Spend Watch"
        ],
        "operationId": "getSpend",
        "summary": "Spend totals, projection, anomaly flag, series, breakdowns and key budgets",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "7d",
                "30d",
                "90d"
              ],
              "default": "30d"
            }
          },
          {
            "name": "group_by",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "model",
                "key",
                "provider"
              ],
              "default": "day"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Spend report.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SpendReport"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/spend/alerts": {
      "get": {
        "tags": [
          "Spend Watch"
        ],
        "operationId": "listSpendAlerts",
        "summary": "List alert rules and recent firings",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Rules.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SpendAlert"
                      }
                    },
                    "limits": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      },
      "post": {
        "tags": [
          "Spend Watch"
        ],
        "operationId": "createSpendAlert",
        "summary": "Create an alert rule (threshold, budget_pct or anomaly)",
        "description": "Owner or admin. Webhooks must be HTTPS to a public address and are delivered at most 3 times per firing.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpendAlertInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SpendAlert"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "too_many_rules (20 per account).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/disclosure/{providerId}": {
      "get": {
        "tags": [
          "Disclosure"
        ],
        "operationId": "getDisclosure",
        "summary": "A provider's disclosure profile and the class it is served under right now",
        "description": "Public. Every value is what the operator documented, with its own source and date; nothing is inferred from traffic. A provider with no recorded profile returns the conservative defaults (retention logs, jurisdiction unknown, legal hold undeclared, training use unknown, declared false). current.class is attested only when retention is declared attested and the provider's TEE attestation is fresh now; current.simulated is true when that attestation is a development report (never accepted in production).",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DisclosureProfile"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      },
      "put": {
        "tags": [
          "Disclosure"
        ],
        "operationId": "putDisclosure",
        "summary": "Replace a provider's disclosure profile (operator only)",
        "description": "Requires the operator token in X-Admin-Token or as a bearer token; an API key is not accepted. The profile is replaced as a whole: a claim that is left out reverts to its conservative default. A retention other than logs needs a legal_hold claim, and retention attested needs a provider with a TEE and attestation endpoint.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DisclosureInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The stored profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DisclosureProfile"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "provider_not_attestable: retention attested was claimed for a provider with no TEE or attestation endpoint (or a development TEE in production).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/models/{author}/{slug}/lane": {
      "put": {
        "tags": [
          "Lane"
        ],
        "operationId": "putModelLane",
        "summary": "Declare a model's variant, license and weights provenance (operator only)",
        "description": "Requires the operator token in X-Admin-Token or as a bearer token; an API key is not accepted. The record is replaced as a whole. The model need not be listed by any provider yet: classify it first. native_low_refusal and abliterated are restricted variants and need license and base_model on record. status candidate routes the model to no provider until the record is written again as servable.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModelLaneInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "description": "The stored record."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/lane/candidates": {
      "get": {
        "tags": [
          "Lane"
        ],
        "operationId": "listLaneCandidates",
        "summary": "Day-zero candidates and their latest scores (operator only)",
        "description": "Requires the operator token. When enabled, the router watches Hugging Face for new fine-tunes of the base models it is configured with, keeps those whose model card carries an allowed license (MIT or Apache-2.0 by default) and records why it rejected the rest. Status: discovered, rejected, evaluated, failed, approved or servable.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "discovered",
                "rejected",
                "evaluated",
                "failed",
                "approved",
                "servable"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LaneCandidate"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/lane/candidates/{id}": {
      "get": {
        "tags": [
          "Lane"
        ],
        "operationId": "getLaneCandidate",
        "summary": "One day-zero candidate (operator only)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LaneCandidate"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/lane/candidates/{id}/endpoint": {
      "put": {
        "tags": [
          "Lane"
        ],
        "operationId": "linkLaneCandidateEndpoint",
        "summary": "Say which provider offer serves a candidate's weights (operator only)",
        "description": "The offer's model must declare the candidate's Hugging Face repository as its hugging_face_id, so an evaluation of one set of weights cannot approve a different model. From the moment a repository is a candidate, a model that declares it is routed to no provider until the candidate is servable.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "provider",
                  "model"
                ],
                "properties": {
                  "provider": {
                    "type": "string"
                  },
                  "model": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LaneCandidate"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "repo_mismatch: the offer's model does not declare the candidate's repository. candidate_rejected: the candidate was rejected. invalid_state: the candidate is already approved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/lane/candidates/{id}/evaluate": {
      "post": {
        "tags": [
          "Lane"
        ],
        "operationId": "evaluateLaneCandidate",
        "summary": "Run the probe sets against a candidate's endpoint (operator only)",
        "description": "Sends the endpoint 16 benign prompts that base models commonly over-refuse (fiction, security education, medical and legal information; none harmful or illegal), 12 capability prompts with exact checks (arithmetic, JSON format, instruction following) and the router's canary set. The scores are stored. The candidate passes when its refusal rate is at most DAYZERO_MAX_REFUSAL_RATE, its capability score at least DAYZERO_MIN_CAPABILITY, its canary accuracy at least DAYZERO_MIN_CANARY and the canary precision check does not contradict the declared quantization. An approved or servable candidate that fails loses its approval and stops being served.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LaneCandidate"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "no_endpoint: link an endpoint first. endpoint_unavailable: the linked offer or provider is not live. candidate_rejected: the candidate was rejected.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/lane/candidates/{id}/approve": {
      "post": {
        "tags": [
          "Lane"
        ],
        "operationId": "approveLaneCandidate",
        "summary": "Approve an evaluated candidate (operator only)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "approved_by": {
                    "type": "string",
                    "maxLength": 64
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "variant": {
                    "type": "string",
                    "enum": [
                      "abliterated",
                      "native_low_refusal"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LaneCandidate"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "invalid_state: only an evaluated candidate can be approved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/lane/candidates/{id}/promote": {
      "post": {
        "tags": [
          "Lane"
        ],
        "operationId": "promoteLaneCandidate",
        "summary": "Make an approved candidate servable (operator only)",
        "description": "Succeeds only if the linked provider is served under attested retention with a fresh attestation and its attestation reports the in-enclave classifier as enabled: the same test routing applies to a request. Otherwise 409 not_servable says why and nothing changes. The router repeats this for approved candidates on every day-zero run.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LaneCandidate"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "invalid_state: only an approved candidate can be promoted. not_servable: no attested provider that reports the classifier serves it now; error.metadata.candidate is the candidate.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/creators/claims": {
      "post": {
        "tags": [
          "Creator royalties"
        ],
        "operationId": "createCreatorClaim",
        "summary": "Get a challenge to claim a model's creator royalty",
        "description": "Public and rate limited. The model must have a Hugging Face weights source on record. Commit file_content to the file named in file, on the main branch of hugging_face_id, then call the verify endpoint before expires_at. The address is the one that will receive the royalty.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "model",
                  "address"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "address": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$"
                  },
                  "hf_handle": {
                    "type": "string",
                    "description": "Optional: refused if it is not the owner of the weights source."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreatorClaim"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "not_claimable: the model has no Hugging Face weights source on record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/creators/claims/{id}": {
      "get": {
        "tags": [
          "Creator royalties"
        ],
        "operationId": "getCreatorClaim",
        "summary": "Read a creator claim",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreatorClaim"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/creators/claims/{id}/verify": {
      "post": {
        "tags": [
          "Creator royalties"
        ],
        "operationId": "verifyCreatorClaim",
        "summary": "Check the published challenge and record the royalty recipient",
        "description": "Public and rate limited. The router reads the repository's owner and the claim file through the Hugging Face API. The owner must still be the handle the challenge was issued to and the file must contain the challenge on its own line. On success the address becomes the model's royalty recipient at the router's default rate (5 percent unless configured otherwise, at most 20 percent): it is registered in the royalty contract first when one is configured, then recorded, and every later call to the model includes the royalty in its price. Verifying a verified claim returns it again.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreatorClaim"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "claim_stale: the model's weights source changed since the challenge was issued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "claim_expired: the challenge is no longer valid; start a new claim.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "502": {
            "description": "chain_failed: the royalty contract registration failed and nothing was recorded; verify again. hf_unavailable: Hugging Face could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/blind/keys": {
      "get": {
        "tags": [
          "Blind tokens"
        ],
        "operationId": "getBlindKeys",
        "summary": "Issuer keys, the token challenge and token prices",
        "description": "Public; 404 unless the router enables blind tokens. One 2048-bit RSA issuer key per denomination (1000, 10000 and 100000 token-units) per epoch (a week), published before the epoch starts. token_key_id is the SHA-256 of the key's RFC 9578 SubjectPublicKeyInfo (token_key, base64url), so a client can check the key against its id. A key issues only while its status is issuing; its tokens stay redeemable until redeem_until. Every token must carry challenge_digest, the SHA-256 of the published challenge. commitments are the per-epoch values a BlindIssuer contract records. Nothing in this response is signed: compare commitments with a value recorded independently (for example on chain) before trusting the keys.",
        "responses": {
          "200": {
            "description": "Keys, challenge and prices.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/BlindKeys"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/blind/purchase": {
      "post": {
        "tags": [
          "Blind tokens"
        ],
        "operationId": "purchaseBlindTokens",
        "summary": "Buy blind tokens with credits",
        "description": "Debits the key's credits through the ledger and returns one blind signature per blinded message, in order. The client blinds the token inputs (RFC 9474) with the key named by token_key_id, and unblinds the signatures locally; the router stores counts only, never the blinded messages, the signatures or the tokens. Sending the same request again after a lost response returns the same signatures without charging again (replayed: true). Purchases count against the key's budget and are rate limited per key, capped per request (max_batch) and per account per day. A key restricted to some models cannot buy tokens. 404 unless the router enables blind tokens.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BlindPurchaseRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The blind signatures.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/BlindPurchase"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The key's epoch is not open yet (epoch_not_open), has ended (epoch_closed) or was revoked (token_key_revoked), or the same purchase is still being processed (purchase_in_progress).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/ohttp/keys": {
      "get": {
        "tags": [
          "Oblivious HTTP"
        ],
        "operationId": "getOhttpKeys",
        "summary": "Gateway key configuration (RFC 9458 section 3)",
        "description": "Public; 404 unless the router enables Oblivious HTTP. One key configuration in application/ohttp-keys form: key identifier, KEM (DHKEM X25519 HKDF-SHA256), public key, and the KDF and AEAD pairs offered (HKDF-SHA256 with AES-128-GCM). The key changes every epoch (a day by default) and keeps opening requests for a grace period after that. This response is not signed: check it against the signed key list (GET /api/v1/ohttp/key-list) before use. Also served at /.well-known/ohttp-gateway.",
        "responses": {
          "200": {
            "description": "The key configuration.",
            "content": {
              "application/ohttp-keys": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "description": "The gateway has no usable key right now (ohttp_no_key). Retry after Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/ohttp/gateway": {
      "post": {
        "tags": [
          "Oblivious HTTP"
        ],
        "operationId": "ohttpGateway",
        "summary": "Oblivious HTTP gateway: unwrap an encapsulated request, serve it, wrap the response",
        "description": "Sent by a relay (or, without the privacy benefit, directly). The body is a message/ohttp-req: a binary HTTP request (RFC 9292) sealed to the gateway key. The gateway serves it on the router's own routes and answers 200 with a message/ohttp-res that carries the whole inner response, errors included, so an inner 4xx is inside the encapsulation. Reachable routes: POST chat/completions and completions (streaming only with chunked Oblivious HTTP), POST embeddings, POST blind/purchase, GET blind/keys, GET models; anything else is an inner 404 route_not_allowed. Of the request's headers only Authorization, Content-Type, Accept, X-Trellis-Lane and X-Trellis-Disclosure-Max are passed on. Responses are zero-padded to a multiple of 256 bytes. A relay identifies itself with Authorization: Bearer <key_id>:<secret>; a request without it is treated as direct and is not served the unlinkable lane. Errors before the request could be unwrapped are plain HTTP: 415, 413, 400, 422 (unknown key identifier or a request that does not decrypt, application/problem+json), 401 (a relay credential that is not recognised) and 429. Where the router enables chunked Oblivious HTTP (draft-ietf-ohai-chunked-ohttp; GET /api/v1/relays then lists gateway.chunked), the body may instead be a message/ohttp-chunked-req, answered with a message/ohttp-chunked-res (with Incremental: ?1) that is encrypted and sent chunk by chunk as the inner response is produced, so stream true works; the last chunk is sealed as the final one, so a response that ends without it was cut off and is incomplete. A chunked response that grows past the size limit ends without its final chunk. Do not retry a failed encapsulated request automatically; a repeated ciphertext is answered with an inner 409 replayed_request.",
        "requestBody": {
          "required": true,
          "content": {
            "message/ohttp-req": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "message/ohttp-chunked-req": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The encapsulated response: message/ohttp-res for a message/ohttp-req, message/ohttp-chunked-res for a message/ohttp-chunked-req.",
            "content": {
              "message/ohttp-res": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "message/ohttp-chunked-res": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "413": {
            "description": "The encapsulated request is larger than the gateway accepts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "415": {
            "description": "The content type is not message/ohttp-req (or message/ohttp-chunked-req, where the router enables chunked Oblivious HTTP).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "422": {
            "description": "The key identifier is unknown, expired or revoked, the ciphersuite is not offered, or the request does not decrypt with the key it names. Fetch the key configuration again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "example": "https://iana.org/assignments/http-problem-types#ohttp-key"
                    },
                    "title": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/ohttp/key-list": {
      "get": {
        "tags": [
          "Oblivious HTTP"
        ],
        "operationId": "getOhttpKeyList",
        "summary": "Gateway key history, signed and hash-chained",
        "description": "Public; 404 unless the router enables Oblivious HTTP. Every gateway key with its configuration, acceptance window and status, the next epoch's key listed as upcoming before it is served, and the relay list. The document is signed with the router's receipt signing key (Ed25519 over the canonical JSON of data; keys at GET /api/v1/receipts/keys, also registered on chain), and each key's entry_hash chains to the one before it, so a client can pin log.head and notice a key that was removed or replaced. A key's private half is destroyed when its window ends (private_key_destroyed).",
        "responses": {
          "200": {
            "description": "The signed key list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OhttpKeyList"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/relays": {
      "get": {
        "tags": [
          "Oblivious HTTP"
        ],
        "operationId": "listRelays",
        "summary": "Relays clients may use for the unlinkable lane",
        "description": "Public; 404 unless the router enables Oblivious HTTP. Each relay has its operator, its URL and a key_id (an identifier of the credential the relay presents to the gateway, published so it is on record; the router does not verify it beyond authenticating the relay). independent is false for a relay run by the gateway's own operator: the unlinkable lane is not served through it. Pick a relay whose operator is not the gateway operator.",
        "responses": {
          "200": {
            "description": "The relays.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RelayList"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/spend/alerts/{id}": {
      "patch": {
        "tags": [
          "Spend Watch"
        ],
        "operationId": "updateSpendAlert",
        "summary": "Update an alert rule (kind cannot change; webhook_url null removes it)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpendAlertInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SpendAlert"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      },
      "delete": {
        "tags": [
          "Spend Watch"
        ],
        "operationId": "deleteSpendAlert",
        "summary": "Delete an alert rule",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/v1/messages": {
      "post": {
        "tags": [
          "Anthropic Messages"
        ],
        "operationId": "createAnthropicMessage",
        "summary": "Create a message (Anthropic Messages API)",
        "description": "The Anthropic Messages API, for the Anthropic SDKs and Claude Code (ANTHROPIC_BASE_URL set to the router). Also served at /api/v1/messages. The request is converted to a chat completion and sent through /api/v1/chat/completions inside the router, so the key, balance, limits, lane, signed receipt and response headers are those of a chat call. Authenticate with x-api-key or Authorization: Bearer. The model is a catalog id (GET /v1/models) or a name the operator mapped with ANTHROPIC_MODEL_MAP; an unmapped claude-* name is a 404 that says the router serves open models. Text, image (base64 and URL), tool_use and tool_result blocks, tools and tool_choice, stop_sequences, top_k (dropped for a provider that does not list it) and metadata.user_id (sent to the provider as user) are converted; max_tokens above the model's output limit, or above the room the context leaves after the prompt bound, is lowered to it, and the resulting cap is always sent to the provider. An image needs a model whose catalog entry declares a per-image token limit (input_token_limits.image in GET /api/v1/models): to a model that declares none the request is refused with a 400 (trellis.type unboundable_input) rather than guessed. The hold and the charge follow the chat route: the hold is a bound (prompt bytes plus the output cap) and the charge never exceeds it. Tools hosted by Anthropic, thinking and service_tier are accepted and not acted on (named in X-Trellis-Ignored); PDF documents, mcp_servers and container are refused with a 400. The reply's id is the receipt id, and its trellis object carries the lane, disclosure class, provider, cost, upstream_attestation where there is one, and the signed receipt. With stream true the events are message_start, ping, content_block_start, content_block_delta (text_delta, input_json_delta), content_block_stop, message_delta (billed usage and the trellis object) and message_stop, or an error event in place of the ending; a request the router refuses before any output is an HTTP error instead of a stream. stop_reason is end_turn, max_tokens, tool_use or refusal, and stop_sequence only when the provider names the stop string that ended the answer. Errors have Anthropic's shape with a trellis object carrying the router's own error type.",
        "parameters": [
          {
            "name": "X-Trellis-Lane",
            "in": "header",
            "required": false,
            "description": "public (default) or attested. attested sends the prompt only to a provider with a fresh TEE attestation the router verified and attested retention; when none can serve the model the call is refused with 409 (503 while they are down) and nothing is sent or charged. Same meaning as provider.lane; the stricter of the two applies. An unrecognised value is a 400.",
            "schema": {
              "type": "string",
              "enum": [
                "public",
                "attested"
              ],
              "default": "public"
            }
          },
          {
            "name": "X-Trellis-Disclosure-Max",
            "in": "header",
            "required": false,
            "description": "Strictest ceiling on who may see the prompt: none, policy or any (default). Same meaning as provider.disclosure.",
            "schema": {
              "type": "string",
              "enum": [
                "none",
                "policy",
                "any"
              ],
              "default": "any"
            }
          },
          {
            "name": "anthropic-version",
            "in": "header",
            "required": false,
            "description": "Accepted and ignored.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "anthropic-beta",
            "in": "header",
            "required": false,
            "description": "Accepted and ignored.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "BearerAuth": []
          },
          {
            "AnthropicApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnthropicMessagesRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The message, or Anthropic server-sent events when stream is true.",
            "headers": {
              "X-Trellis-Lane": {
                "$ref": "#/components/headers/LaneServed"
              },
              "X-Receipt-Id": {
                "$ref": "#/components/headers/ReceiptId"
              },
              "Inference-Id": {
                "$ref": "#/components/headers/InferenceId"
              },
              "X-Generation-Id": {
                "$ref": "#/components/headers/GenerationId"
              },
              "X-Trellis-Policy-Hash": {
                "$ref": "#/components/headers/PolicyHash"
              },
              "X-Trellis-Disclosure": {
                "$ref": "#/components/headers/Disclosure"
              },
              "Request-Id": {
                "description": "An id for this request (req_...), also in the error body's request_id.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Trellis-Ignored": {
                "description": "Present when the request asked for something that is accepted and not acted on: thinking, service_tier, or tools hosted by Anthropic (tool:<name>). A comma separated list.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnthropicMessage"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Anthropic SSE: each event has an event: line naming its type and a data: JSON object."
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/AnthropicError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/v1/messages/count_tokens": {
      "post": {
        "tags": [
          "Anthropic Messages"
        ],
        "operationId": "countAnthropicMessageTokens",
        "summary": "Count the tokens of a message (upper bound)",
        "description": "The body of POST /v1/messages without max_tokens. Returns the router's own bound on the prompt, the figure a hold is priced at: the UTF-8 bytes of the text and of the indented JSON of tools and other structured fields (non-ASCII text counts the larger of its bytes and its NFKD-normalised bytes; characters are never divided by a ratio), plus fixed template allowances (64 tokens per request, 16 per message, 256 when tools are present), plus, for each image, the per-item token limit the model's catalog entry declares (input_token_limits.image in GET /api/v1/models). An image sent to a model that declares no such limit is refused with 400 (trellis.type unboundable_input). It is an upper bound, several times a tokenizer's count for English text, not a tokenizer's count; it costs nothing, and it needs a key. The model is read only for its per-item limits; a text-only body is counted the same for any model. Also served at /api/v1/messages/count_tokens.",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "AnthropicApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnthropicCountTokensRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The bound.",
            "headers": {
              "Request-Id": {
                "description": "An id for this request (req_...), also in the error body's request_id.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "input_tokens"
                  ],
                  "properties": {
                    "input_tokens": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/AnthropicError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/responses": {
      "post": {
        "tags": [
          "Responses"
        ],
        "operationId": "createResponse",
        "summary": "Create a response (OpenAI Responses API)",
        "description": "The OpenAI Responses API, for the OpenAI Agents SDK, the Codex CLI and other Responses clients (POST /v1/responses is the same route). It is an adapter over POST /api/v1/chat/completions: the request is translated and sent to that route in-process with the same credentials and headers, so keys, wallet and per-call payment, blind tokens, limits, disclosure ceilings, lanes, signed receipts and error responses are the chat route's own, and the answer is returned in the Responses shape. With stream true the body is the Responses event stream, each frame an event: line and a data: line carrying type and sequence_number: response.created, response.in_progress, response.output_item.added, response.content_part.added, response.output_text.delta, response.output_text.done, response.content_part.done, response.function_call_arguments.delta, response.function_call_arguments.done, response.custom_tool_call_input.delta and .done, response.output_item.done and last response.completed (or response.incomplete when the answer was cut off by max_output_tokens). A failure after the stream has started is an error event followed by response.failed; there is no [DONE]. Stateless by design: nothing is stored, so store must be false (the default; true is refused), and previous_response_id, conversation, background, stored prompts and file or item references are refused with a 400 whose error.param names the field. Send the whole conversation in input on every request, including function_call and function_call_output items for tool round trips. GET, DELETE and cancel under /api/v1/responses/{id} answer 404. Function tools and custom (freeform) tools run. A custom tool, such as Codex's apply_patch, is offered to the model as a function with one string argument, input; its description, a line saying it takes freeform text and its grammar, if it has one, become the function's description, as guidance only: no grammar is enforced. A call to it comes back as a custom_tool_call item with the text as input (streamed as response.custom_tool_call_input.delta, then response.custom_tool_call_input.done), and a custom_tool_call_output input item is its result on the next turn. Hosted tools (web_search, file_search, code_interpreter, computer_use, image_generation, mcp) are refused with a 400 naming the tool, because Trellis hosts none; run the work in your own code and return it as a function_call_output or custom_tool_call_output. Route with provider (lane, disclosure and the router's other preferences) or the X-Trellis-Lane header; the stricter of the two applies, and a request no provider can serve under the lane is refused (409 lane_unavailable) with nothing sent and nothing charged. The response carries X-Receipt-Id, Inference-Id and X-Trellis-Lane (and X-Trellis-Policy-Hash where the serving endpoint attested one), and its metadata carries trellis_receipt_id, trellis_lane and, once known, trellis_disclosure. Other Responses options (include, truncation, service_tier, prompt_cache_key, safety_identifier, stream_options) are accepted and ignored.",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "WalletAuth": []
          },
          {
            "PrivateToken": []
          },
          {}
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Referer"
          },
          {
            "$ref": "#/components/parameters/Title"
          },
          {
            "$ref": "#/components/parameters/Payment"
          },
          {
            "$ref": "#/components/parameters/PaymentSignature"
          },
          {
            "$ref": "#/components/parameters/PaymentRecovery"
          },
          {
            "$ref": "#/components/parameters/TrellisTab"
          },
          {
            "$ref": "#/components/parameters/TrellisTabVoucher"
          },
          {
            "$ref": "#/components/parameters/PayWith"
          },
          {
            "$ref": "#/components/parameters/DisclosureMax"
          },
          {
            "$ref": "#/components/parameters/Lane"
          },
          {
            "$ref": "#/components/parameters/LaneDowngrade"
          },
          {
            "$ref": "#/components/parameters/DecisionTag"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResponsesRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A Response object, or the Responses event stream when stream is true.",
            "headers": {
              "X-Trellis-Disclosure": {
                "$ref": "#/components/headers/Disclosure"
              },
              "X-Trellis-Lane": {
                "$ref": "#/components/headers/LaneServed"
              },
              "X-Receipt-Id": {
                "$ref": "#/components/headers/ReceiptId"
              },
              "Inference-Id": {
                "$ref": "#/components/headers/InferenceId"
              },
              "X-Generation-Id": {
                "$ref": "#/components/headers/GenerationId"
              },
              "X-Trellis-Policy-Hash": {
                "$ref": "#/components/headers/PolicyHash"
              },
              "X-PAYMENT-RESPONSE": {
                "description": "Present when an x402 payment was settled for this call: base64 JSON {success, transaction, network, payer}.",
                "schema": {
                  "type": "string"
                }
              },
              "PAYMENT-RESPONSE": {
                "description": "x402 v2: the same settlement as X-PAYMENT-RESPONSE, with the same value.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResponsesObject"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE frames (event: and data: lines) in the order described above; the response.completed, response.incomplete and response.failed frames carry the whole Response object."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/DisclosureUnavailable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "501": {
            "$ref": "#/components/responses/LaneNotAvailable"
          },
          "503": {
            "$ref": "#/components/responses/DisclosureProviderDown"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/responses/{id}": {
      "get": {
        "tags": [
          "Responses"
        ],
        "operationId": "getResponse",
        "summary": "Not available: responses are not stored",
        "description": "Always 404 (responses_not_stored), like DELETE and POST .../cancel and GET .../input_items on this path. Trellis is stateless: it stores no responses, conversations or input items, so there is nothing to retrieve. A response is returned by the call that creates it. The call's signed receipt, which holds no prompt or answer, is at GET /api/v1/receipts/{id}: the id is in the X-Receipt-Id header and the response's metadata.trellis_receipt_id.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/rag": {
      "post": {
        "tags": [
          "Private RAG"
        ],
        "operationId": "createRagAnswer",
        "summary": "Answer a question from documents you send, keeping nothing",
        "description": "Retrieval-augmented answers over documents sent with the question, with nothing kept. The router cuts the documents into overlapping chunks, embeds the chunks and the question through POST /api/v1/embeddings (in batches), ranks the chunks by cosine similarity in memory, and answers from the best top_k through POST /api/v1/chat/completions, citing numbered sources. Every call is an ordinary call of your key: billed, limited, routed by lane and receipted, and the response lists every receipt id with its lane, the disclosure class it was served under and, for an attested gateway, its upstream_attestation check. Needs a prepaid API key (Authorization: Bearer); per-call payment and blind tokens are not accepted. Lane: send provider.lane (public or attested) or provider.disclosure (none, policy, any), or the X-Trellis-Lane and X-Trellis-Disclosure-Max headers, and every call is held to exactly that and refused, never downgraded: on the attested lane 503 no_attested_endpoint (error.metadata.reason none_attested, or attested_endpoints_down with Retry-After); with only a disclosure ceiling 409 disclosure_unavailable, or 503 disclosure_provider_unavailable while qualifying providers are down; or 502 upstream_not_attested when an attested gateway's receipt does not show an attested upstream (the reply is withheld and the call is billed). A lane or ceiling pinned on the key (routing.provider) applies to every step, not only the chat call. A model the router resolves itself (a saved route, an alias of the key, trellis/...) can pin a lane of its own, so a request naming one must state provider.lane (400 lane_required). Send none and the attested lane is used when the chat model and the embedding model both have an attested endpoint; otherwise the public lane is used and lane_note says why. embedding_model defaults to qwen/qwen3-embedding-8b, else the cheapest embedding model, preferring models with an attested endpoint. Unlinkable is not available. An error from a step is that step's own status and error.type, with error.metadata.step (embeddings or chat) and error.metadata.receipts, the calls already made and billed. Caps (configurable): 200 documents, 2 MiB of document text, 2000 chunks and 64 embeddings calls per request, 413 payload_too_large above them. With stream true the embeddings run first (a refusal there, or at the start of the chat call, is an ordinary JSON error); the stream then sends a chat.completion.chunk event with choices [] and rag.object rag.sources (the sources and the embeddings receipts), the chat stream exactly as /api/v1/chat/completions sends it, an event with rag.object rag.summary (all receipts, totals and, if the chat call was refused mid-stream, error), and data: [DONE]. Nothing of the documents, the question or the answer is stored. The documents, their chunks and vectors and the question live in the memory of the one request that carries them and are dropped when it ends; this endpoint writes them to no database, cache or file, does not log them and never uses the response cache. What remains is what any call leaves: each embeddings call and the chat call is a generation of the key, with a signed receipt holding ids, model, provider, lane, token counts, cost, timing and the SHA-256 of the request and of the response, not their text (a hash confirms an exact guess; it does not reveal text). The text does leave the router: the chunks and the question go to the embedding model's provider and the question and the best chunks go to the chat model's provider. What those providers see and keep depends on the lane; on the attested lane only providers with attested retention and a fresh attestation the router verified are used, which shows what code is running, not what it does with the text.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PayWith"
          },
          {
            "$ref": "#/components/parameters/DisclosureMax"
          },
          {
            "$ref": "#/components/parameters/Lane"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RagRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The answer, its sources and the receipt of every call; or, with stream true, Server-Sent Events: a chat.completion.chunk with choices [] and rag.object rag.sources, the chat stream, a chunk with rag.object rag.summary, then data: [DONE]. The headers are those of the chat call, except X-Trellis-Disclosure, which is the weakest class among all the calls (and is left out when a call's class is not known), and X-Trellis-Policy-Hash, which is sent only when every call reported the same one.",
            "headers": {
              "X-Trellis-Disclosure": {
                "$ref": "#/components/headers/Disclosure"
              },
              "X-Trellis-Lane": {
                "$ref": "#/components/headers/LaneServed"
              },
              "X-Receipt-Id": {
                "$ref": "#/components/headers/ReceiptId"
              },
              "Inference-Id": {
                "$ref": "#/components/headers/InferenceId"
              },
              "X-Generation-Id": {
                "$ref": "#/components/headers/GenerationId"
              },
              "X-Trellis-Policy-Hash": {
                "$ref": "#/components/headers/PolicyHash"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RagAnswer"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-Sent Events; each data: line is a JSON object of the chat.completion.chunk shape."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "No provider meets provider.disclosure for a step (disclosure_unavailable), or no embedding model does. Nothing was sent to a provider for that step. error.metadata.step names it and error.metadata.receipts lists the calls already made.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "More documents, bytes of document text, chunks or embeddings calls than the router allows in one request (payload_too_large). error.metadata.limit is the cap. Nothing was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "502": {
            "description": "A step failed after the router accepted the request: upstream_not_attested (an attested gateway's receipt did not show an attested upstream; the reply was withheld and the call is billed), providers_unavailable, or invalid_embedding_response. error.metadata.step and error.metadata.receipts say where it stopped and what was billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/DisclosureProviderDown"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/tlog/checkpoint": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "getTlogCheckpoint",
        "summary": "Newest checkpoint, with the cosignatures collected so far",
        "description": "Public; 404 unless the router enables the transparency log. A C2SP signed note: the checkpoint text (origin, tree size, base64 root hash; no extension lines), a blank line, the log's Ed25519 signature line, then one cosignature/v1 line per configured witness that has cosigned this tree size. Verify the log's line against the log key pinned out of band (GET /api/v1/tlog shows it, but a client must not take it from the log it is checking), and count witness lines against the witness keys you trust. Served with Cache-Control: no-cache.",
        "responses": {
          "200": {
            "description": "The checkpoint note.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "router.example/tlog\n12\nq0qBmQ4H0cMA5Tq3kQ0V8wQv1c5V3bI1n4r7FQ0y2Hc=\n\n— router.example/tlog <base64 key id and signature>\n— witness.example/w1 <base64 key id, timestamp and cosignature>\n"
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/tlog/tile/{level}/{index}": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "getTlogTile",
        "summary": "Merkle tree tile (tlog-tiles, height 8)",
        "description": "Public; 404 unless the router enables the transparency log, and for any tile or width the tree does not have yet. The concatenated 32-byte node hashes of tree level 8 x level, indices 256 x N to 256 x N + W. The index path is the tlog-tiles encoding of N (groups of three digits, all but the last prefixed with x: 1234067 is x001/x234/067) and may end in .p/<W> for a partial tile of width 1 to 255. A tile of a given width never changes, so tiles are served with Cache-Control: public, max-age=31536000, immutable.",
        "parameters": [
          {
            "name": "level",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 63
            }
          },
          {
            "name": "index",
            "in": "path",
            "required": true,
            "description": "The encoded tile index, optionally followed by .p/<width>; it may contain slashes.",
            "schema": {
              "type": "string",
              "example": "x001/234.p/17"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The tile.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/tlog/tile/entries/{index}": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "getTlogEntryBundle",
        "summary": "Entry bundle (tlog-tiles)",
        "description": "Public; 404 unless the router enables the transparency log. The entries at leaf indices 256 x N to 256 x N + W, each as a big-endian 16-bit length followed by the entry: the canonical JSON {v, type: \"trellis.tlog.entry\", kind, sha256, key}, whose leaf hash is SHA-256(0x00 || entry). Same index encoding and caching as the hash tiles.",
        "parameters": [
          {
            "name": "index",
            "in": "path",
            "required": true,
            "description": "The encoded tile index, optionally followed by .p/<width>; it may contain slashes.",
            "schema": {
              "type": "string",
              "example": "000.p/12"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The entry bundle.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tlog": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "getTlogInfo",
        "summary": "The log: origin, verifier key, witnesses, quorum and newest checkpoint",
        "description": "Public; 404 unless the router enables the transparency log. What entry kinds exist and which witnesses the router collects cosignatures from. Pin the log's verifier key and the witness keys from a source other than the log itself. With Rekor anchoring on (TLOG_REKOR_ENABLED), rekor names the anchoring key and the newest anchored checkpoint's Rekor entry; it is null otherwise.",
        "responses": {
          "200": {
            "description": "The log description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TlogInfo"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tlog/witnessed": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "getTlogWitnessedCheckpoint",
        "summary": "Newest checkpoint cosigned by the witness quorum",
        "description": "Public; 404 (not_witnessed) until some checkpoint carries cosignatures from at least TLOG_WITNESS_QUORUM configured witnesses. Same note format as /tlog/checkpoint.",
        "responses": {
          "200": {
            "description": "The checkpoint note.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "router.example/tlog\n12\nq0qBmQ4H0cMA5Tq3kQ0V8wQv1c5V3bI1n4r7FQ0y2Hc=\n\n— router.example/tlog <base64 key id and signature>\n— witness.example/w1 <base64 key id, timestamp and cosignature>\n"
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tlog/checkpoints/{size}": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "getTlogCheckpointBySize",
        "summary": "One checkpoint with its cosignatures",
        "parameters": [
          {
            "name": "size",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "description": "Public; 404 (unknown_checkpoint) when the log never signed a checkpoint of that tree size.",
        "responses": {
          "200": {
            "description": "The checkpoint note.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "router.example/tlog\n12\nq0qBmQ4H0cMA5Tq3kQ0V8wQv1c5V3bI1n4r7FQ0y2Hc=\n\n— router.example/tlog <base64 key id and signature>\n— witness.example/w1 <base64 key id, timestamp and cosignature>\n"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tlog/lookup": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "lookupTlogEntry",
        "summary": "The entry for a key or configuration",
        "description": "Public; 404 (not_logged) when the key is not in the log. sha256 is the digest a client computes from what it holds: the raw Ed25519 receipt key, the encoded Oblivious HTTP key configuration, the blind issuer SubjectPublicKeyInfo (its token_key_id), the canonical measurement bundle, or the canonical JSON of a sidecar's bindings.",
        "parameters": [
          {
            "$ref": "#/components/parameters/TlogKind"
          },
          {
            "$ref": "#/components/parameters/TlogSha256"
          }
        ],
        "responses": {
          "200": {
            "description": "The entry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TlogEntry"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tlog/proof": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "getTlogProof",
        "summary": "An entry with its inclusion proof and, on request, a consistency proof",
        "description": "Public. The entry for (kind, sha256), a checkpoint that includes it (by default the newest one the witness quorum cosigned, else, with Rekor anchoring on, the newest anchored one, else the newest one), the RFC 6962 inclusion proof to that checkpoint's root and, with from, the consistency proof between tree size from and the checkpoint's size. Nothing here is trusted by itself: a client checks the log signature and witness cosignatures (or, with anchoring, the checkpoint's Rekor entry in checkpoint.rekor) on the checkpoint, recomputes the leaf from the entry and verifies both proofs. 404 not_logged, 409 not_yet_included when the requested checkpoint predates the entry.",
        "parameters": [
          {
            "$ref": "#/components/parameters/TlogKind"
          },
          {
            "$ref": "#/components/parameters/TlogSha256"
          },
          {
            "name": "size",
            "in": "query",
            "description": "Prove against the checkpoint of this tree size instead.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "The tree size of the newest checkpoint the client already holds.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The proof bundle.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TlogProof"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The chosen checkpoint does not include the entry yet (not_yet_included).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tlog/consistency": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "getTlogConsistency",
        "summary": "Consistency proof between two tree sizes",
        "description": "Public. The RFC 6962 consistency proof from tree size from to tree size to (to at most the current size). Witnesses use it before cosigning; clients use it to check that a newer checkpoint extends one they saw.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The proof.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TlogConsistency"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tlog/cosignatures": {
      "post": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "postTlogCosignature",
        "summary": "A witness hands in its cosignature on a checkpoint",
        "description": "Public, rate limited per client address (TLOG_COSIGN_RPM). The body is the checkpoint note as the log served it with the witness's cosignature/v1 line added (the C2SP tlog-cosignature format: key id, 8-byte timestamp and Ed25519 signature over \"cosignature/v1\\ntime <t>\\n\" and the checkpoint text). Only lines from witnesses in TLOG_WITNESSES count; each valid one is kept, the newest per witness and tree size. A witness should cosign only after verifying a consistency proof from the last checkpoint it cosigned (scripts/tlog-witness.ts does). 400 invalid_checkpoint or unknown_log, 403 unknown_witness or invalid_cosignature, 404 unknown_checkpoint, 409 checkpoint_mismatch when the text is not what the log signed for that size.",
        "requestBody": {
          "required": true,
          "content": {
            "text/plain": {
              "schema": {
                "type": "string",
                "maxLength": 16384
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The cosignatures that were accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TlogCosignatureResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The note is not the checkpoint the log signed for that size (checkpoint_mismatch).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "The note is larger than 16 KiB (payload_too_large).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tlog/rekor": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "getTlogRekorAnchors",
        "summary": "Rekor anchoring: the anchoring key, the newest anchored checkpoint and a list of anchors",
        "description": "Public; 404 (rekor_not_enabled) unless the router anchors its checkpoints in Rekor (TLOG_REKOR_ENABLED). Each checkpoint the log moves to is recorded, at most once per TLOG_REKOR_MIN_INTERVAL_MS, as a hashedrekord entry in the Sigstore Rekor log at rekor_url: the entry holds the SHA-256 of the checkpoint as the log signed it (the checkpoint text, a blank line and the log's own signature line, without cosignatures) and an ECDSA P-256 signature over it by the anchoring key. The router verifies the entry's inclusion proof (and, with REKOR_PUBLIC_KEY, Rekor's signed checkpoint and signed entry timestamp) before it lists it. anchors lists every verified anchor, newest checkpoint first; page with before=next_before. Anyone can compare the entries the anchoring key has in Rekor with this list: an entry the list does not explain, or two anchored checkpoints of one size with different roots, is a split view.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Only anchors of checkpoints smaller than this tree size.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The anchoring key and the anchors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TlogRekorAnchors"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tlog/rekor/key": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "getTlogRekorKey",
        "summary": "The anchoring key (ECDSA P-256)",
        "description": "Public; 404 (rekor_not_enabled) unless the router anchors its checkpoints in Rekor (TLOG_REKOR_ENABLED). The public key that signs the log's Rekor entries, and its key_id (SHA-256 of the SubjectPublicKeyInfo, hex). Every entry carries this key, so it can be searched for in Rekor. A client that checks anchors pins this key out of band. Served with Cache-Control: public, max-age=300.",
        "responses": {
          "200": {
            "description": "The anchoring key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TlogRekorKey"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tlog/rekor/{size}": {
      "get": {
        "tags": [
          "Transparency log"
        ],
        "operationId": "getTlogRekorAnchorBySize",
        "summary": "The Rekor entry that anchors one checkpoint",
        "description": "Public; 404 (rekor_not_enabled) unless the router anchors its checkpoints in Rekor (TLOG_REKOR_ENABLED). 404 (not_anchored) when no verified Rekor entry anchors a checkpoint of that tree size under the current anchoring key.",
        "parameters": [
          {
            "name": "size",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The anchor.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/TlogRekorAnchor"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/batches": {
      "post": {
        "tags": [
          "Batches"
        ],
        "operationId": "createBatch",
        "summary": "Create a batch of chat or embeddings requests, run in the background",
        "description": "Also at POST /v1/batches. The OpenAI Batch API shape without files: send the lines inline as requests (a list) or input_jsonl (JSON Lines text), one request per line with a unique custom_id (at most 64 characters), method POST, a url of /v1/chat/completions or /v1/embeddings (the /api/v1 forms are accepted too) and the request body. endpoint, when given, must match every line's url. input_file_id is refused with 400: there is no files endpoint, so send requests or input_jsonl. stream true, council mode (model trellis/council) and verify are refused in a batch. A batch with an invalid line is not created: the 400 invalid_request carries error.metadata.errors, a list of { line, code, message } with 1-based line numbers. Every line's prompt bound is checked before the batch is accepted: a line whose input cannot be bounded is listed with code unboundable_input (non-text input to a model that declares no input_token_limits for it, an unknown content-part type, a provider-side tool, web_search_options), and a line that batches too many prompts with code prompt_batch_too_large. Each line is held, capped and charged as a normal call is: an explicit output cap is sent to the provider and the charge never exceeds the line's hold. Needs a prepaid key. The lines run on the router's worker in spare capacity, so a batch can take minutes; lines not run within the 24h completion window expire and are not charged. Each line is billed at the normal price (BATCH_DISCOUNT_BPS is 0 by default; an operator can set a batch reduction only where a margin of at least that size funds it), a failed line is not charged, and every answered line gets its own signed receipt. Lanes, provider preferences, key budgets and key rate limits apply to each line exactly as to a normal call. Limits (operator settings): BATCH_MAX_LINES (1000 lines), BATCH_MAX_BYTES (8 MiB of input) and BATCH_MAX_ACTIVE (2 unfinished batches per key; one more is refused with 429 batch_limit); a batch over the line or byte limit is refused. The request lines and answers are never written to the database: until the results expire they are kept sealed (AES-256-GCM, with a key derived from the router's secret) in Redis, or in the router's memory without Redis, and then deleted. The database keeps only counts, costs, statuses and generation ids.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The batch was accepted; its status is validating until the worker picks it up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      },
      "get": {
        "tags": [
          "Batches"
        ],
        "operationId": "listBatches",
        "summary": "List the key's batches, newest first",
        "description": "Also at GET /v1/batches. Pages with limit and after (the id of the last batch of the previous page).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Batches per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 20
            }
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "A batch id: list the batches after it.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of batches, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/batches/{id}": {
      "get": {
        "tags": [
          "Batches"
        ],
        "operationId": "getBatch",
        "summary": "Read a batch: status, counts and cost",
        "description": "Also at GET /v1/batches/{id}. Poll it until status is completed, failed, expired or cancelled, then read the output and errors files.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The batch id (batch_...).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The batch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/batches/{id}/cancel": {
      "post": {
        "tags": [
          "Batches"
        ],
        "operationId": "cancelBatch",
        "summary": "Cancel a batch",
        "description": "Also at POST /v1/batches/{id}/cancel. The status becomes cancelling, then cancelled: lines already running finish and are billed, lines not started are never run or billed and appear in the errors file.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The batch id (batch_...).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The batch, cancelling or cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/batches/{id}/output": {
      "get": {
        "tags": [
          "Batches"
        ],
        "operationId": "getBatchOutput",
        "summary": "The answered lines of a batch, as JSONL",
        "description": "Also at GET /v1/batches/{id}/output. One line per answered request: { id: batch_req_..., custom_id, response: { status_code: 200, request_id: the generation id, body: the normal chat or embeddings response, usage.cost and receipt included }, error: null }. Kept for BATCH_RESULTS_TTL (24 hours by default) after the batch finishes.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The batch id (batch_...).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The answered lines.",
            "content": {
              "application/jsonl": {
                "schema": {
                  "type": "string",
                  "description": "JSON Lines: one BatchResultLine object per line."
                },
                "x-line-schema": {
                  "$ref": "#/components/schemas/BatchResultLine"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "410": {
            "description": "The results were deleted: they are kept for BATCH_RESULTS_TTL (24 hours by default) after the batch finishes (batch_results_expired).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/batches/{id}/errors": {
      "get": {
        "tags": [
          "Batches"
        ],
        "operationId": "getBatchErrors",
        "summary": "The failed and unrun lines of a batch, as JSONL",
        "description": "Also at GET /v1/batches/{id}/errors. One line per failed or unrun request: { id, custom_id, response: { status_code, request_id, body: { error } } or null for a line that never ran, error: { code, message } }. Failed and unrun lines are not charged. Kept for BATCH_RESULTS_TTL (24 hours by default) after the batch finishes.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The batch id (batch_...).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The failed and unrun lines.",
            "content": {
              "application/jsonl": {
                "schema": {
                  "type": "string",
                  "description": "JSON Lines: one BatchResultLine object per line."
                },
                "x-line-schema": {
                  "$ref": "#/components/schemas/BatchResultLine"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "410": {
            "description": "The results were deleted: they are kept for BATCH_RESULTS_TTL (24 hours by default) after the batch finishes (batch_results_expired).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/ollama/api/version": {
      "get": {
        "tags": [
          "Ollama"
        ],
        "operationId": "ollamaVersion",
        "summary": "The Ollama API version this endpoint speaks",
        "responses": {
          "200": {
            "description": "The version.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "version"
                  ],
                  "properties": {
                    "version": {
                      "type": "string",
                      "examples": [
                        "0.12.6"
                      ]
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/OllamaError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/ollama/api/tags": {
      "get": {
        "tags": [
          "Ollama"
        ],
        "operationId": "ollamaTags",
        "summary": "List models in Ollama's shape",
        "description": "The live catalog, as GET /api/v1/models lists it. Each name is a catalog id with Ollama's :latest tag (a routing suffix such as :free or :private works as a tag too). size is 0 (there are no local weights) and digest is the SHA-256 of the catalog id. X-Trellis-Lane: attested lists only the models that lane can serve now. Public.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Lane"
          }
        ],
        "responses": {
          "200": {
            "description": "The models.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "models"
                  ],
                  "properties": {
                    "models": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OllamaModel"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/OllamaError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/ollama/api/ps": {
      "get": {
        "tags": [
          "Ollama"
        ],
        "operationId": "ollamaPs",
        "summary": "Models held in memory (always none)",
        "description": "Models are served on demand by hosted providers, so the list is always empty.",
        "responses": {
          "200": {
            "description": "An empty list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "models"
                  ],
                  "properties": {
                    "models": {
                      "type": "array",
                      "maxItems": 0,
                      "items": {}
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/OllamaError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/ollama/api/show": {
      "post": {
        "tags": [
          "Ollama"
        ],
        "operationId": "ollamaShow",
        "summary": "Describe a model",
        "description": "details, capabilities (completion, tools, vision, thinking, or embedding) and the context length in model_info. Public. An unknown model is a 404.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string",
                    "description": "Older clients send the name here."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The model.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OllamaShowResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/OllamaError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/ollama/api/chat": {
      "post": {
        "tags": [
          "Ollama"
        ],
        "operationId": "ollamaChat",
        "summary": "Chat (Ollama)",
        "description": "Converted to a chat completion and sent through /api/v1/chat/completions in-process, so the key, its balance and limits, the lane and the signed receipt are those of a chat call. Streams NDJSON unless stream is false: lines with done false, tool calls whole in one line, then a closing line with done true, done_reason, the counts and durations (nanoseconds) and a trellis object with the receipt id. A request the router refuses before any output is an HTTP error; a failure after output has begun is an {\"error\"} line. No messages: the model is loaded as Ollama does (done_reason load), with no call and no charge.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Lane"
          },
          {
            "$ref": "#/components/parameters/DisclosureMax"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OllamaChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The reply, or its NDJSON stream.",
            "headers": {
              "X-Trellis-Lane": {
                "$ref": "#/components/headers/LaneServed"
              },
              "X-Receipt-Id": {
                "$ref": "#/components/headers/ReceiptId"
              },
              "Inference-Id": {
                "$ref": "#/components/headers/InferenceId"
              },
              "X-Generation-Id": {
                "$ref": "#/components/headers/GenerationId"
              },
              "X-Trellis-Policy-Hash": {
                "$ref": "#/components/headers/PolicyHash"
              },
              "X-Trellis-Disclosure": {
                "$ref": "#/components/headers/Disclosure"
              },
              "X-Trellis-Ignored": {
                "description": "Present when the request asked for something that is accepted and not acted on: options that tune a local runtime (options.num_ctx and the like), suffix, template, raw or context. A comma separated list.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OllamaChatResponse"
                }
              },
              "application/x-ndjson": {
                "schema": {
                  "$ref": "#/components/schemas/OllamaChatResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/OllamaError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/ollama/api/generate": {
      "post": {
        "tags": [
          "Ollama"
        ],
        "operationId": "ollamaGenerate",
        "summary": "Generate (Ollama)",
        "description": "system and prompt are sent as a system and a user message through /api/v1/chat/completions, with the same billing, lanes and receipts. The answer is in response. Streams NDJSON unless stream is false. suffix, template, raw and context are accepted and named in X-Trellis-Ignored.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Lane"
          },
          {
            "$ref": "#/components/parameters/DisclosureMax"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OllamaGenerateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The reply, or its NDJSON stream.",
            "headers": {
              "X-Trellis-Lane": {
                "$ref": "#/components/headers/LaneServed"
              },
              "X-Receipt-Id": {
                "$ref": "#/components/headers/ReceiptId"
              },
              "Inference-Id": {
                "$ref": "#/components/headers/InferenceId"
              },
              "X-Generation-Id": {
                "$ref": "#/components/headers/GenerationId"
              },
              "X-Trellis-Policy-Hash": {
                "$ref": "#/components/headers/PolicyHash"
              },
              "X-Trellis-Disclosure": {
                "$ref": "#/components/headers/Disclosure"
              },
              "X-Trellis-Ignored": {
                "description": "Present when the request asked for something that is accepted and not acted on: options that tune a local runtime (options.num_ctx and the like), suffix, template, raw or context. A comma separated list.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OllamaGenerateResponse"
                }
              },
              "application/x-ndjson": {
                "schema": {
                  "$ref": "#/components/schemas/OllamaGenerateResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/OllamaError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/ollama/api/embed": {
      "post": {
        "tags": [
          "Ollama"
        ],
        "operationId": "ollamaEmbed",
        "summary": "Embeddings (Ollama)",
        "description": "Sent through /api/v1/embeddings, with the same billing, lanes and receipts.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Lane"
          },
          {
            "$ref": "#/components/parameters/DisclosureMax"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "input"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "input": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "minItems": 1
                      }
                    ]
                  },
                  "dimensions": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "truncate": {
                    "type": "boolean",
                    "description": "Accepted and ignored."
                  },
                  "keep_alive": {
                    "description": "Accepted and ignored."
                  },
                  "options": {
                    "type": "object",
                    "description": "Accepted and named in X-Trellis-Ignored."
                  },
                  "provider": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The vectors, in the order of input.",
            "headers": {
              "X-Trellis-Lane": {
                "$ref": "#/components/headers/LaneServed"
              },
              "X-Receipt-Id": {
                "$ref": "#/components/headers/ReceiptId"
              },
              "Inference-Id": {
                "$ref": "#/components/headers/InferenceId"
              },
              "X-Generation-Id": {
                "$ref": "#/components/headers/GenerationId"
              },
              "X-Trellis-Policy-Hash": {
                "$ref": "#/components/headers/PolicyHash"
              },
              "X-Trellis-Disclosure": {
                "$ref": "#/components/headers/Disclosure"
              },
              "X-Trellis-Ignored": {
                "description": "Present when the request asked for something that is accepted and not acted on: options that tune a local runtime (options.num_ctx and the like), suffix, template, raw or context. A comma separated list.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "model",
                    "embeddings"
                  ],
                  "properties": {
                    "model": {
                      "type": "string"
                    },
                    "embeddings": {
                      "type": "array",
                      "items": {
                        "type": "array",
                        "items": {
                          "type": "number"
                        }
                      }
                    },
                    "total_duration": {
                      "type": "integer"
                    },
                    "load_duration": {
                      "type": "integer"
                    },
                    "prompt_eval_count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/OllamaError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/ollama/api/embeddings": {
      "post": {
        "tags": [
          "Ollama"
        ],
        "operationId": "ollamaEmbeddingsLegacy",
        "summary": "One embedding (older Ollama endpoint)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Lane"
          },
          {
            "$ref": "#/components/parameters/DisclosureMax"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "prompt"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "prompt": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The vector.",
            "headers": {
              "X-Trellis-Lane": {
                "$ref": "#/components/headers/LaneServed"
              },
              "X-Receipt-Id": {
                "$ref": "#/components/headers/ReceiptId"
              },
              "Inference-Id": {
                "$ref": "#/components/headers/InferenceId"
              },
              "X-Generation-Id": {
                "$ref": "#/components/headers/GenerationId"
              },
              "X-Trellis-Policy-Hash": {
                "$ref": "#/components/headers/PolicyHash"
              },
              "X-Trellis-Disclosure": {
                "$ref": "#/components/headers/Disclosure"
              },
              "X-Trellis-Ignored": {
                "description": "Present when the request asked for something that is accepted and not acted on: options that tune a local runtime (options.num_ctx and the like), suffix, template, raw or context. A comma separated list.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "embedding"
                  ],
                  "properties": {
                    "embedding": {
                      "type": "array",
                      "items": {
                        "type": "number"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/OllamaError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/ollama/api/pull": {
      "post": {
        "tags": [
          "Ollama"
        ],
        "operationId": "ollamaPull",
        "summary": "Pull a model (nothing to download)",
        "description": "A listed model is ready as soon as it is named, so the pull succeeds at once with {\"status\":\"success\"} (one NDJSON line unless stream is false). An unknown model is a 404. create, copy, push, delete and blob uploads are 501s.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "const": "success"
                    }
                  }
                }
              },
              "application/x-ndjson": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "const": "success"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/OllamaError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/keys/{hash}": {
      "get": {
        "tags": [
          "Keys"
        ],
        "operationId": "getKey",
        "summary": "Get one key, with its tracing export status",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The key's hash (Key.hash)."
          }
        ],
        "responses": {
          "200": {
            "description": "The key's metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Key"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      },
      "patch": {
        "tags": [
          "Keys"
        ],
        "operationId": "updateKey",
        "summary": "Update a key's limits, auto top-up, guardrails or tracing destination",
        "description": "Accepts the fields of KeyCreateRequest. `topup` sets or clears the key's auto top-up rule (KeyTopup). `tracing` sets where spans of this key's public-lane calls go: your OpenTelemetry collector (OTLP/HTTP JSON), Langfuse or Helicone. Spans follow the OpenTelemetry GenAI semantic conventions and add trellis.cost_usd, trellis.receipt_id, trellis.lane and trellis.provider. Prompt and completion text is included only with include_content: true. Attested and unlinkable lane calls are never exported.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The key's hash (Key.hash)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KeyCreateRequest"
              },
              "examples": {
                "honeycomb": {
                  "summary": "Honeycomb over OTLP",
                  "value": {
                    "tracing": {
                      "type": "otlp",
                      "endpoint": "https://api.honeycomb.io",
                      "headers": {
                        "x-honeycomb-team": "YOUR_API_KEY"
                      }
                    }
                  }
                },
                "langfuse": {
                  "summary": "Langfuse, with content",
                  "value": {
                    "tracing": {
                      "type": "langfuse",
                      "public_key": "pk-lf-...",
                      "secret_key": "sk-lf-...",
                      "include_content": true
                    }
                  }
                },
                "off": {
                  "summary": "Stop exporting",
                  "value": {
                    "tracing": null
                  }
                },
                "topup": {
                  "summary": "Auto top-up: below $2 left, add $10, at most $50 a week",
                  "value": {
                    "limit": 20,
                    "topup": {
                      "below_usd": 2,
                      "add_usd": 10,
                      "max_per_week_usd": 50
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The key's metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Key"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      },
      "delete": {
        "tags": [
          "Keys"
        ],
        "operationId": "deleteKey",
        "summary": "Disable a key",
        "description": "Owner or admin. The key stops working immediately; it is disabled rather than removed, because generations and on-chain balances refer to it (PATCH with disabled: false restores it). A key cannot delete itself (400). Disabling a key also stops a closure of its credits that it started: the closure is not paid while the key is disabled, and data.closure_held names it. This is what protects a balance when a key has leaked. An owner or admin lets the closure go ahead on purpose with POST /api/v1/credits/close/release.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The key's hash (Key.hash)."
          }
        ],
        "responses": {
          "200": {
            "description": "The key is disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "hash": {
                          "type": "string"
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "closure_held": {
                          "$ref": "#/components/schemas/ClosureHeld"
                        }
                      },
                      "required": [
                        "hash",
                        "deleted"
                      ]
                    }
                  },
                  "required": [
                    "deleted",
                    "data"
                  ]
                },
                "example": {
                  "deleted": true,
                  "data": {
                    "hash": "be9554a9d1eac080eb504f995cc2356755a82a7cb0601482df6e0fb9e919b5bd",
                    "deleted": true,
                    "closure_held": {
                      "id": "close_fixture",
                      "reason": "key_disabled",
                      "release": "POST /api/v1/credits/close/release"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/rerank": {
      "post": {
        "tags": [
          "Rerank"
        ],
        "operationId": "createRerank",
        "summary": "Rerank documents",
        "description": "Orders documents by relevance to a query through a provider's own /rerank. Served only by models whose output modalities include rerank; any other model, or a router where no provider lists a rerank model, is 404 model_not_found. Priced per token (pricing.prompt) and per search unit (pricing.request) as the provider reports them. An answer that is not a valid ranking of the documents sent is a failed attempt: the next provider is tried, and 502 providers_unavailable with nothing charged if none answers. Keys, budgets, per-call payment (HTTP 402), blind tokens, lanes, the disclosure ceiling and provider preferences work as for embeddings; the Oblivious HTTP gateway does not carry rerank calls yet. Also served at /v1/rerank.",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "PrivateToken": []
          },
          {}
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Payment"
          },
          {
            "$ref": "#/components/parameters/PaymentSignature"
          },
          {
            "$ref": "#/components/parameters/PaymentRecovery"
          },
          {
            "$ref": "#/components/parameters/TrellisTab"
          },
          {
            "$ref": "#/components/parameters/TrellisTabVoucher"
          },
          {
            "$ref": "#/components/parameters/DisclosureMax"
          },
          {
            "$ref": "#/components/parameters/Lane"
          },
          {
            "$ref": "#/components/parameters/LaneDowngrade"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RerankRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Results best first, with usage, cost and a signed receipt.",
            "headers": {
              "X-Trellis-Disclosure": {
                "$ref": "#/components/headers/Disclosure"
              },
              "X-Trellis-Lane": {
                "$ref": "#/components/headers/LaneServed"
              },
              "X-Receipt-Id": {
                "$ref": "#/components/headers/ReceiptId"
              },
              "Inference-Id": {
                "$ref": "#/components/headers/InferenceId"
              },
              "X-Generation-Id": {
                "$ref": "#/components/headers/GenerationId"
              },
              "X-Trellis-Policy-Hash": {
                "$ref": "#/components/headers/PolicyHash"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RerankResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/DisclosureUnavailable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "501": {
            "$ref": "#/components/responses/LaneNotAvailable"
          },
          "503": {
            "$ref": "#/components/responses/DisclosureProviderDown"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams": {
      "post": {
        "tags": [
          "Teams"
        ],
        "operationId": "createTeam",
        "summary": "Create a team (organisation)",
        "description": "Management key. A team made by a wallet-signed-in account is owned by that wallet.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "budget_usd": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Team"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      },
      "get": {
        "tags": [
          "Teams"
        ],
        "operationId": "listTeams",
        "summary": "List teams",
        "description": "A management key lists its account's teams; a team key (viewer, dev, admin, owner) its own team. Agent keys get 403.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Teams.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Team"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/{id}": {
      "get": {
        "tags": [
          "Teams"
        ],
        "operationId": "getTeam",
        "summary": "Get a team",
        "description": "Viewer, dev, admin or owner.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          }
        ],
        "responses": {
          "200": {
            "description": "The team.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Team"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      },
      "patch": {
        "tags": [
          "Teams"
        ],
        "operationId": "updateTeam",
        "summary": "Rename a team or set its org budget",
        "description": "Admin or owner. An org budget can be set only when every key in the team has a limit and the limits fit.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "budget_usd": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The team.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Team"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "org_budget_exceeded, org_budget_limit_required or org_budget_unlimited_keys: the change does not fit the org budget.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/{id}/members/{hash}": {
      "put": {
        "tags": [
          "Teams"
        ],
        "operationId": "setTeamMember",
        "summary": "Add a key to a team or change its role",
        "description": "Admin or owner; never a role at or above your own unless you are the owner.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          },
          {
            "name": "hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The key's hash."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "role"
                ],
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "owner",
                      "admin",
                      "dev",
                      "member",
                      "viewer",
                      "agent"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The membership.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "team": {
                          "type": "string"
                        },
                        "key_hash": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string",
                          "enum": [
                            "owner",
                            "admin",
                            "dev",
                            "member",
                            "viewer",
                            "agent"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "org_budget_exceeded, org_budget_limit_required or org_budget_unlimited_keys: the change does not fit the org budget.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/{id}/owner/challenge": {
      "post": {
        "tags": [
          "Teams"
        ],
        "operationId": "teamOwnerChallenge",
        "summary": "Start binding the team to a wallet",
        "description": "Owner only. Returns a one-time message for the wallet to sign (ed25519 over its exact UTF-8 bytes). The address is a base58 Solana address (32 bytes).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address"
                ],
                "properties": {
                  "address": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
                    "description": "Base58 Solana address (32-byte ed25519 public key)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The message to sign.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WalletChallenge"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/{id}/owner": {
      "post": {
        "tags": [
          "Teams"
        ],
        "operationId": "bindTeamOwner",
        "summary": "Bind the team to a wallet",
        "description": "Owner only. The wallet's ed25519 signature over the challenge message is verified against the base58 address; a multisig vault cannot sign a message and is not bindable yet. The bound address then signs in as owner. Refusals: 401 invalid_challenge (unknown, expired, used or made for another address) and 401 invalid_signature.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address",
                  "nonce",
                  "signature"
                ],
                "properties": {
                  "address": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
                    "description": "Base58 Solana address."
                  },
                  "nonce": {
                    "type": "string"
                  },
                  "signature": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$",
                    "description": "Base58 ed25519 signature (64 bytes) over the challenge message bytes."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The team.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Team"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/{id}/invites": {
      "post": {
        "tags": [
          "Teams"
        ],
        "operationId": "createTeamInvite",
        "summary": "Create a single-use invite",
        "description": "Admin or owner. The invite is shown once; only its SHA-256 is stored.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TeamInviteRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The invite.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "invite": {
                          "type": "string",
                          "pattern": "^ar-inv-[0-9a-f]{48}$"
                        },
                        "team": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string"
                        },
                        "method": {
                          "type": "string"
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/join/challenge": {
      "post": {
        "tags": [
          "Teams"
        ],
        "operationId": "teamJoinChallenge",
        "summary": "Start joining a team with an invite",
        "description": "No key. Passkey: WebAuthn creation options (attestation none, a random user handle, no name or email). Wallet: a message to sign.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "invite",
                  "method"
                ],
                "properties": {
                  "invite": {
                    "type": "string"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "passkey",
                      "wallet"
                    ]
                  },
                  "address": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The challenge.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/TeamChallenge"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/join": {
      "post": {
        "tags": [
          "Teams"
        ],
        "operationId": "joinTeam",
        "summary": "Join a team",
        "description": "No key. Send the passkey registration or the wallet signature. The invite and the challenge work once. Returns a 12-hour key for the new member.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "invite",
                  "challenge_id"
                ],
                "properties": {
                  "invite": {
                    "type": "string"
                  },
                  "challenge_id": {
                    "type": "string"
                  },
                  "passkey": {
                    "type": "object",
                    "required": [
                      "id",
                      "response"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "rawId": {
                        "type": "string"
                      },
                      "type": {
                        "const": "public-key"
                      },
                      "response": {
                        "type": "object",
                        "required": [
                          "clientDataJSON",
                          "attestationObject"
                        ],
                        "properties": {
                          "clientDataJSON": {
                            "type": "string"
                          },
                          "attestationObject": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "wallet": {
                    "type": "object",
                    "required": [
                      "address",
                      "signature"
                    ],
                    "properties": {
                      "address": {
                        "type": "string",
                        "pattern": "^0x[0-9a-fA-F]{40}$"
                      },
                      "signature": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Joined.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamSignedIn"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "already_member: that passkey or wallet is already in the team.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/{id}/sign-in/challenge": {
      "post": {
        "tags": [
          "Teams"
        ],
        "operationId": "teamSignInChallenge",
        "summary": "Start signing in to a team",
        "description": "No key. Passkey: WebAuthn request options with an empty allowCredentials (discoverable passkeys). Wallet: a message to sign.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "method"
                ],
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": [
                      "passkey",
                      "wallet"
                    ]
                  },
                  "address": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The challenge.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/TeamChallenge"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/{id}/sign-in": {
      "post": {
        "tags": [
          "Teams"
        ],
        "operationId": "teamSignIn",
        "summary": "Sign in to a team",
        "description": "No key. A passkey assertion (signature and a counter that must increase) or a wallet signature (base58 ed25519 signature by the wallet whose base58 address was challenged). The owner's bound wallet signs in as owner. Returns a 12-hour key with a limit of 0.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "challenge_id"
                ],
                "properties": {
                  "challenge_id": {
                    "type": "string"
                  },
                  "passkey": {
                    "type": "object",
                    "required": [
                      "id",
                      "response"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "rawId": {
                        "type": "string"
                      },
                      "type": {
                        "const": "public-key"
                      },
                      "response": {
                        "type": "object",
                        "required": [
                          "clientDataJSON",
                          "authenticatorData",
                          "signature"
                        ],
                        "properties": {
                          "clientDataJSON": {
                            "type": "string"
                          },
                          "authenticatorData": {
                            "type": "string"
                          },
                          "signature": {
                            "type": "string"
                          },
                          "userHandle": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    }
                  },
                  "wallet": {
                    "type": "object",
                    "required": [
                      "address",
                      "signature"
                    ],
                    "properties": {
                      "address": {
                        "type": "string",
                        "pattern": "^0x[0-9a-fA-F]{40}$"
                      },
                      "signature": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Signed in.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamSignedIn"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/{id}/principals/{pid}": {
      "patch": {
        "tags": [
          "Teams"
        ],
        "operationId": "updateTeamPrincipal",
        "summary": "Change a member's role, revoke or restore them",
        "description": "Admin or owner. Revoking disables every key issued to the member.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          },
          {
            "name": "pid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Member id (tp_...)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "dev",
                      "viewer"
                    ]
                  },
                  "disabled": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The member.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/TeamPrincipal"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      },
      "delete": {
        "tags": [
          "Teams"
        ],
        "operationId": "revokeTeamPrincipal",
        "summary": "Revoke a member",
        "description": "Admin or owner. Disables the member and every key issued to it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          },
          {
            "name": "pid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Member id (tp_...)."
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "revoked": {
                          "type": "boolean"
                        },
                        "keys_disabled": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/{id}/audit": {
      "get": {
        "tags": [
          "Teams"
        ],
        "operationId": "listTeamAudit",
        "summary": "Read the audit log",
        "description": "Viewer, dev, admin or owner. Entries in chain order.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          },
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of entries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "head",
                    "next_after",
                    "genesis"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TeamAuditEntry"
                      }
                    },
                    "head": {
                      "type": "object",
                      "properties": {
                        "seq": {
                          "type": "integer"
                        },
                        "hash": {
                          "type": "string"
                        }
                      }
                    },
                    "next_after": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "genesis": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/{id}/audit/roots": {
      "get": {
        "tags": [
          "Teams"
        ],
        "operationId": "listTeamAuditRoots",
        "summary": "Hourly Merkle roots of the audit log",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          }
        ],
        "responses": {
          "200": {
            "description": "One root per UTC hour.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TeamAuditRoot"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/teams/{id}/audit/export": {
      "get": {
        "tags": [
          "Teams"
        ],
        "operationId": "exportTeamAudit",
        "summary": "Export the audit log with its chain",
        "description": "Viewer, dev, admin or owner. JSONL: a header line, one entry per line, then one hourly root per line. CSV: team,seq,at,actor,action,target,detail,prev_hash,hash. Verify offline with node scripts/verify-audit.mjs <file>.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Team id (team_...)."
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "jsonl",
                "csv"
              ],
              "default": "jsonl"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The export as a download.",
            "headers": {
              "Content-Disposition": {
                "schema": {
                  "type": "string"
                },
                "description": "attachment; filename=\"trellis-audit-<team>.jsonl\" (or .csv)"
              }
            },
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "type": "string"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/status/slo": {
      "get": {
        "tags": [
          "Status page"
        ],
        "operationId": "getStatusSlo",
        "summary": "Availability, latency and error budget per lane and surface",
        "description": "Public, cached for 30 seconds. For each privacy lane (public, attested, unlinkable) and each API surface (chat, embeddings, batch, messages, ollama, and rerank where served): availability over 1 hour, 24 hours, 7 days and 30 days, p50 and p95 latency over 24 hours, error counts by class, the SLO target, the 30-day error budget, 90 daily availability figures and the open and recent incidents. The public lane is summed from public-lane request outcomes in five-minute buckets. The attested and unlinkable lanes use only the differentially private hourly releases published at /api/v1/stats and say so with source: dp-noised; they share one set of noisy counters and have no per-surface breakdown.",
        "responses": {
          "200": {
            "description": "The SLO document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StatusSlo"
                    }
                  }
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/status/incidents": {
      "get": {
        "tags": [
          "Status page"
        ],
        "operationId": "listStatusIncidents",
        "summary": "Confirmed incidents of the last 90 days",
        "description": "Public: confirmed incidents, newest first. With all=true and the operator token (ADMIN_TOKEN), also automatic suggestions and dismissed ones.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "all",
            "in": "query",
            "description": "Operator only.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Incidents.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StatusIncident"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "core"
      },
      "post": {
        "tags": [
          "Status page"
        ],
        "operationId": "createStatusIncident",
        "summary": "Open an incident (operator)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Operator only (ADMIN_TOKEN as Bearer or x-admin-token).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "title",
                  "lanes",
                  "message"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 140
                  },
                  "lanes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "public",
                        "attested",
                        "unlinkable"
                      ]
                    },
                    "minItems": 1
                  },
                  "surfaces": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "chat",
                        "embeddings",
                        "batch",
                        "messages",
                        "ollama",
                        "rerank"
                      ]
                    }
                  },
                  "impact": {
                    "type": "string",
                    "enum": [
                      "none",
                      "minor",
                      "major",
                      "critical"
                    ],
                    "default": "minor"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "investigating",
                      "identified",
                      "monitoring"
                    ],
                    "default": "investigating"
                  },
                  "message": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "started_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The incident.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StatusIncident"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/status/incidents/{id}": {
      "get": {
        "tags": [
          "Status page"
        ],
        "operationId": "getStatusIncident",
        "summary": "One confirmed incident",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The incident.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StatusIncident"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "core"
      },
      "patch": {
        "tags": [
          "Status page"
        ],
        "operationId": "patchStatusIncident",
        "summary": "Change an incident's title, impact, lanes or surfaces (operator)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 140
                  },
                  "lanes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "public",
                        "attested",
                        "unlinkable"
                      ]
                    },
                    "minItems": 1
                  },
                  "surfaces": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "chat",
                        "embeddings",
                        "batch",
                        "messages",
                        "ollama",
                        "rerank"
                      ]
                    }
                  },
                  "impact": {
                    "type": "string",
                    "enum": [
                      "none",
                      "minor",
                      "major",
                      "critical"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The incident.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StatusIncident"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/status/incidents/{id}/updates": {
      "post": {
        "tags": [
          "Status page"
        ],
        "operationId": "postStatusIncidentUpdate",
        "summary": "Post a status update (operator)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "Adds an update and moves the incident to its status. On an automatic suggestion, investigating, identified or monitoring confirms it (it becomes public) and dismissed drops it. resolved and dismissed are final: a later update is refused with 409.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "status",
                  "message"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "investigating",
                      "identified",
                      "monitoring",
                      "resolved",
                      "dismissed"
                    ]
                  },
                  "message": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "impact": {
                    "type": "string",
                    "enum": [
                      "none",
                      "minor",
                      "major",
                      "critical"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The incident.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StatusIncident"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The incident is closed, or only a suggestion can be dismissed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/status/incidents.atom": {
      "get": {
        "tags": [
          "Status page"
        ],
        "operationId": "getStatusIncidentsAtom",
        "summary": "Incidents as an Atom feed",
        "responses": {
          "200": {
            "description": "Atom 1.0 feed of confirmed incidents.",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/status/incidents.rss": {
      "get": {
        "tags": [
          "Status page"
        ],
        "operationId": "getStatusIncidentsRss",
        "summary": "Incidents as an RSS feed",
        "responses": {
          "200": {
            "description": "RSS 2.0 feed of confirmed incidents.",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/characters": {
      "get": {
        "tags": [
          "Characters"
        ],
        "operationId": "listCharacters",
        "summary": "Discover public characters, or list your own",
        "description": "With no key: public characters only, newest first, filtered by tag and a text search over name, tags and creator. With ?mine=1 and a key: the caller's own characters of every visibility.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Text search over name, tags and creator."
          },
          {
            "name": "mine",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "The caller's own characters; needs a key."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Characters.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Character"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      },
      "post": {
        "tags": [
          "Characters"
        ],
        "operationId": "createCharacter",
        "summary": "Create a character from a card",
        "description": "Send a Tavern card as JSON (card) or a PNG that carries one (png). A private card is encrypted on the client with sealCard from @trellis/client/characters: send sealed_card and card_hash, and the router keeps only the ciphertext and the hash.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CharacterInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Character"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "character_limit_reached: the account keeps the most characters it may. Delete one first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "payload_too_large: the PNG is over 8 MB, or the card is over the size limit as JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/characters/{id}": {
      "get": {
        "tags": [
          "Characters"
        ],
        "operationId": "getCharacter",
        "summary": "Get a character",
        "description": "Public and unlisted characters to anyone with the id. A private one only to its owner, with sealed_card; to anyone else it is a 404.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^ch_[0-9a-f]{24}$"
            },
            "description": "The character id, as in @character/<id>."
          }
        ],
        "responses": {
          "200": {
            "description": "The character.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Character"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      },
      "put": {
        "tags": [
          "Characters"
        ],
        "operationId": "updateCharacter",
        "summary": "Replace a character's card, visibility or default model",
        "description": "Owner only. The same body as POST; the card_hash changes with the card.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^ch_[0-9a-f]{24}$"
            },
            "description": "The character id, as in @character/<id>."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CharacterInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated character.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Character"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "413": {
            "description": "payload_too_large: the PNG is over 8 MB, or the card is over the size limit as JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      },
      "delete": {
        "tags": [
          "Characters"
        ],
        "operationId": "deleteCharacter",
        "summary": "Delete a character",
        "description": "Owner only. Calls to @character/<id> fail from then on; receipts of past calls are unaffected.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^ch_[0-9a-f]{24}$"
            },
            "description": "The character id, as in @character/<id>."
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "id",
                        "deleted"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "deleted": {
                          "const": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/characters/{id}/export": {
      "get": {
        "tags": [
          "Characters"
        ],
        "operationId": "exportCharacter",
        "summary": "Download the card as JSON or PNG",
        "description": "Public and unlisted characters. The PNG carries the card in a chara tEXt chunk (spec v2) or in both ccv3 and chara (spec v3), so SillyTavern and other card tools import it.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^ch_[0-9a-f]{24}$"
            },
            "description": "The character id, as in @character/<id>."
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "png"
              ],
              "default": "json"
            }
          },
          {
            "name": "spec",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "v2",
                "v3"
              ]
            },
            "description": "Defaults to the card's own spec."
          }
        ],
        "responses": {
          "200": {
            "description": "The card file.",
            "headers": {
              "Content-Disposition": {
                "schema": {
                  "type": "string"
                },
                "description": "attachment; filename=\"<name>.json\" (or .png)"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CharacterCard"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "contentEncoding": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/characters/{id}/greetings": {
      "get": {
        "tags": [
          "Characters"
        ],
        "operationId": "getCharacterGreetings",
        "summary": "The greetings a chat can open with",
        "description": "first_mes, then the alternate greetings. The index is what the chat endpoint's greeting field takes.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^ch_[0-9a-f]{24}$"
            },
            "description": "The character id, as in @character/<id>."
          }
        ],
        "responses": {
          "200": {
            "description": "The greetings.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "greetings"
                      ],
                      "properties": {
                        "greetings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/characters/{id}/usage": {
      "get": {
        "tags": [
          "Characters"
        ],
        "operationId": "getCharacterUsage",
        "summary": "Calls and cost per day, for the card's creator",
        "description": "Owner only. Creator attribution for a public card: how many calls used it and what they cost, per day. Never the content of a call, and never who made it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^ch_[0-9a-f]{24}$"
            },
            "description": "The character id, as in @character/<id>."
          }
        ],
        "responses": {
          "200": {
            "description": "Usage per day, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CharacterUsage"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/characters/{id}/chat": {
      "post": {
        "tags": [
          "Characters"
        ],
        "operationId": "characterChat",
        "summary": "Chat with a character",
        "description": "A chat completion with the character's card as the prompt. The model is model, then models[0], then the card's default model. The lane defaults to attested when the model has an attested provider, else public; a request's own provider.lane wins, and a lane that cannot be served fails as on /chat/completions. Budgets, guardrails and signed receipts apply as there. Memory sent in memory is used for this call only and never stored. For a private card, send the decrypted card: without it the call fails with 400 card_required, and a card that does not hash to card_hash with 409 card_hash_mismatch. A character with no default model and no model in the request fails with 400 model_required.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^ch_[0-9a-f]{24}$"
            },
            "description": "The character id, as in @character/<id>."
          },
          {
            "$ref": "#/components/parameters/Lane"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CharacterChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A chat completion, or SSE events followed by data: [DONE] when stream is true.",
            "headers": {
              "X-Trellis-Character": {
                "description": "The character id that answered.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Trellis-Character-Lane": {
                "description": "The lane the character call ran on.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "attested",
                    "public"
                  ]
                }
              },
              "X-Trellis-Character-Note": {
                "description": "Present when the attested lane was not available for this model, in plain English.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Trellis-Lane": {
                "$ref": "#/components/headers/LaneServed"
              },
              "X-Receipt-Id": {
                "$ref": "#/components/headers/ReceiptId"
              },
              "X-Trellis-Character-Session": {
                "description": "The session_id the request sent, echoed back.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "An OpenAI chat completion."
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "card_hash_mismatch: the decrypted card sent for a private character does not hash to its card_hash.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "description": "no_attested_endpoint: the request asked for the attested lane and no attested endpoint can serve the model.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/characters/group/next": {
      "post": {
        "tags": [
          "Characters"
        ],
        "operationId": "characterGroupNext",
        "summary": "Pick who speaks next in a group chat",
        "description": "Returns the member that should answer next; call its chat endpoint with the same messages. Nothing is stored.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CharacterGroupNextRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The next speaker.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "next",
                        "index"
                      ],
                      "properties": {
                        "next": {
                          "type": "string"
                        },
                        "index": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/memory": {
      "get": {
        "tags": [
          "Memory"
        ],
        "operationId": "listMemory",
        "summary": "List memory entries (metadata only)",
        "description": "The caller's entries, optionally for one scope, without the sealed values.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entries and their total size.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "total_bytes"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MemoryEntry"
                      }
                    },
                    "total_bytes": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      },
      "post": {
        "tags": [
          "Memory"
        ],
        "operationId": "createMemory",
        "summary": "Store a sealed memory entry",
        "description": "The client encrypts the entry and derives the scope; the router stores the ciphertext and cannot read it or tell which character it is for. An embedding is stored only with embedding_opt_in: true, because a vector is derived from the text and can leak its topic.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemoryInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MemoryEntry"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "description": "The entry, or the caller's memory in total, is too large.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      },
      "delete": {
        "tags": [
          "Memory"
        ],
        "operationId": "deleteMemoryScope",
        "summary": "Delete every entry in a scope",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "scope": {
                          "type": "string"
                        },
                        "deleted": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/memory/{id}": {
      "get": {
        "tags": [
          "Memory"
        ],
        "operationId": "getMemory",
        "summary": "Read one sealed memory entry",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The memory entry id."
          }
        ],
        "responses": {
          "200": {
            "description": "The entry with its sealed value.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MemoryEntry"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      },
      "put": {
        "tags": [
          "Memory"
        ],
        "operationId": "updateMemory",
        "summary": "Replace a sealed memory entry",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The memory entry id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemoryInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replaced.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MemoryEntry"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "413": {
            "description": "The entry is too large.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      },
      "delete": {
        "tags": [
          "Memory"
        ],
        "operationId": "deleteMemory",
        "summary": "Delete a memory entry",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The memory entry id."
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "deleted": {
                          "const": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/memory/search": {
      "post": {
        "tags": [
          "Memory"
        ],
        "operationId": "searchMemory",
        "summary": "Nearest sealed entries to an embedding",
        "description": "Searches only entries stored with embedding_opt_in. Returns the sealed values for the client to decrypt.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemorySearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The nearest entries, best first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "score",
                          "kind",
                          "sealed"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "score": {
                            "type": "number"
                          },
                          "kind": {
                            "type": "string"
                          },
                          "sealed": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/skills": {
      "get": {
        "tags": [
          "Skills"
        ],
        "operationId": "listSkills",
        "summary": "Search the skills registry",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Matches name, description, author and slug."
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated scan levels: trusted, caution, dangerous."
          },
          {
            "name": "include_revoked",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Skills, trusted first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SkillSummary"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "download_levels": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "note": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/skills/import": {
      "post": {
        "tags": [
          "Skills"
        ],
        "operationId": "importSkill",
        "summary": "Import a skill from a git repository or an archive; it is hashed and scanned",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "price_usd",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "For an archive body: the install price."
          },
          {
            "name": "path",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "For an archive body: the skill's folder inside the archive."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "description": "Exactly one of git or archive.",
                "properties": {
                  "git": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "url"
                    ],
                    "properties": {
                      "url": {
                        "type": "string",
                        "description": "https:// only."
                      },
                      "ref": {
                        "type": "string"
                      },
                      "path": {
                        "type": "string"
                      }
                    }
                  },
                  "archive": {
                    "type": "string",
                    "contentEncoding": "base64",
                    "description": "A .tar.gz, .tar or .zip of the skill folder."
                  },
                  "path": {
                    "type": "string"
                  },
                  "price_usd": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 10000
                  }
                }
              }
            },
            "application/gzip": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "application/x-tar": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "application/zip": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The same files were already imported; the existing skill.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Skill"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Imported and scanned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Skill"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/skills/{id}": {
      "get": {
        "tags": [
          "Skills"
        ],
        "operationId": "getSkill",
        "summary": "A skill: manifest, files, content hash, scan report, price and chain fields",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^sk_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The skill.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Skill"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      },
      "patch": {
        "tags": [
          "Skills"
        ],
        "operationId": "updateSkill",
        "summary": "Change a skill's price (the publishing account)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^sk_[0-9a-f]{24}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "price_usd"
                ],
                "properties": {
                  "price_usd": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 10000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The skill.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Skill"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/skills/{id}/download": {
      "get": {
        "tags": [
          "Skills"
        ],
        "operationId": "downloadSkill",
        "summary": "Download the canonical tar.gz (trusted and caution skills only; paid skills after an install)",
        "description": "Returns 403 with the scan report for a dangerous or revoked skill. A paid skill needs the key of its author or of an account that installed it (402 otherwise). X-Skill-Content-Hash carries the sha256 of the uncompressed tar.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^sk_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The gzipped canonical tar.",
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/skills/{id}/install": {
      "post": {
        "tags": [
          "Skills"
        ],
        "operationId": "installSkill",
        "summary": "Install a skill: a paid one debits the key's balance, 90% to the author and 10% network fee, with a signed receipt",
        "description": "Idempotent per skill and account: a repeat returns the first install and receipt (200) without a second charge.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^sk_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Already installed by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SkillInstall"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Installed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SkillInstall"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/skills/{id}/revoke": {
      "post": {
        "tags": [
          "Skills"
        ],
        "operationId": "revokeSkill",
        "summary": "Revoke a skill (operator)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^sk_[0-9a-f]{24}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 280
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The revoked skill.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Skill"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/network/policy": {
      "get": {
        "tags": [
          "Network host policy"
        ],
        "description": "Public when NETWORK_POLICY_ENABLED is true (default false; requires TLOG_ENABLED). No policy is seeded. Includes canonical JSON, SHA-256, detached Ed25519 signature and public log verifier key. Pin the verifier key independently and verify the host_policy inclusion proof under a signed checkpoint with independent witness or public-log evidence. Publication does not change existing provider admission. Current sidecars do not bind a source hash, engine image or model ID; missing bindings fail the pure check. Trellis reads request text in memory on every lane.",
        "responses": {
          "200": {
            "description": "Published host policy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HostPolicyPublication"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "operationId": "getCurrentNetworkHostPolicy",
        "summary": "Current signed network host policy",
        "x-launch-surface": "all"
      }
    },
    "/api/v1/network/policy/{version}": {
      "get": {
        "tags": [
          "Network host policy"
        ],
        "description": "Public when NETWORK_POLICY_ENABLED is true (default false; requires TLOG_ENABLED). No policy is seeded. Includes canonical JSON, SHA-256, detached Ed25519 signature and public log verifier key. Pin the verifier key independently and verify the host_policy inclusion proof under a signed checkpoint with independent witness or public-log evidence. Publication does not change existing provider admission. Current sidecars do not bind a source hash, engine image or model ID; missing bindings fail the pure check. Trellis reads request text in memory on every lane.",
        "responses": {
          "200": {
            "description": "Published host policy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HostPolicyPublication"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "operationId": "getNetworkHostPolicyVersion",
        "summary": "An immutable signed network host policy version",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2147483647
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/trpc/network.publishPolicy": {
      "post": {
        "tags": [
          "Network host policy"
        ],
        "operationId": "publishNetworkHostPolicy",
        "summary": "Publish a consecutive signed host policy version (operator)",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "description": "POST /trpc/network.publishPolicy accepts the policy document directly as a tRPC JSON input. Requires ADMIN_TOKEN as x-admin-token or Authorization: Bearer, NETWORK_POLICY_ENABLED and TLOG_ENABLED. The policy, host_policy log leaf and signed checkpoint commit atomically. Versions start at 1 and advance consecutively; exact resubmission is idempotent, replacement is refused. Issue time cannot be in the future or before the preceding version. allow_dev must be false. Existing providers are unaffected. This publication path is groundwork for later host signup; it does not open signup.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HostPolicy"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "tRPC publication result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/HostPolicyPublication"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "tRPC error envelope: unauthorized without the operator token, precondition failed when disabled, conflict for an occupied or nonconsecutive version, or bad request for invalid policy or issue time.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/e2ee/sessions/{id}": {
      "get": {
        "summary": "Proxy content-addressed gateway upstream session",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ACI session whose canonical hash must match its id.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "description": "Gateway session unavailable."
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/e2ee/chat/completions": {
      "post": {
        "summary": "End-to-end encrypted chat (attested gateway)",
        "description": "Off by default (E2EE_PASSTHROUGH_ENABLED=false). Exact JSON bytes and encrypted fields are forwarded unchanged; SSE bytes pass through unchanged. Message content is restored inside the attested gateway enclave, which forwards it to the serving workload over a separate confidential channel. Model, sizes, timing, public keys and payment metadata remain visible. Only the attested-gateway provider and text chat are supported; tools, files, search and unknown fields are refused. Holds use a conservative input-byte bound plus max_tokens. Charges trust gateway-reported usage; completion or truncation without usage charges the hold. The charge never exceeds the hold: when the gateway reports usage priced above it, the receipt carries e2ee.over_hold (USD string, the list price of the reported usage) and the gateway is paid no more than was charged. The router cannot check the restored plaintext request hash; clients must independently verify attestation and complete signed wire receipts. Prepaid keys and blind tokens are supported.",
        "parameters": [
          {
            "in": "header",
            "name": "X-E2EE-Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Exactly 2."
          },
          {
            "in": "header",
            "name": "X-Client-Pub-Key",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client X25519 public key, 32-byte hex."
          },
          {
            "in": "header",
            "name": "X-Model-Pub-Key",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Attestation-bound gateway X25519 key, 32-byte hex."
          },
          {
            "in": "header",
            "name": "X-E2EE-Nonce",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Fresh 32-byte replay nonce, 64 hex characters."
          },
          {
            "in": "header",
            "name": "X-E2EE-Timestamp",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unix seconds within 300 seconds."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "model",
                  "messages",
                  "max_tokens",
                  "provider"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "messages": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 128,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "role",
                        "content"
                      ],
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "system",
                            "developer",
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string",
                          "pattern": "^(?:[0-9a-f]{2}){60,}$",
                          "description": "v2 X25519 field ciphertext."
                        }
                      }
                    }
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 32768
                  },
                  "stream": {
                    "type": "boolean"
                  },
                  "stream_options": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "include_usage"
                    ],
                    "properties": {
                      "include_usage": {
                        "const": true
                      }
                    }
                  },
                  "provider": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "aci_verified",
                      "zdr"
                    ],
                    "properties": {
                      "aci_verified": {
                        "const": true
                      },
                      "zdr": {
                        "const": true
                      },
                      "aci_session_ids": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 8,
                        "items": {
                          "type": "string",
                          "pattern": "^[0-9a-f]{64}$"
                        }
                      }
                    }
                  },
                  "n": {
                    "const": 1
                  },
                  "temperature": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 2
                  },
                  "top_p": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Encrypted JSON or SSE, with X-Receipt-Id, X-Trellis-Lane and X-E2EE-Receipt-Id. Stream completion is provisional until signed gateway evidence verifies.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "413": {
            "description": "Envelope exceeds 1 MiB."
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "502": {
            "description": "Gateway rejection or E2EE transport failure."
          },
          "503": {
            "description": "Configured provider or fresh attestation unavailable."
          }
        },
        "security": [
          {
            "BearerAuth": []
          },
          {
            "PrivateToken": []
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/e2ee/attestation": {
      "get": {
        "summary": "Proxy gateway attestation for independent client verification",
        "description": "Off by default. The client supplies its own fresh nonce and must verify the TDX quote, keyset binding, measurements, freshness, event log and deployment policy itself. A router boolean is not proof.",
        "parameters": [
          {
            "in": "query",
            "name": "nonce",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Unmodified attestation document fields.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "description": "Gateway evidence unavailable."
          },
          "503": {
            "description": "Provider unavailable."
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/e2ee/receipts/{id}": {
      "get": {
        "summary": "Proxy signed gateway receipt",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._-]{1,128}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Signed ACI receipt for independent client verification.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "description": "Gateway evidence unavailable."
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/me/record-certificate": {
      "post": {
        "tags": [
          "Agents"
        ],
        "summary": "Issue a signed track-record certificate",
        "description": "Signed by Trellis's router, which sees the agent's activity; not a zero-knowledge proof. Requests through Trellis only; no on-chain enforcement. AGENT_POLICY_ENABLED gates availability; TLOG_ENABLED is required for issuance. Fresh random pseudonym; no agent key hash or account id. Shared issuer key, claims and timing may correlate certificates. Five issuance attempts per account per minute. No certificates or prompt text are stored by this path. Later events do not revoke the seven-day snapshot.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "claims"
                ],
                "properties": {
                  "claims": {
                    "$ref": "#/components/schemas/AgentRecordClaims"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Certificate result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentRecordCertificate"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid claim request.",
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Authentication required.",
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Feature disabled.",
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "Any claim false or insufficient retained history; no partial certificate.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Account issuance limit exceeded; Retry-After header.",
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "description": "Signing key log unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "operationId": "issueAgentRecordCertificate",
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/certificates/verify": {
      "post": {
        "tags": [
          "Agents"
        ],
        "summary": "Verify a track-record certificate",
        "description": "Public when AGENT_POLICY_ENABLED is on. Checks shape, signature, issuer-key issuance window and expiry, not underlying observations. Signed by Trellis's router, which sees the agent's activity; not a zero-knowledge proof.",
        "security": [],
        "responses": {
          "200": {
            "description": "Certificate result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "valid",
                        "notice"
                      ],
                      "properties": {
                        "valid": {
                          "type": "boolean"
                        },
                        "notice": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed certificate.",
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "description": "Feature disabled.",
            "$ref": "#/components/responses/NotFound"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRecordCertificate"
              }
            }
          }
        },
        "operationId": "verifyAgentRecordCertificate",
        "x-launch-surface": "all"
      },
      "get": {
        "tags": [
          "Agents"
        ],
        "summary": "Verify a track-record certificate",
        "description": "Public when AGENT_POLICY_ENABLED is on. Checks shape, signature, issuer-key issuance window and expiry, not underlying observations. Signed by Trellis's router, which sees the agent's activity; not a zero-knowledge proof.",
        "security": [],
        "responses": {
          "200": {
            "description": "Certificate result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "valid",
                        "notice"
                      ],
                      "properties": {
                        "valid": {
                          "type": "boolean"
                        },
                        "notice": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed certificate.",
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "description": "Feature disabled.",
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "certificate",
            "in": "query",
            "required": true,
            "description": "URL-encoded certificate JSON. Prefer POST to avoid URL retention outside the router.",
            "schema": {
              "type": "string",
              "maxLength": 8192
            }
          }
        ],
        "operationId": "verifyAgentRecordCertificateQuery",
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/profiles": {
      "get": {
        "operationId": "agentDirectory",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Discover opt-in public agents",
        "description": "AGENT_PROFILES_ENABLED defaults false; off returns 404. Public owner-supplied tags are not verified abilities. Only selected boolean rulebook categories are shown, never exact caps, thresholds, private identifiers or reasons. Rulebook categories require AGENT_POLICY_ENABLED. Certificates are selected-key router-signed snapshots, require agent policies and TLOG_ENABLED, and are shown only after signature, signing-key window and expiry checks. Agent-host sealing and attestation are unavailable. Random slugs do not stop correlation through owner-supplied text or publication timing. Disabled or expired keys are hidden. MCP trellis_agent_directory accepts the same arguments without authentication. Exact tag match; ascending slug cursor pagination.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "name",
                          "description",
                          "url",
                          "capabilities",
                          "provider",
                          "trellis"
                        ],
                        "properties": {
                          "name": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 80
                          },
                          "description": {
                            "type": "string",
                            "maxLength": 280
                          },
                          "url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Public profile page, not invocation endpoint."
                          },
                          "homepage": {
                            "type": "string",
                            "format": "uri",
                            "maxLength": 500,
                            "description": "HTTP(S) only, without embedded credentials."
                          },
                          "endpoint": {
                            "type": "string",
                            "format": "uri",
                            "maxLength": 500,
                            "description": "Owner-declared HTTPS agent endpoint, when set."
                          },
                          "capabilities": {
                            "type": "array",
                            "maxItems": 16,
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 40
                            }
                          },
                          "provider": {
                            "type": "object",
                            "properties": {
                              "organization": {
                                "const": "Trellis"
                              }
                            },
                            "required": [
                              "organization"
                            ]
                          },
                          "trellis": {
                            "type": "object",
                            "required": [
                              "id",
                              "rulebook_summary",
                              "certificates",
                              "status",
                              "notice"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "pattern": "^[A-Za-z0-9_-]{24}$"
                              },
                              "rulebook_summary": {
                                "type": "object",
                                "additionalProperties": false,
                                "properties": {
                                  "has_spending_caps": {
                                    "type": "boolean"
                                  },
                                  "asks_before_spending": {
                                    "type": "boolean"
                                  },
                                  "kill_switch_armed": {
                                    "type": "boolean"
                                  },
                                  "killed": {
                                    "type": "boolean"
                                  }
                                }
                              },
                              "certificates": {
                                "type": "array",
                                "maxItems": 1,
                                "items": {
                                  "type": "object",
                                  "additionalProperties": false,
                                  "required": [
                                    "payload",
                                    "key_id",
                                    "signature",
                                    "valid"
                                  ],
                                  "properties": {
                                    "key_id": {
                                      "type": "string",
                                      "pattern": "^[0-9a-f]{16}$"
                                    },
                                    "signature": {
                                      "type": "string",
                                      "pattern": "^[A-Za-z0-9+/]{86}==$"
                                    },
                                    "payload": {
                                      "type": "object",
                                      "additionalProperties": false,
                                      "required": [
                                        "version",
                                        "type",
                                        "pseudonym",
                                        "claims",
                                        "issued_at",
                                        "expires_at",
                                        "notice"
                                      ],
                                      "properties": {
                                        "version": {
                                          "const": 1
                                        },
                                        "type": {
                                          "const": "trellis.agent.record-certificate"
                                        },
                                        "pseudonym": {
                                          "type": "string",
                                          "pattern": "^[0-9a-f]{64}$"
                                        },
                                        "claims": {
                                          "$ref": "#/components/schemas/AgentRecordClaims"
                                        },
                                        "issued_at": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "expires_at": {
                                          "type": "string",
                                          "format": "date-time",
                                          "description": "Exactly seven days after issuance."
                                        },
                                        "notice": {
                                          "const": "Signed by Trellis's router, which sees the agent's activity; not a zero-knowledge proof."
                                        }
                                      }
                                    },
                                    "valid": {
                                      "const": true,
                                      "description": "Router read-time validity metadata; remove this field before submitting the certificate to strict certificate verifiers."
                                    }
                                  }
                                }
                              },
                              "status": {
                                "type": "object",
                                "properties": {
                                  "sealed": {
                                    "const": "unavailable"
                                  },
                                  "attested": {
                                    "const": "unavailable"
                                  }
                                }
                              },
                              "notice": {
                                "type": "string"
                              },
                              "identity": {
                                "description": "AGENT_IDENTITY_ENABLED only. Either {opted_out: true} or links: card, receipt_keys (/.well-known/trellis-receipt-keys.json), receipt_key_id, registration (ERC-8004 registration file or null) and erc8004 {registry, agent_id, status}.",
                                "type": "object"
                              },
                              "liveness": {
                                "description": "AGENT_IDENTITY_ENABLED only. endpoint_declared, live (true, false or null before the first probe), probed_at, http_status and the probe receipt signed with the router's receipt key.",
                                "type": "object"
                              },
                              "track_record": {
                                "description": "AGENT_IDENTITY_ENABLED only. The newest published, unexpired track record: id, url, stats, merkle_root, expires_at; or null.",
                                "anyOf": [
                                  {
                                    "type": "object"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "reputation": {
                                "description": "PAID_FEEDBACK_ENABLED only. {opted_in: false, url} or opted_in, score (0 to 100 or null), feedback_count, weight_usd, by_kind, half_life_days and url.",
                                "type": "object"
                              },
                              "holder_badge": {
                                "type": "string",
                                "description": "The name of the holder tier of the wallet behind this profile. Present only when the owner switched show_holder_badge on and the wallet holds a tier with a badge right now."
                              }
                            }
                          }
                        }
                      }
                    },
                    "next_cursor": {
                      "anyOf": [
                        {
                          "type": "string",
                          "pattern": "^[A-Za-z0-9_-]{24}$"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{24}$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/profiles/{slug}": {
      "get": {
        "operationId": "publicAgentCard",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Read an A2A-style public agent card",
        "description": "AGENT_PROFILES_ENABLED defaults false; off returns 404. Public owner-supplied tags are not verified abilities. Only selected boolean rulebook categories are shown, never exact caps, thresholds, private identifiers or reasons. Rulebook categories require AGENT_POLICY_ENABLED. Certificates are selected-key router-signed snapshots, require agent policies and TLOG_ENABLED, and are shown only after signature, signing-key window and expiry checks. Agent-host sealing and attestation are unavailable. Random slugs do not stop correlation through owner-supplied text or publication timing.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "name",
                    "description",
                    "url",
                    "capabilities",
                    "provider",
                    "trellis"
                  ],
                  "properties": {
                    "name": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 80
                    },
                    "description": {
                      "type": "string",
                      "maxLength": 280
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Public profile page, not invocation endpoint."
                    },
                    "homepage": {
                      "type": "string",
                      "format": "uri",
                      "maxLength": 500,
                      "description": "HTTP(S) only, without embedded credentials."
                    },
                    "endpoint": {
                      "type": "string",
                      "format": "uri",
                      "maxLength": 500,
                      "description": "Owner-declared HTTPS agent endpoint, when set."
                    },
                    "payout_wallet": {
                      "type": "string",
                      "pattern": "^0x[0-9a-f]{40}$",
                      "description": "Owner-declared USDC wallet that other agents pay directly, when set."
                    },
                    "capabilities": {
                      "type": "array",
                      "maxItems": 16,
                      "items": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 40
                      }
                    },
                    "provider": {
                      "type": "object",
                      "properties": {
                        "organization": {
                          "const": "Trellis"
                        }
                      },
                      "required": [
                        "organization"
                      ]
                    },
                    "trellis": {
                      "type": "object",
                      "required": [
                        "id",
                        "rulebook_summary",
                        "certificates",
                        "status",
                        "notice"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^[A-Za-z0-9_-]{24}$"
                        },
                        "rulebook_summary": {
                          "type": "object",
                          "additionalProperties": false,
                          "properties": {
                            "has_spending_caps": {
                              "type": "boolean"
                            },
                            "asks_before_spending": {
                              "type": "boolean"
                            },
                            "kill_switch_armed": {
                              "type": "boolean"
                            },
                            "killed": {
                              "type": "boolean"
                            }
                          }
                        },
                        "certificates": {
                          "type": "array",
                          "maxItems": 1,
                          "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                              "payload",
                              "key_id",
                              "signature",
                              "valid"
                            ],
                            "properties": {
                              "key_id": {
                                "type": "string",
                                "pattern": "^[0-9a-f]{16}$"
                              },
                              "signature": {
                                "type": "string",
                                "pattern": "^[A-Za-z0-9+/]{86}==$"
                              },
                              "payload": {
                                "type": "object",
                                "additionalProperties": false,
                                "required": [
                                  "version",
                                  "type",
                                  "pseudonym",
                                  "claims",
                                  "issued_at",
                                  "expires_at",
                                  "notice"
                                ],
                                "properties": {
                                  "version": {
                                    "const": 1
                                  },
                                  "type": {
                                    "const": "trellis.agent.record-certificate"
                                  },
                                  "pseudonym": {
                                    "type": "string",
                                    "pattern": "^[0-9a-f]{64}$"
                                  },
                                  "claims": {
                                    "$ref": "#/components/schemas/AgentRecordClaims"
                                  },
                                  "issued_at": {
                                    "type": "string",
                                    "format": "date-time"
                                  },
                                  "expires_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "description": "Exactly seven days after issuance."
                                  },
                                  "notice": {
                                    "const": "Signed by Trellis's router, which sees the agent's activity; not a zero-knowledge proof."
                                  }
                                }
                              },
                              "valid": {
                                "const": true,
                                "description": "Router read-time validity metadata; remove this field before submitting the certificate to strict certificate verifiers."
                              }
                            }
                          }
                        },
                        "status": {
                          "type": "object",
                          "properties": {
                            "sealed": {
                              "const": "unavailable"
                            },
                            "attested": {
                              "const": "unavailable"
                            }
                          }
                        },
                        "notice": {
                          "type": "string"
                        },
                        "identity": {
                          "description": "AGENT_IDENTITY_ENABLED only. Either {opted_out: true} or links: card, receipt_keys (/.well-known/trellis-receipt-keys.json), receipt_key_id, registration (ERC-8004 registration file or null) and erc8004 {registry, agent_id, status}.",
                          "type": "object"
                        },
                        "liveness": {
                          "description": "AGENT_IDENTITY_ENABLED only. endpoint_declared, live (true, false or null before the first probe), probed_at, http_status and the probe receipt signed with the router's receipt key.",
                          "type": "object"
                        },
                        "track_record": {
                          "description": "AGENT_IDENTITY_ENABLED only. The newest published, unexpired track record: id, url, stats, merkle_root, expires_at; or null.",
                          "anyOf": [
                            {
                              "type": "object"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "reputation": {
                          "description": "PAID_FEEDBACK_ENABLED only. {opted_in: false, url} or opted_in, score (0 to 100 or null), feedback_count, weight_usd, by_kind, half_life_days and url.",
                          "type": "object"
                        },
                        "holder_badge": {
                          "type": "string",
                          "description": "The name of the holder tier of the wallet behind this profile. Present only when the owner switched show_holder_badge on and the wallet holds a tier with a badge right now."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{24}$"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/profile": {
      "get": {
        "operationId": "agentProfileSettings",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Read owned profile publication settings",
        "description": "AGENT_PROFILES_ENABLED defaults false; off returns 404. Public owner-supplied tags are not verified abilities. Only selected boolean rulebook categories are shown, never exact caps, thresholds, private identifiers or reasons. Rulebook categories require AGENT_POLICY_ENABLED. Certificates are selected-key router-signed snapshots, require agent policies and TLOG_ENABLED, and are shown only after signature, signing-key window and expiry checks. Agent-host sealing and attestation are unavailable. Random slugs do not stop correlation through owner-supplied text or publication timing.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "anyOf": [
                        {
                          "type": "null"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 80
                            },
                            "description": {
                              "type": "string",
                              "maxLength": 280
                            },
                            "homepage": {
                              "type": "string",
                              "format": "uri",
                              "maxLength": 500,
                              "description": "HTTP(S) only, without embedded credentials."
                            },
                            "capabilities": {
                              "type": "array",
                              "maxItems": 16,
                              "items": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 40
                              },
                              "default": []
                            },
                            "show": {
                              "type": "array",
                              "maxItems": 3,
                              "items": {
                                "type": "string",
                                "enum": [
                                  "spending_caps",
                                  "ask_first",
                                  "kill_switch"
                                ]
                              },
                              "default": []
                            },
                            "certificate_claims": {
                              "type": "array",
                              "maxItems": 16,
                              "uniqueItems": true,
                              "items": {
                                "type": "string",
                                "pattern": "^(requests_at_least|no_denials_days|no_kills_days|active_days_at_least):[1-9][0-9]{0,14}$"
                              },
                              "default": [],
                              "description": "Absence claims limited to 90 days. Verified against this key, never accepted from another certificate."
                            },
                            "id": {
                              "type": "string",
                              "pattern": "^[A-Za-z0-9_-]{24}$"
                            },
                            "show_holder_badge": {
                              "type": "boolean",
                              "default": false,
                              "description": "Opt-in holder badge. When true, and the key belongs to a wallet sign-in account whose wallet holds a tier with a badge, the public card shows trellis.holder_badge with the tier name. Never the wallet address or the balance."
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "422": {
            "$ref": "#/components/responses/ApiError"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      },
      "put": {
        "operationId": "publishAgentProfile",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Publish selected public agent fields",
        "description": "AGENT_PROFILES_ENABLED defaults false; off returns 404. Public owner-supplied tags are not verified abilities. Only selected boolean rulebook categories are shown, never exact caps, thresholds, private identifiers or reasons. Rulebook categories require AGENT_POLICY_ENABLED. Certificates are selected-key router-signed snapshots, require agent policies and TLOG_ENABLED, and are shown only after signature, signing-key window and expiry checks. Agent-host sealing and attestation are unavailable. Random slugs do not stop correlation through owner-supplied text or publication timing. Updates preserve the slug and replace all public fields and certificate selection. Empty claims remove the certificate. Issuance shares the account five-per-minute certificate limit.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^[A-Za-z0-9_-]{24}$"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "422": {
            "$ref": "#/components/responses/ApiError"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "name",
                  "description"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 280
                  },
                  "homepage": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 500,
                    "description": "HTTP(S) only, without embedded credentials."
                  },
                  "endpoint": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 500,
                    "description": "Optional HTTPS agent endpoint without credentials or fragment. With AGENT_IDENTITY_ENABLED on, the agent-liveness job sends it one GET a day."
                  },
                  "payout_wallet": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$",
                    "description": "Optional USDC wallet on Solana that other agents pay directly (stored lowercase; not the zero address). Payments go wallet to wallet; Trellis never holds the money."
                  },
                  "capabilities": {
                    "type": "array",
                    "maxItems": 16,
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 40
                    },
                    "default": []
                  },
                  "show": {
                    "type": "array",
                    "maxItems": 3,
                    "items": {
                      "type": "string",
                      "enum": [
                        "spending_caps",
                        "ask_first",
                        "kill_switch"
                      ]
                    },
                    "default": []
                  },
                  "certificate_claims": {
                    "type": "array",
                    "maxItems": 16,
                    "uniqueItems": true,
                    "items": {
                      "type": "string",
                      "pattern": "^(requests_at_least|no_denials_days|no_kills_days|active_days_at_least):[1-9][0-9]{0,14}$"
                    },
                    "default": [],
                    "description": "Absence claims limited to 90 days. Verified against this key, never accepted from another certificate."
                  },
                  "show_holder_badge": {
                    "type": "boolean",
                    "default": false,
                    "description": "Opt-in holder badge. When true, and the key belongs to a wallet sign-in account whose wallet holds a tier with a badge, the public card shows trellis.holder_badge with the tier name. Never the wallet address or the balance."
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      },
      "delete": {
        "operationId": "unpublishAgentProfile",
        "tags": [
          "Agent rulebook"
        ],
        "summary": "Delete owned public profile",
        "description": "AGENT_PROFILES_ENABLED defaults false; off returns 404. Public owner-supplied tags are not verified abilities. Only selected boolean rulebook categories are shown, never exact caps, thresholds, private identifiers or reasons. Rulebook categories require AGENT_POLICY_ENABLED. Certificates are selected-key router-signed snapshots, require agent policies and TLOG_ENABLED, and are shown only after signature, signing-key window and expiry checks. Agent-host sealing and attestation are unavailable. Random slugs do not stop correlation through owner-supplied text or publication timing. Deletes the row immediately. Public reader copies and database backups may remain. Republish allocates a new slug.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "const": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "422": {
            "$ref": "#/components/responses/ApiError"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/sealed": {
      "post": {
        "tags": [
          "Agents"
        ],
        "operationId": "postAgentSealed",
        "summary": "Register and verify sealed agent hosting",
        "description": "Requires principal ownership. AGENT_SEALED_ENABLED defaults to false and requires AGENT_POLICY_ENABLED plus a configured dstack verifier. Measured code is not audited code; the router reads ordinary requests in memory. An owner may retain a credential copy; the badge does not prove each subsequent request originated in this VM. GET agent list and /api/v1/agents/me gain an optional sealed status when enabled; success expires after 30 minutes and clears on a failed check.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current registration status. Success requires fresh hardware quote, pinned TLS key, matching key fingerprint and verifier-recovered approved compose hash.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "attested",
                        "agent_image_digest",
                        "compose_hash",
                        "checked_at",
                        "expires_at"
                      ],
                      "properties": {
                        "attested": {
                          "type": "boolean"
                        },
                        "agent_image_digest": {
                          "type": "string"
                        },
                        "compose_hash": {
                          "type": "string"
                        },
                        "checked_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "expires_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "reason": {
                          "type": "string"
                        },
                        "verified_by": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "Attestation failed or a concurrent registration replaced this one; data contains an unattested status or null.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "attested",
                        "agent_image_digest",
                        "compose_hash",
                        "checked_at",
                        "expires_at"
                      ],
                      "properties": {
                        "attested": {
                          "type": "boolean"
                        },
                        "agent_image_digest": {
                          "type": "string"
                        },
                        "compose_hash": {
                          "type": "string"
                        },
                        "checked_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "expires_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "reason": {
                          "type": "string"
                        },
                        "verified_by": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "attestation_url",
                  "agent_image_digest",
                  "compose_hash"
                ],
                "properties": {
                  "attestation_url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2048,
                    "description": "HTTPS /attest URL with no credentials, query or fragment."
                  },
                  "agent_image_digest": {
                    "type": "string",
                    "pattern": "^sha256:[a-f0-9]{64}$"
                  },
                  "compose_hash": {
                    "type": "string",
                    "pattern": "^sha256:[a-f0-9]{64}$"
                  }
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      },
      "delete": {
        "tags": [
          "Agents"
        ],
        "operationId": "deleteAgentSealed",
        "summary": "Remove sealed agent registration",
        "description": "Requires principal ownership. AGENT_SEALED_ENABLED defaults to false and requires AGENT_POLICY_ENABLED plus a configured dstack verifier. Measured code is not audited code; the router reads ordinary requests in memory. An owner may retain a credential copy; the badge does not prove each subsequent request originated in this VM. GET agent list and /api/v1/agents/me gain an optional sealed status when enabled; success expires after 30 minutes and clears on a failed check.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Registration deleted."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/telegram/weekly-summary": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Weekly summary preference.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "opted_in",
                        "last_sent_week"
                      ],
                      "properties": {
                        "opted_in": {
                          "type": "boolean",
                          "default": false
                        },
                        "last_sent_week": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "pattern": "^[0-9]{4}-W[0-9]{2}$"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "This principal has no Telegram link."
          }
        },
        "summary": "Read weekly Telegram summary preference",
        "description": "B120: WEEKLY_SUMMARY_ENABLED defaults false and requires Telegram linking and agent policies. Same principal auth as /api/v1/telegram/link, no-store. Preference belongs to this key’s link; last_sent_week is account-wide and survives unlink. One message/account for the previous ISO week, Monday from 09:00 UTC, hourly checks. Quiet weeks skipped; team administrators see only their team. Existing call charges, approval request statuses at send time, stop events and most-used model; top five agents by spend. Telegram can read names and totals. A crash or ambiguous network failure after sending but before commit may repeat delivery; no catch-up after Monday.",
        "x-launch-surface": "all"
      },
      "put": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Weekly summary preference.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "opted_in",
                        "last_sent_week"
                      ],
                      "properties": {
                        "opted_in": {
                          "type": "boolean",
                          "default": false
                        },
                        "last_sent_week": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "pattern": "^[0-9]{4}-W[0-9]{2}$"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "This principal has no Telegram link."
          }
        },
        "summary": "Choose weekly Telegram summaries",
        "description": "B120: Same auth and flag guards as GET. Updates only this principal’s existing Telegram link; opt-in defaults off. Unlink removes the preference. No-store. Strict boolean body; invalid bodies return 400.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "opted_in"
                ],
                "properties": {
                  "opted_in": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/telegram/link": {
      "get": {
        "summary": "Read Telegram link status",
        "description": "TELEGRAM_LINKING_ENABLED defaults false. Requires AGENT_POLICY_ENABLED and TELEGRAM_BOT_TOKEN. Management or owner/admin principal only, excluding session keys. Returns this key’s link status, Telegram user id and linked timestamp. No-store.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Telegram link status or single-use code."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      },
      "post": {
        "summary": "Issue a Telegram account link code",
        "description": "Same principal permissions as status. Returns code and expires_at. Valid five minutes, single-use, five issuance attempts per account per minute. Replaces the previous account code. Send /link <code> privately to the bot; no API key needed in Telegram. Treat the code as an approval credential. No-store.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Telegram link status or single-use code."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      },
      "delete": {
        "summary": "Unlink Telegram or cancel a pending code",
        "description": "Removes this principal’s Telegram link, its approval delivery markers and the account’s pending code. /unlink works from the bot. Stops account-link delivery; chat keys connected through /key remain separate until /forget. No-store.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Telegram link status or single-use code."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tools/call": {
      "post": {
        "tags": [
          "Paid tools"
        ],
        "operationId": "callPaidTool",
        "summary": "Pay an x402 tool from the key's balance",
        "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at trellis.example yet; every route answers 404 while it is off. See /docs/#paid-tools. The router fetches the resource unpaid and reads its 402 (x402 v1 JSON body with accepts, or the v2 PAYMENT-REQUIRED header). It pays only scheme exact in USDC on Solana. A quote above max_price (the seller's price plus the router's take, TOOLS_TAKE_BPS), above TOOLS_MAX_PRICE_USD or outside the key's rulebook (tools.allow, tools.deny, tools.max_price_per_call, tools.daily_budget, caps, approval) is refused before anything is held or paid. Otherwise it holds price plus take, signs a USDC transfer authorization from the router's buyer wallet to the seller's payTo and retries with X-PAYMENT or PAYMENT-SIGNATURE. A 2xx JSON or plain-text answer of at most 2 MB is charged once and returned as untrusted data with a signed tool.call receipt (COSE_Sign1; check it with POST /api/v1/receipts/verify). Any other answer is not charged: the hold is released once the authorization expires unused, or the call is charged if the seller collected it anyway. then hands the answer to a model and needs tools.pass_to_models in the rulebook.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ToolCallRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The tool's answer, the charge and the tool.call receipt",
            "headers": {
              "X-Trellis-Tool-Call": {
                "schema": {
                  "type": "string"
                },
                "description": "The call id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ToolCall"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "tool_price_above_max, tool_price_above_router_max, tool_delisted or tool_pay_to_mismatch; nothing was charged credits_closing: the key's credits are being closed (POST /api/v1/credits/close is registered on chain); the key is frozen until its refund is paid, error.metadata.closure names the closure, and retrying with the same key does not help.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "422": {
            "description": "tool_not_payable or tool_content_type_refused; nothing was charged",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "502": {
            "description": "tool_seller_failed, tool_response_refused or tool_unreachable; not charged unless the seller later collects the authorization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "tools_buyer_unconfigured or tools_daily_limit; nothing was charged",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "504": {
            "description": "tool_timeout before any payment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tools": {
      "get": {
        "tags": [
          "Paid tools"
        ],
        "operationId": "listPaidTools",
        "summary": "Listed tools with their canary state",
        "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at trellis.example yet; every route answers 404 while it is off. See /docs/#paid-tools. Public. Each listing has a daily paid probe with a known answer; three failures in a row delist it. include_delisted=true also returns delisted listings.",
        "security": [],
        "parameters": [
          {
            "name": "include_delisted",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ToolListing"
                      }
                    },
                    "call": {
                      "type": "string"
                    },
                    "status": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tools/search": {
      "get": {
        "tags": [
          "Paid tools"
        ],
        "operationId": "searchPaidTools",
        "summary": "Search listings, facilitator sellers and the public catalog",
        "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at trellis.example yet; every route answers 404 while it is off. See /docs/#paid-tools. Public. The public catalog (TOOLS_PUBLIC_CATALOG_URL) is fetched through the egress guard and cached; facilitator sellers carry no canary.",
        "security": [],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "public",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matches",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ToolListing"
                      }
                    },
                    "public_catalog": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tools/calls": {
      "get": {
        "tags": [
          "Paid tools"
        ],
        "operationId": "listPaidToolCalls",
        "summary": "This key's paid tool calls",
        "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at trellis.example yet; every route answers 404 while it is off. See /docs/#paid-tools. The 50 newest calls of the calling key, with status (paying, ok, failed, released, charged_after_failure) and receipts.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Calls",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tools/calls/{id}": {
      "get": {
        "tags": [
          "Paid tools"
        ],
        "operationId": "getPaidToolCall",
        "summary": "One paid tool call of this key",
        "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at trellis.example yet; every route answers 404 while it is off. See /docs/#paid-tools.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^tc_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The call"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tools/listings": {
      "post": {
        "tags": [
          "Paid tools"
        ],
        "operationId": "createToolListing",
        "summary": "List an x402 tool with a known-answer canary",
        "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at trellis.example yet; every route answers 404 while it is off. See /docs/#paid-tools. Owner or admin key. The router asks the address unpaid: it must answer 402 with an offer this router can pay. The listing records that offer's payTo and price, and calls are refused if the payTo later changes. skill_id makes it the paid invocation of a Skills Hub skill the account published. 20 listings per account per hour.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ToolListingRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Listed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ToolListing"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "tool_already_listed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "422": {
            "description": "tool_not_payable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tools/listings/{id}": {
      "delete": {
        "tags": [
          "Paid tools"
        ],
        "operationId": "removeToolListing",
        "summary": "Remove a listing",
        "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at trellis.example yet; every route answers 404 while it is off. See /docs/#paid-tools. The listing account only.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^tl_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/tools/{id}": {
      "get": {
        "tags": [
          "Paid tools"
        ],
        "operationId": "getToolListing",
        "summary": "One listing and its last ten canary runs",
        "description": "TOOLS_MARKET_ENABLED defaults to false and is not switched on at trellis.example yet; every route answers 404 while it is off. See /docs/#paid-tools.",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^tl_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The listing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ToolListing"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/identity": {
      "get": {
        "operationId": "agentIdentitySettings",
        "tags": [
          "Agent identity"
        ],
        "summary": "Read identity and reputation choices",
        "description": "Either AGENT_IDENTITY_ENABLED or PAID_FEEDBACK_ENABLED must be on; otherwise 404. Owner or administrator key of the same account; session keys are refused. Returns identity_opt_out (default true only when the key's rulebook allows only the unlinkable lane), reputation_opt_in (default false) and the ERC-8004 registration progress.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Choices and registration",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      },
      "put": {
        "operationId": "setAgentIdentitySettings",
        "tags": [
          "Agent identity"
        ],
        "summary": "Opt out of identity or in to paid reputation",
        "description": "Either flag must be on; otherwise 404. Owner or administrator key of the same account; session keys are refused. Opting out stops the registration file and every identity link the router publishes; a transaction already on chain stays there.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "identity_opt_out": {
                    "type": "boolean"
                  },
                  "reputation_opt_in": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated choices",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/identity/register": {
      "post": {
        "operationId": "registerAgentIdentity",
        "tags": [
          "Agent identity"
        ],
        "summary": "Prepare or queue an agent identity registration",
        "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Owner or administrator key of the same account; session keys are refused. Needs a published profile and no opt-out. Owner mode returns the registration the owner's wallet would submit to an identity registry (no registry is deployed on Solana yet, so it is returned for the owner to keep); registrar mode queues it for the isolated agent-identity worker. The router never sends the owner's transaction.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Registration data (owner mode) or queued (registrar mode)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/identity/confirm": {
      "post": {
        "operationId": "confirmAgentIdentity",
        "tags": [
          "Agent identity"
        ],
        "summary": "Confirm the owner's registration transaction",
        "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Owner or administrator key of the same account; session keys are refused. Reads the transaction receipt and keeps the agent id from the identity registry's Registered event when its agentURI is this key's registration file. 409 while unconfirmed; 422 when it registered something else.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "tx_hash"
                ],
                "properties": {
                  "tx_hash": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{64}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "422": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{key_hash}/track-record": {
      "post": {
        "operationId": "issueAgentTrackRecord",
        "tags": [
          "Agent identity"
        ],
        "summary": "Issue a portable track record",
        "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Also needs TLOG_ENABLED. Owner or administrator key of the same account; session keys are refused. A seven-day certificate signed with the receipt key: count of this key's anchored receipts, total spend, refund rate, dispute rate of agreements its wallet is party to, and a Merkle root over those receipts' anchor leaves. No counterparty or amount per counterparty. Returns the ERC-8004 validation entry it is the payload of. publish:true shows it on the card. Shares the five-per-minute certificate limit.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "publish": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Certificate, validation entry and proof URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "422": {
            "$ref": "#/components/responses/ApiError"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/identity/{id}/registration.json": {
      "get": {
        "operationId": "agentRegistrationFile",
        "tags": [
          "Agent identity"
        ],
        "summary": "Read an agent registration file",
        "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public. type https://eips.ethereum.org/EIPS/eip-8004#registration-v1, name, description, services (web, trellis-card, the agent endpoint, trellis-reputation when opted in, trellis-receipt-keys), active, registrations and supportedTrust. 404 when the key opted out.",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Registration file",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/track-records/verify": {
      "post": {
        "operationId": "verifyAgentTrackRecord",
        "tags": [
          "Agent identity"
        ],
        "summary": "Check a track-record certificate",
        "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public. Checks the signature against the published receipt keys, the seven-day window and internal consistency; not the router's underlying observations.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{valid, notice}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/track-records/{id}": {
      "get": {
        "operationId": "agentTrackRecord",
        "tags": [
          "Agent identity"
        ],
        "summary": "Read a track record and its validation entry",
        "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public. The requestURI of the validation entry. validation carries request_hash (sha256 of the canonical payload JSON), response 100, response_hash (sha256 of the canonical signed certificate), tag trellis-track-record, and registry data only when a validation registry, a validator and the agent's identity id are all known. No validation registry exists on Solana yet.",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^tr_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Certificate, validity and validation entry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/track-records/{id}/proof": {
      "get": {
        "operationId": "agentTrackRecordProof",
        "tags": [
          "Agent identity"
        ],
        "summary": "Prove one counted receipt",
        "description": "AGENT_IDENTITY_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public. The leaf at index (ascending order), its path to the certificate's Merkle root, and its path to the hourly anchor root. 410 when the router no longer holds every counted receipt.",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^tr_[0-9a-f]{24}$"
            }
          },
          {
            "name": "index",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Leaf, proof, root and anchor proof",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "410": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{slug}/reputation": {
      "get": {
        "operationId": "agentReputation",
        "tags": [
          "Agent identity"
        ],
        "summary": "Read paid-feedback reputation",
        "description": "PAID_FEEDBACK_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public. opted_in false until the owner opts in. Otherwise the weighted score (0 to 100), feedback_count, weight_usd, by_kind, half_life_days and up to 20 recent entries with a payment band and day. Weight is the amount paid, halving every PAID_FEEDBACK_HALF_LIFE_DAYS after the payment. Reviewers are never shown.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reputation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{slug}/feedback": {
      "post": {
        "operationId": "giveAgentFeedback",
        "tags": [
          "Agent identity"
        ],
        "summary": "Give feedback backed by a paid receipt",
        "description": "PAID_FEEDBACK_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Any key of the paying account. No receipt, no feedback: the router's record of receipt_id must name the caller's account as payer and this agent as payee or agent served (model.call: a call answered by a network host the agent's account operates; agreement.release: a released milestone paid to the agent's wallet; other kinds may register). Refused: unknown or unpaid receipts, unlinkable or blind payments, another payer's receipt, a receipt already used, and any account that controls the agent. Thirty per minute per account. For an agent with a registered identity, erc8004 carries the optional feedback entry the reviewer's own wallet would submit to a reputation registry (none is deployed on Solana yet).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{24}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "receipt_id",
                  "score"
                ],
                "properties": {
                  "receipt_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "receipt_kind": {
                    "type": "string",
                    "description": "model.call, agreement.release or another registered kind; omitted means every known kind is tried."
                  },
                  "score": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "tag1": {
                    "type": "string",
                    "maxLength": 32,
                    "pattern": "^[A-Za-z0-9 ._:-]+$"
                  },
                  "tag2": {
                    "type": "string",
                    "maxLength": 32,
                    "pattern": "^[A-Za-z0-9 ._:-]+$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Recorded entry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "422": {
            "$ref": "#/components/responses/ApiError"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/{slug}/feedback/{id}": {
      "delete": {
        "operationId": "withdrawAgentFeedback",
        "tags": [
          "Agent identity"
        ],
        "summary": "Withdraw one's own feedback",
        "description": "PAID_FEEDBACK_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Only a key of the reviewing account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{24}$"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^fb_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Withdrawn",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/agents/feedback/{id}": {
      "get": {
        "operationId": "agentFeedbackEntry",
        "tags": [
          "Agent identity"
        ],
        "summary": "Read one public feedback entry",
        "description": "PAID_FEEDBACK_ENABLED defaults false and needs AGENT_PROFILES_ENABLED; off returns 404. Public; the feedbackURI of the optional ERC-8004 entry. Score, tags, receipt kind, payment band and day; never the reviewer, the receipt id or the exact amount.",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^fb_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/escrow/deposits": {
      "get": {
        "tags": [
          "Credits"
        ],
        "summary": "Alias of GET /api/v1/credits/deposits",
        "description": "Active bearer key required. Account deposit progress allows owner/admin/member/viewer roles and excludes session keys; deposits are scoped to the key's hash in trellis_credits. Stages: submitted, confirmed, finalized, credited. Nullable expected_final_at is an estimate from live slot progress, never proof of finality. No-store.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Deposit stages with an optional timing estimate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deposits": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "expected_final_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true,
                                "description": "Approximate ISO finality estimate from live block progress; null when unavailable. Not a deadline."
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "deprecated": true,
        "x-launch-surface": "all"
      }
    },
    "/api/v1/credits/deposits": {
      "get": {
        "tags": [
          "Credits"
        ],
        "summary": "Read deposit progress and approximate finality time",
        "description": "Active bearer key required. Account deposit progress allows owner/admin/member/viewer roles and excludes session keys; deposits are scoped to the key's hash in trellis_credits. Stages: submitted, confirmed, finalized, credited. Nullable expected_final_at is an estimate from live slot progress, never proof of finality. No-store.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Deposit stages with an optional timing estimate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deposits": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "expected_final_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true,
                                "description": "Approximate ISO finality estimate from live block progress; null when unavailable. Not a deadline."
                              },
                              "tx_hash": {
                                "type": "string",
                                "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$",
                                "description": "The base58 Solana transaction signature (64 bytes), exactly as submitted."
                              },
                              "lane": {
                                "type": "string",
                                "enum": [
                                  "usdc",
                                  "escrow"
                                ],
                                "description": "usdc: a deposit into the trellis_credits vault."
                              },
                              "stage": {
                                "type": "string",
                                "enum": [
                                  "submitted",
                                  "confirmed",
                                  "finalized",
                                  "credited",
                                  "failed"
                                ]
                              },
                              "amount_usdc": {
                                "type": "string",
                                "description": "Exact USDC amount once the transfer is read; absent while submitted."
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-launch-surface": "core"
      },
      "post": {
        "tags": [
          "Credits"
        ],
        "operationId": "watchDeposit",
        "summary": "Watch a submitted deposit transaction",
        "description": "Tell the indexer about a deposit transaction the wallet just sent so its progress shows at once (the indexer finds vault deposits on its own too). Same roles as GET. At most 20 submitted transactions are watched per account (429 rate_limit beyond that).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tx_hash": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$",
                    "description": "Base58 Solana transaction signature."
                  },
                  "lane": {
                    "type": "string",
                    "enum": [
                      "usdc",
                      "escrow"
                    ],
                    "description": "usdc for a trellis_credits deposit."
                  }
                },
                "required": [
                  "tx_hash",
                  "lane"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Now watched",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "tx_hash": {
                          "type": "string"
                        },
                        "stage": {
                          "type": "string",
                          "const": "submitted"
                        }
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/account/runway": {
      "get": {
        "tags": [
          "Keys"
        ],
        "summary": "Estimate balance runway",
        "description": "Same active-key authentication and visibility as credits: account-scoped keys see the account; sessions see remaining budget and their own charges. Inference-only keys are forbidden. Settled balance divided by seven-day charged usage/tool spend per day, rounded down; null without spending. Refunds, token purchases and holds are excluded.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "balance_usd",
                    "spend_7d_usd",
                    "per_day_usd",
                    "days_left"
                  ],
                  "properties": {
                    "balance_usd": {
                      "type": "number"
                    },
                    "spend_7d_usd": {
                      "type": "number"
                    },
                    "per_day_usd": {
                      "type": "number"
                    },
                    "days_left": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "operationId": "getAccountRunway",
        "x-launch-surface": "all"
      }
    },
    "/api/v1/account/low-balance": {
      "get": {
        "tags": [
          "Keys"
        ],
        "summary": "Read balance alert setting",
        "description": "Owner keys only; no session or inference-only keys. enabled reports LOW_BALANCE_ALERTS_ENABLED (default false).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "low_balance_usd",
                    "enabled"
                  ],
                  "properties": {
                    "low_balance_usd": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "minimum": 0,
                      "maximum": 1000000
                    },
                    "enabled": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "operationId": "getLowBalanceSetting",
        "x-launch-surface": "core"
      },
      "patch": {
        "tags": [
          "Keys"
        ],
        "summary": "Set balance alert threshold",
        "description": "Owner keys only; no session or inference-only keys. 403 while LOW_BALANCE_ALERTS_ENABLED is false. Null clears the setting. A changed threshold starts a new crossing check; an unchanged threshold preserves the claim. Worker checks every five minutes, records an inbox low_balance item, and attempts linked Telegram delivery once per crossing. Re-arms strictly above the threshold.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; Cache-Control: no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "low_balance_usd",
                    "enabled"
                  ],
                  "properties": {
                    "low_balance_usd": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "minimum": 0,
                      "maximum": 1000000
                    },
                    "enabled": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "low_balance_usd"
                ],
                "properties": {
                  "low_balance_usd": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0,
                    "maximum": 1000000
                  }
                }
              }
            }
          }
        },
        "operationId": "setLowBalanceSetting",
        "x-launch-surface": "core"
      }
    },
    "/api/v1/credits": {
      "get": {
        "tags": [
          "Credits"
        ],
        "operationId": "getCredits",
        "summary": "Read the balance and how to fund this key",
        "description": "The account's deposited total, usage, balance, held amount and available credits in USDC, plus deposit instructions (program, vault, key hash) and the deposit confirmation timing. A session key sees only its own budget. Credits never expire into a withdrawal: they are spend-only.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Balance and deposit instructions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "total_credits": {
                          "type": "number"
                        },
                        "total_usage": {
                          "type": "number"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "held": {
                          "type": "number"
                        },
                        "available": {
                          "type": "number"
                        },
                        "currency": {
                          "type": "string",
                          "const": "USDC"
                        },
                        "deposit": {
                          "$ref": "#/components/schemas/DepositInfo"
                        }
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/credits/deposit-tx": {
      "post": {
        "tags": [
          "Credits"
        ],
        "operationId": "createDepositTransaction",
        "summary": "Build an unsigned deposit transaction for a wallet",
        "description": "Returns an unsigned trellis_credits::deposit transaction (Solana Pay transaction-request shape) that moves amount USDC from the payer's wallet into the program vault for this key; the wallet signs and sends it, and the balance is credited once it is finalized (usually seconds). The answer also says where what is left of this deposit returns if the key's credits are ever closed (refund_to: the token account it is paid from). Refused above the per-key cap (400 deposit_refused). 503 chain_unavailable when the Solana RPC cannot be reached. By default (`register_owner`) a key with no owner wallet gets the paying wallet registered as its owner in the same transaction; the response says so under `data.owner`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "string",
                    "pattern": "^\\d+(\\.\\d{1,6})?$",
                    "description": "USDC amount with up to 6 decimals.",
                    "example": "12.50"
                  },
                  "payer": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
                    "description": "The depositing wallet (base58).",
                    "example": "CZ8YUVdk7znjrUmnb5n7kgySk9yRAsQDYmyCxzfSky9t"
                  },
                  "register_owner": {
                    "type": "boolean",
                    "default": true,
                    "description": "When the key has no owner wallet yet, the returned transaction also registers `payer` as the key's owner (set_key_authority, signed by the key): the transaction then carries the key's signature and the wallet adds its own with a partial sign. `false` returns the deposit alone."
                  }
                },
                "required": [
                  "amount",
                  "payer"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The transaction to sign",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DepositTransaction"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "description": "chain_unavailable: the Solana RPC is unavailable; try again shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/credits/close": {
      "post": {
        "tags": [
          "Credits"
        ],
        "operationId": "closeCredits",
        "summary": "Close the key's credits: what is left returns to the wallets that paid in",
        "description": "The only customer-initiated outflow (docs §5.1). A closure refund can only return to the wallets that deposited to the key: each gets at most what it put in, to the token account it named on chain (by default the one it paid from). The key can ask for a closure and take it back; it cannot choose or change a destination, so holding an API key is not enough to move a balance anywhere new. The request therefore carries only payer; one that carries refund_to is refused with 400 refund_destination_fixed. The answer lists who will be paid in refunds. Must be called with the key itself (not a sub-key; 403 forbidden otherwise). trellis_credits::close_account is authorised by the key itself: its own ed25519 keypair (the one whose public key hashes to the key hash) must sign, and no wallet can close a key, whoever deposited to it. The request carries the key, so the router signs the transaction as the key (it stores neither the key nor its keypair) and returns it in transaction with signed_by_key true. payer (any wallet) adds its signature as fee payer, pays the network fee and a small rent, and sends it before expires_at_block_height; nothing else in the transaction may change. The transaction is a single close_account instruction. Once the closure is on chain the key is frozen: anything that would spend answers 409 credits_closing until the refund is paid or the closure is cancelled (POST /api/v1/credits/close/cancel). The settlement service pays the refund after the program's delay (72 hours at launch), once no call is in progress, and a sanctions screen of the account being paid: what the key had not spent, never more than its own deposits cover. Never on demand, never sent by the router. It is not paid while the key is disabled (see POST /api/v1/credits/close/release). 201 for a new closure, 200 when one is already open (transaction null when it is already registered on chain). 400 nothing_to_close when the key has no on-chain credits or is already closed. With as_owner: true and payer = the key's registered owner wallet (see POST /api/v1/credits/owner-tx) the answer is an unsigned close_account_by_owner transaction for that wallet (signed_by_key false, requested_by owner): a closure asked for this way cannot be cancelled with the API key. The refund is split over the depositors largest remaining share first. Deposits are at least 1 USDC.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payer": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
                    "description": "The wallet that pays the transaction fee and a small rent and signs last (base58). Any wallet. It is not the destination of the refund.",
                    "example": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc"
                  },
                  "as_owner": {
                    "type": "boolean",
                    "description": "Build the transaction for the key's registered owner wallet (payer must be that wallet) instead of signing it as the key."
                  }
                },
                "required": [
                  "payer"
                ],
                "not": {
                  "required": [
                    "refund_to"
                  ]
                },
                "description": "Only payer. A closure names no destination: a body that carries refund_to is refused with 400 refund_destination_fixed."
              },
              "example": {
                "payer": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Closure queued: the transaction to finish with the payer's signature, and who will be paid back",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreditClosureRequest"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "close_fixture",
                    "status": "queued",
                    "payer": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                    "authority": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                    "payable_at": "2026-09-24T14:13:20.000Z",
                    "transaction": "<base64>",
                    "message": "Trellis credits: close key 11888fa4… and queue its refund to the wallets that funded it",
                    "accounts": {
                      "refundRequest": "Byn9yxiKaw8rNjraDJaZJsuyzk3ymgutdj7wiWXm7VDE"
                    },
                    "expires_at_block_height": 314159265,
                    "signed_by_key": true,
                    "refunds": [
                      {
                        "depositor": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                        "refund_to": "2ynX92NNnMitvdyFgkE1PW4Wa7nTirUHuMEapMS82ZWJ",
                        "deposited_units": "25000000",
                        "refunded_units": "0"
                      },
                      {
                        "depositor": "JAsM8j57YVbWu3hg8ah2p27JMb82HnyRhPLsNLbSPdXx",
                        "refund_to": "2v1RgDhkNQwxXsCyzUN3TLW9Uq4PXXByhbkverZxjDvx",
                        "deposited_units": "5000000",
                        "refunded_units": "0"
                      }
                    ],
                    "note": "The transaction already carries the key's signature. Sign it with the payer wallet (any wallet; it pays the fee and a small rent) and send it before the blockhash expires. The refund is not sent to an address of your choosing: it returns to the wallets that deposited to this key (see refunds), after the dispute window and a sanctions check, never on demand. The key stops serving new calls once the closure is on chain. Until anything is paid you can take it back with POST /api/v1/credits/close/cancel."
                  }
                }
              }
            }
          },
          "200": {
            "description": "An open closure already exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreditClosureRequest"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "close_fixture",
                    "status": "registered",
                    "payer": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                    "authority": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                    "payable_at": "2026-09-24T14:13:20.000Z",
                    "transaction": null,
                    "refunds": [
                      {
                        "depositor": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                        "refund_to": "2ynX92NNnMitvdyFgkE1PW4Wa7nTirUHuMEapMS82ZWJ",
                        "deposited_units": "25000000",
                        "refunded_units": "0"
                      },
                      {
                        "depositor": "JAsM8j57YVbWu3hg8ah2p27JMb82HnyRhPLsNLbSPdXx",
                        "refund_to": "2v1RgDhkNQwxXsCyzUN3TLW9Uq4PXXByhbkverZxjDvx",
                        "deposited_units": "5000000",
                        "refunded_units": "0"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "description": "chain_unavailable: the Solana RPC is unavailable; try again shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      },
      "get": {
        "tags": [
          "Credits"
        ],
        "operationId": "listCreditClosures",
        "summary": "List this key's closure requests",
        "description": "The last ten closures of this key, newest first: their status, who is paid back (refunds: one payment per wallet that deposited), the wallets paid so far, why an open closure is waiting (reason; key_disabled means it is held until an owner or admin releases it), and the transactions that registered, paid or cancelled it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Closures",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CreditClosure"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "close_fixture_4",
                      "status": "registered",
                      "reason": "key_disabled",
                      "refund_to": null,
                      "refunds": [],
                      "amount_units": null,
                      "requested_at": "2026-09-21T14:13:20.000Z",
                      "payable_at": "2026-09-24T14:13:20.000Z",
                      "paid_at": null,
                      "register_tx": "2m7UJYQWS3A8Dku2mc2A85jMiiGaypFLNcmC3KBoGLk7jW4A8xo9HA6Wdjd3yuWe8vzQtC5EGPUpbdgkLSYVyfqi",
                      "pay_tx": null,
                      "cancel_tx": null,
                      "released_at": null
                    },
                    {
                      "id": "close_fixture_3",
                      "status": "registered",
                      "reason": "refund_rate_limited",
                      "refund_to": null,
                      "refunds": [
                        {
                          "depositor": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                          "refund_to": "2ynX92NNnMitvdyFgkE1PW4Wa7nTirUHuMEapMS82ZWJ",
                          "owner": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                          "amount_units": "20000000",
                          "status": "paid",
                          "reason": null,
                          "tx": "3ypQdE37MwKSaX2Kh7SQve4eneZ17U8AXG4eyNrfkE4hxJVjjHHjfkqomjmeQaXt8remx4sskvxSgVbPL2QoakbS"
                        },
                        {
                          "depositor": "JAsM8j57YVbWu3hg8ah2p27JMb82HnyRhPLsNLbSPdXx",
                          "refund_to": "2v1RgDhkNQwxXsCyzUN3TLW9Uq4PXXByhbkverZxjDvx",
                          "owner": "BoVyoBax4CPDvP3omDuWdsiLhqQKveKUfzfwE6ujhqnW",
                          "amount_units": "4000000",
                          "status": "planned",
                          "reason": "refund_rate_limited",
                          "tx": null
                        }
                      ],
                      "amount_units": "24000000",
                      "requested_at": "2026-09-21T14:13:20.000Z",
                      "payable_at": "2026-09-24T14:13:20.000Z",
                      "paid_at": null,
                      "register_tx": "qxTtRVcrjNF7DH5pdfKZ7aG6uCQ7CS9TtPjJtUGtBot1EehbVMRSZxNSEhEv8od4a26M6KM3U4uAvza2w5jXXqS",
                      "pay_tx": "3ypQdE37MwKSaX2Kh7SQve4eneZ17U8AXG4eyNrfkE4hxJVjjHHjfkqomjmeQaXt8remx4sskvxSgVbPL2QoakbS",
                      "cancel_tx": null,
                      "released_at": "2026-09-24T15:13:20.000Z"
                    },
                    {
                      "id": "close_fixture_2",
                      "status": "cancelled",
                      "reason": "cancelled_on_chain",
                      "refund_to": null,
                      "refunds": [],
                      "amount_units": null,
                      "requested_at": "2026-09-21T14:13:20.000Z",
                      "payable_at": "2026-09-24T14:13:20.000Z",
                      "paid_at": null,
                      "register_tx": "KGnx2Djtt5Ec7LJzpHPyjLqmiFFzNEAVsS8AiX9Htc13i6WYsC6nRJXHNFdkv7BqmAhABpr8rgtEp5BDwKJRGs2",
                      "pay_tx": null,
                      "cancel_tx": "4fWwQuHGNuPRCwzvTv75zQAWDpoPvJnpqQePfWABrp24P3VzyJrcgh6hFAk8o3j33CDYsyadihm7u7yYTkRXPF13",
                      "released_at": null
                    },
                    {
                      "id": "close_fixture_1",
                      "status": "paid",
                      "reason": null,
                      "refund_to": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc,BoVyoBax4CPDvP3omDuWdsiLhqQKveKUfzfwE6ujhqnW",
                      "refunds": [
                        {
                          "depositor": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                          "refund_to": "2ynX92NNnMitvdyFgkE1PW4Wa7nTirUHuMEapMS82ZWJ",
                          "owner": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                          "amount_units": "20000000",
                          "status": "paid",
                          "reason": null,
                          "tx": "51EnCfBCXmvN9yS2mx2gzbn6AE5AqmZ8wWobgSiu7nhG3zjmWVsP4uC95AzFosq7JLb441MBKfRLJHi5KvWTbWWH"
                        },
                        {
                          "depositor": "JAsM8j57YVbWu3hg8ah2p27JMb82HnyRhPLsNLbSPdXx",
                          "refund_to": "2v1RgDhkNQwxXsCyzUN3TLW9Uq4PXXByhbkverZxjDvx",
                          "owner": "BoVyoBax4CPDvP3omDuWdsiLhqQKveKUfzfwE6ujhqnW",
                          "amount_units": "4000000",
                          "status": "paid",
                          "reason": null,
                          "tx": "3ckgXppvXonZEhH9Yh91Ph9L6tQsudeUwToaYL1VaSjzixmadkMSVdg9Fn11gq7WxuTM5CQUy8fv7Z7sADoNqoiq"
                        }
                      ],
                      "amount_units": "24000000",
                      "requested_at": "2026-09-21T14:13:20.000Z",
                      "payable_at": "2026-09-24T14:13:20.000Z",
                      "paid_at": "2026-09-24T15:13:20.000Z",
                      "register_tx": "T6krRexkFyU5BdndSEC5c1VY5aBqmhhiFKZXUfEFUPoMML6QdxEgfqXeWcXARSbpQ9KoHVquQJasmFqUx22aPHq",
                      "pay_tx": "3ckgXppvXonZEhH9Yh91Ph9L6tQsudeUwToaYL1VaSjzixmadkMSVdg9Fn11gq7WxuTM5CQUy8fv7Z7sADoNqoiq",
                      "cancel_tx": null,
                      "released_at": null
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/credits/close/cancel": {
      "post": {
        "tags": [
          "Credits"
        ],
        "operationId": "cancelCreditClosure",
        "summary": "Take a closure back while nothing has been paid",
        "description": "Returns a trellis_credits::cancel_close transaction already signed by the key (called with the key itself; 403 forbidden otherwise) for payer, any wallet, to sign as fee payer and send. Once it lands the key is open again with its balance and serves calls as before. 400 nothing_to_cancel when no closure of this key is on chain (a closure that was prepared and never sent needs no cancelling). 409 refund_in_progress once the closure has been paid in part or in full: it can no longer be cancelled, and retrying does not help. Who may cancel (security review round 3): whoever asked for the closure, or the key's registered owner wallet (send as_owner: true with payer = that wallet; the transaction is then unsigned, signed_by_key false). The key itself only for a closure the key asked for, and once in 60 days: 409 cancel_cooldown (error.metadata.retry_at) after that, 403 not_requester for a closure the owner wallet asked for, 403 not_owner when as_owner is sent with another wallet. A wallet that only deposited to the key cannot cancel.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payer": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
                    "description": "The wallet that pays the transaction fee and a small rent and signs last (base58). Any wallet. It is not the destination of the refund.",
                    "example": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc"
                  },
                  "as_owner": {
                    "type": "boolean",
                    "description": "Build the transaction for the key's registered owner wallet (payer must be that wallet) instead of signing it as the key."
                  }
                },
                "required": [
                  "payer"
                ]
              },
              "example": {
                "payer": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The cancellation to finish with the payer's signature",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreditClosureCancel"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "transaction": "<base64>",
                    "message": "Trellis credits: take back the closure of key 11888fa4…",
                    "accounts": {
                      "refundRequest": "Byn9yxiKaw8rNjraDJaZJsuyzk3ymgutdj7wiWXm7VDE"
                    },
                    "payer": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                    "expires_at_block_height": 314159265,
                    "signed_by_key": true,
                    "note": "Sign with the payer wallet and send before the blockhash expires. Once it lands the key is open again with its balance and serves calls as before."
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden",
            "description": " Also not_requester (the closure was asked for by the owner wallet) and not_owner (as_owner with a wallet that is not the registered owner)."
          },
          "409": {
            "description": "refund_in_progress: the closure has already been paid in part or in full and can no longer be cancelled. Not a transient error. Also cancel_cooldown: the key has already taken a closure back in the last 60 days (error.metadata.retry_at).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "example": {
                  "error": {
                    "code": 409,
                    "message": "This closure has already been paid in part or in full and can no longer be cancelled.",
                    "type": "refund_in_progress"
                  }
                }
              }
            }
          },
          "503": {
            "description": "chain_unavailable: the Solana RPC is unavailable; try again shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/credits/close/release": {
      "post": {
        "tags": [
          "Credits"
        ],
        "operationId": "releaseCreditClosure",
        "summary": "Release a closure that is held because its key was disabled",
        "description": "A closure is not paid while its key is disabled: disabling or revoking a key (DELETE /api/v1/keys/{hash}) stops a closure it started, which is what protects a balance when a key has leaked. An owner or admin of the account calls this, with their own key, to let the closure go ahead on purpose. key is the hash of the key whose credits are being closed (Key.hash), never the key itself. The refund still only returns to the wallets that deposited to that key. 404 not_found when that key has no open closure.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{64}$",
                    "description": "The key's hash (Key.hash), as GET /api/v1/keys lists it."
                  }
                },
                "required": [
                  "key"
                ]
              },
              "example": {
                "key": "be9554a9d1eac080eb504f995cc2356755a82a7cb0601482df6e0fb9e919b5bd"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The closures released",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CreditClosureRelease"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "close_fixture",
                      "status": "registered",
                      "released": true,
                      "payable_at": "2026-09-24T14:13:20.000Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/credits/refund-destination-tx": {
      "post": {
        "tags": [
          "Credits"
        ],
        "operationId": "createRefundDestinationTransaction",
        "summary": "Build the transaction with which a depositor moves its own refund destination",
        "description": "Where a depositor's refunds from this key go is that depositor's decision, made with its own wallet signature. Returns an UNSIGNED trellis_credits::set_refund_destination transaction for depositor to sign and send: from then on that wallet's share of a closure refund is paid to refund_to's USDC associated token account (created if needed, paid by the depositor). The API key has no say in it and is not part of the transaction; this route only builds it. It moves no money now. 404 not_found when that wallet has not deposited to this key.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "depositor": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
                    "description": "The wallet that deposited to this key and will sign (base58).",
                    "example": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc"
                  },
                  "refund_to": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
                    "description": "The wallet that should receive that depositor's refunds (base58).",
                    "example": "BoVyoBax4CPDvP3omDuWdsiLhqQKveKUfzfwE6ujhqnW"
                  }
                },
                "required": [
                  "depositor",
                  "refund_to"
                ]
              },
              "example": {
                "depositor": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                "refund_to": "BoVyoBax4CPDvP3omDuWdsiLhqQKveKUfzfwE6ujhqnW"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The transaction for the depositor's wallet to sign",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RefundDestinationTransaction"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "transaction": "<base64>",
                    "message": "Trellis credits: send my refunds from key 11888fa4… to BoVyoB…",
                    "accounts": {
                      "share": "CC3DdPsMibJqbYbSkKSYGqErTpPGtKea3e9vWCNtkEmX",
                      "refundToToken": "2v1RgDhkNQwxXsCyzUN3TLW9Uq4PXXByhbkverZxjDvx"
                    },
                    "depositor": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                    "refund_to": "BoVyoBax4CPDvP3omDuWdsiLhqQKveKUfzfwE6ujhqnW",
                    "current_refund_to": "2ynX92NNnMitvdyFgkE1PW4Wa7nTirUHuMEapMS82ZWJ",
                    "expires_at_block_height": 314159265,
                    "note": "Only the depositor's own wallet can sign this. It changes where that wallet's deposits to this key are refunded; it moves nothing now."
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "description": "chain_unavailable: the Solana RPC is unavailable; try again shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/credits/withdrawal-proof": {
      "post": {
        "tags": [
          "Credits"
        ],
        "operationId": "removed_withdrawalProof",
        "summary": "Removed: credits are spend-only",
        "deprecated": true,
        "x-removed": true,
        "description": "This self-custodial withdrawal route of the earlier router no longer exists on Trellis: credits are spend-only (docs §5.1). Every method answers 410 gone.",
        "security": [
          {}
        ],
        "responses": {
          "410": {
            "description": "gone: Trellis credits are spend-only; deposits are not withdrawn. Use POST /api/v1/credits/close to close the account and request a refund of the unspent balance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/credits/withdraw-request": {
      "post": {
        "tags": [
          "Credits"
        ],
        "operationId": "removed_withdrawRequest",
        "summary": "Removed: credits are spend-only",
        "deprecated": true,
        "x-removed": true,
        "description": "This self-custodial withdrawal route of the earlier router no longer exists on Trellis: credits are spend-only (docs §5.1). Every method answers 410 gone.",
        "security": [
          {}
        ],
        "responses": {
          "410": {
            "description": "gone: Trellis credits are spend-only; deposits are not withdrawn. Use POST /api/v1/credits/close to close the account and request a refund of the unspent balance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/credits/withdraw-cancel": {
      "post": {
        "tags": [
          "Credits"
        ],
        "operationId": "removed_withdrawCancel",
        "summary": "Removed: credits are spend-only",
        "deprecated": true,
        "x-removed": true,
        "description": "This self-custodial withdrawal route of the earlier router no longer exists on Trellis: credits are spend-only (docs §5.1). Every method answers 410 gone.",
        "security": [
          {}
        ],
        "responses": {
          "410": {
            "description": "gone: Trellis credits are spend-only; deposits are not withdrawn. Use POST /api/v1/credits/close to close the account and request a refund of the unspent balance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/auth/wallet/challenge": {
      "post": {
        "tags": [
          "Wallet sign-in"
        ],
        "operationId": "walletChallenge",
        "summary": "Get a single-use wallet sign-in challenge",
        "description": "No key. Returns a single-use nonce and the exact message the wallet signs: a Sign-In-With-Solana text (the EIP-4361 layout) that names this router's domain (the host of its public URL) on its first line, then the wallet's address, a statement, and URI, Version, Chain ID (the network, CAIP-2), Nonce, Issued At and Expiration Time. A wallet shows the domain, so a challenge relayed by another site is visibly not that site's: a client should check that domain is the router it is talking to and that the message names its own address before signing. Rate limited per address (429). The challenge expires after five minutes and is consumed by POST /api/v1/auth/wallet.",
        "security": [
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "address": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
                    "description": "Base58 Solana address (32-byte ed25519 public key).",
                    "example": "CZ8YUVdk7znjrUmnb5n7kgySk9yRAsQDYmyCxzfSky9t"
                  }
                },
                "required": [
                  "address"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The challenge",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WalletSignInChallenge"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/auth/wallet": {
      "post": {
        "tags": [
          "Wallet sign-in"
        ],
        "operationId": "walletSignIn",
        "summary": "Sign in with a wallet and get a management key",
        "description": "No key. The wallet signs the exact UTF-8 bytes of the message returned with the challenge (POST /api/v1/auth/wallet/challenge) with its ed25519 key (solana:signMessage) and sends the 64-byte signature base58. The router verifies the signature over the message it issued and stored with the challenge, and over nothing else: a signature over any other text does not sign in, including the earlier client-built form \"trellis:wallet:v1\\n<nonce>\\n<timestamp>\", which named no site and is retired. The router checks that the nonce exists, is unexpired, was issued for this address and this router and is used once (consumed in the same transaction that issues the key). message may be sent back; when present it must equal the issued one. Issues a management key for the wallet's account w_<address>; the secret is returned once. A wallet keeps at most ten live sign-in keys: issuing another disables the oldest. 401 invalid_wallet_auth for any failure.",
        "security": [
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "address": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
                    "example": "CZ8YUVdk7znjrUmnb5n7kgySk9yRAsQDYmyCxzfSky9t"
                  },
                  "nonce": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{48}$"
                  },
                  "timestamp": {
                    "type": "integer",
                    "deprecated": true,
                    "description": "Sent by v1 clients. Not read: the validity is part of the signed message."
                  },
                  "signature": {
                    "type": "string",
                    "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$",
                    "description": "Base58 ed25519 signature (64 bytes) over the UTF-8 bytes of the challenge's message.",
                    "example": "MxNopkq48oapj97ZKWzUFbaz7NWxMLTePUJ6ssX1JmxKxxrry6tcikFoQFL3RkUAVbaSbtSxvPWRRciXG4dt3qK"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "message": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Optional: the message that was signed. When sent it must be exactly the one issued with the challenge; it is never verified in its place."
                  }
                },
                "required": [
                  "address",
                  "nonce",
                  "signature"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Key"
                    },
                    "key": {
                      "type": "string",
                      "description": "Secret returned only on creation."
                    }
                  },
                  "required": [
                    "data",
                    "key"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/facilitator/supported": {
      "get": {
        "tags": [
          "Facilitator"
        ],
        "operationId": "facilitatorSupported",
        "summary": "Schemes and networks this facilitator settles",
        "description": "Public. Each (x402Version, scheme, network) the facilitator settles, with the fee payer (relay) address and, for tab, the program id and the pre-audit cap. kinds is empty while the facilitator is switched off. No-store.",
        "security": [
          {}
        ],
        "responses": {
          "200": {
            "description": "Supported kinds",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FacilitatorSupported"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/facilitator/verify": {
      "post": {
        "tags": [
          "Facilitator"
        ],
        "operationId": "facilitatorVerify",
        "summary": "Verify a payment without moving funds",
        "description": "Public. exact: decodes the transaction, checks fee payer, instructions (one TransferChecked of the USDC asset to payTo's associated token account, decimals 6), amount >= the requirement, the payer's signature and that the blockhash is still valid. tab: parses the voucher, reads the Tab account, checks payee, mint, expiry, cap, sequence and the session-key signature, and that cumulative_used covers the amount; when payload.transaction is present it must be exactly the payee-signed close for that voucher. Answers 200 with isValid false and a reason rather than an error; 400 invalid_request for a malformed body; 503 facilitator_disabled when switched off.",
        "security": [
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FacilitatorPaymentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FacilitatorVerifyResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "description": "facilitator_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/facilitator/settle": {
      "post": {
        "tags": [
          "Facilitator"
        ],
        "operationId": "facilitatorSettle",
        "summary": "Co-sign as fee payer and submit",
        "description": "Public. Verifies like /verify, then claims the payment by (payer, nonce) so a replay settles once and gets the same answer (409 payment_already_claimed while another settlement of the same payment is in flight; a settled replay answers the original transaction), co-signs the transaction with the relay key as fee payer and submits it, waiting for confirmation. exact: USDC moves payer to payTo. tab: the payee-signed close moves escrow to the payee and refunds the remainder to the payer; payload.transaction is required (tab_close_transaction_required). The SOL fee is recovered inside the settlement amount when a SOL price is configured (sponsorship, docs §5.2); the facilitator fee (0 during the waiver) is a second transfer. 400 with success false for a rejected payment or a failed submission (settle_transaction_failed, invalid_exact_svm_payload_transaction_blockhash_expired, invalid_tab_close_blockhash_expired).",
        "security": [
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FacilitatorPaymentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FacilitatorSettleResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "default": {
            "description": "A rejected payment or a failed submission answers 400 with this body: success false and errorReason naming why (a malformed request body is the ApiError 400 invalid_request instead).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FacilitatorSettleResponse"
                }
              }
            }
          },
          "409": {
            "description": "payment_already_claimed or settle_transaction_failed for an earlier attempt of the same payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FacilitatorSettleResponse"
                }
              }
            }
          },
          "503": {
            "description": "facilitator_disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/hvx": {
      "get": {
        "tags": [
          "HVX"
        ],
        "operationId": "getHvx",
        "summary": "Read the Harvest Index",
        "description": "Public, no key, no body. The latest completed hour per grade (G-S small, G-M medium, G-L large open models served on the sealed lane) and the 24-hour series. Hours are computed from paid, completed receipts with wash trading removed (self-dealing: payer and host under one account; circular: mutual payment loops; below the minimum). HVX is a public statistic; nothing settles against it. Cache-Control: public, max-age=60.",
        "security": [
          {}
        ],
        "responses": {
          "200": {
            "description": "The index",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HvxView"
                }
              }
            }
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/holders/tiers": {
      "get": {
        "tags": [
          "Holder tiers"
        ],
        "operationId": "listHolderTiers",
        "summary": "The holder tier table",
        "description": "Public. Holder tiers are membership levels with fixed thresholds. Their perks are access and priority only; no tier changes a price, and every caller pays the host's price. Describes current behaviour, which can change. When no thresholds are set, enabled is false and tiers is empty.",
        "responses": {
          "200": {
            "description": "The tier table.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HolderTiers"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "core"
      }
    },
    "/api/v1/holders/me": {
      "get": {
        "tags": [
          "Holder tiers"
        ],
        "operationId": "getHolderStatus",
        "summary": "The tier of the wallet behind this key",
        "description": "The tier of the wallet behind the calling key, the next threshold and the perks that apply to the key now. The balance is read from the wallet's token account and cached for about an hour. Only a wallet sign-in key has a wallet; any other key gets the same shape with wallet null and a hint. Holder tiers are membership levels with fixed thresholds. Their perks are access and priority only; no tier changes a price, and every caller pays the host's price. Describes current behaviour, which can change.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The key's tier and perks.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HolderStatus"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/holders/polls": {
      "get": {
        "tags": [
          "Holder tiers"
        ],
        "operationId": "listHolderPolls",
        "summary": "Advisory polls and their tallies",
        "description": "Public. The latest polls, newest first (at most 100), each with its tally. Polls are advisory: a result informs a decision and does not carry it out.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Keep only open or only closed polls.",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "closed"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Polls, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/HolderPoll"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/holders/polls/{id}": {
      "get": {
        "tags": [
          "Holder tiers"
        ],
        "operationId": "getHolderPoll",
        "summary": "One advisory poll's results",
        "description": "Public. An open poll shows the tally so far; a closed poll shows the final tally.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^poll_[A-Za-z0-9_-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The poll.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HolderPoll"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/holders/polls/{id}/vote": {
      "post": {
        "tags": [
          "Holder tiers"
        ],
        "operationId": "castHolderVote",
        "summary": "Cast one advisory vote, signed by the wallet",
        "description": "One vote per wallet per poll; it cannot be changed. The wallet must hold a tier with a vote right now; the vote counts with that tier's fixed vote_weight, never the balance, and is checked again when the poll closes. Signed with X-Wallet-Auth for this POST (the method, the router's host and this path), where the hash is the SHA-256 of the canonical JSON of the body (keys sorted, no spaces). At most 10 attempts a minute per wallet. Advisory: the result does not carry anything out.",
        "security": [
          {
            "WalletAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^poll_[A-Za-z0-9_-]{1,64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HolderVoteRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The vote was recorded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HolderVote"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "already_voted: this wallet has voted in this poll. poll_closed: voting has ended.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "description": "balance_unavailable: the wallet's token balance could not be read. Try again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-launch-surface": "all"
      }
    },
    "/api/v1/credits/owner-tx": {
      "post": {
        "tags": [
          "Credits"
        ],
        "operationId": "registerCreditsOwner",
        "summary": "Register the key's owner wallet",
        "description": "Registers one owner wallet for this key on chain (trellis_credits::set_key_authority). The transaction is signed here as the key; the wallet named in owner signs as the new owner and as fee payer and sends it. First registration wins, and afterwards the key alone can never change the owner (only the owner wallet can, on chain). The owner can close the key without the key (POST /api/v1/credits/close with as_owner) and take back any closure; it gains no claim on the balance, which still only returns to the wallets that deposited. Do this when the key is created, before it can leak. 400 no_credit_account before the first deposit, 409 owner_already_registered (error.metadata.owner), 409 credits_closing.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "owner"
                ],
                "properties": {
                  "owner": {
                    "type": "string",
                    "description": "The wallet to register as owner (base58). It must sign the returned transaction."
                  }
                }
              },
              "example": {
                "owner": "<base58 wallet address>"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The cancellation to finish with the payer's signature",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreditClosureCancel"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "transaction": "<base64>",
                    "message": "Trellis credits: take back the closure of key 11888fa4…",
                    "accounts": {
                      "refundRequest": "Byn9yxiKaw8rNjraDJaZJsuyzk3ymgutdj7wiWXm7VDE"
                    },
                    "payer": "GXTZont2hnAMvcQ9CuQRzihrczgwNZNC9JGoEcpsohHc",
                    "expires_at_block_height": 314159265,
                    "signed_by_key": true,
                    "note": "Sign with the payer wallet and send before the blockhash expires. Once it lands the key is open again with its balance and serves calls as before."
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "refund_in_progress: the closure has already been paid in part or in full and can no longer be cancelled. Not a transient error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "example": {
                  "error": {
                    "code": 409,
                    "message": "This closure has already been paid in part or in full and can no longer be cancelled.",
                    "type": "refund_in_progress"
                  }
                }
              }
            }
          },
          "503": {
            "description": "chain_unavailable: the Solana RPC is unavailable; try again shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-launch-surface": "core"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AdminToken": {
        "type": "apiKey",
        "in": "header",
        "name": "x-admin-token",
        "description": "Operator ADMIN_TOKEN. Authorization: Bearer with the operator token is also accepted."
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Trellis API key",
        "description": "Send the key in Authorization. Never put it in a URL."
      },
      "AnthropicApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Anthropic SDK style: the Trellis key in x-api-key. Authorization: Bearer with the same key works too. Never put it in a URL."
      },
      "WalletAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Wallet-Auth",
        "description": "X-Wallet-Auth: <base58 address>:<unixSeconds>:<base58 ed25519 signature>, where the signature, by the wallet whose public key is the address, is over the UTF-8 bytes of trellis:wallet-auth:v2\\n<METHOD>\\n<host>\\n<path>\\n<unixSeconds>\\n<sha256 hex> (six lines joined by line feeds, no trailing one): METHOD is the request method in upper case; host is the router's public host as configured, with its port if it has one, in lower case (the value the sign-in challenge calls domain); path is the request path with its query string, as sent; the last line is the SHA-256 of what the route binds. What a route binds: the chat routes bind the canonical JSON (keys sorted, no whitespace) of the body without stream and stream_options; other JSON routes bind the canonical JSON of the body; a GET binds the empty string; GET /api/v1/hosts/{providerId} binds the string \"GET /api/v1/hosts/<url-encoded providerId>\". Valid for five minutes and single use per (address, timestamp, method, host, path, hash): a signature for one route, method or router is refused on any other. The earlier message, trellis:<unixSeconds>:<sha256>, named no method, path or host and is no longer accepted (401 invalid_wallet_auth; error.metadata carries version and host). Lets a wallet spend the change left on its account w_<address> by earlier x402 payments, binds a bare transaction signature in X-PAYMENT to the wallet that paid, lets a host operator read its private host fields and sign up a host, and signs a holder's advisory vote. Never authorizes a payment by itself."
      },
      "PrivateToken": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Only where the router enables blind tokens. `PrivateToken token=<base64url>`: one Privacy Pass token (RFC 9578 type 0x0002, 354 bytes) bought with POST /api/v1/blind/purchase. Each token can be spent once."
      }
    },
    "parameters": {
      "Referer": {
        "name": "HTTP-Referer",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      "Title": {
        "name": "X-Title",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      "Payment": {
        "name": "X-Payment",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Payment for this exact request, where the router has x402 enabled (data.per_call.x402 in GET /api/v1/status): either base64 JSON {x402Version: 1, scheme: \"exact\", network, payload: {transaction}} for the requirement in the 402 body, where transaction is a base64 Solana transaction that holds exactly one SPL TransferChecked of USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v, 6 decimals) from the payer's token account to payTo's associated token account, with extra.feePayer as fee payer (its signature slot left empty) and the payer's signature present, no address lookup tables; or the base58 signature of such a transfer already sent and finalized. The fee payer co-signs only inside fixed bounds and refuses anything else before it signs: exactly two required signatures (the fee payer and the payer); the fee payer named by no instruction; at most one SetComputeUnitLimit (at most 200,000 units) and one SetComputeUnitPrice (at most 5,000,000 micro-lamports per unit) with a priority fee, ceil(limit x price / 1e6), of at most 10,000 lamports (with no explicit limit the fee is computed on 200,000 units per other instruction); at most one idempotent creation of payTo's associated token account, funded by the payer and never by the fee payer; no other program. A bare transaction signature is accepted only together with X-Wallet-Auth from the wallet that paid, signed for this request: a landed payment is public, so the signature alone does not show who is asking (401 payment_not_bound_to_caller without it, 402 with the same type when another wallet signed). The facilitator co-signs as fee payer, submits, and serves the call; unused value stays as change on the account w_<payer>. Rejections are a fresh 402 with payment_error (for example invalid_exact_svm_payload_transaction_amount_mismatch, invalid_exact_svm_payload_transaction_blockhash_expired, invalid_exact_svm_payload_transaction_instructions_compute_price_instruction_too_high, invalid_exact_svm_payload_transaction_create_ata_instruction, invalid_exact_svm_payload_transaction_fee_payer_included_in_instruction_accounts, payment_already_claimed). Do not replay blindly."
      },
      "PaymentSignature": {
        "name": "PAYMENT-SIGNATURE",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "x402 v2 form of X-PAYMENT: base64 JSON PaymentPayload {x402Version: 2, resource, accepted, payload: {transaction}} for the requirement in PAYMENT-REQUIRED, with the same base64 Solana transaction. Read like X-PAYMENT; do not replay blindly."
      },
      "PaymentRecovery": {
        "name": "PAYMENT-RECOVERY",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$"
        },
        "description": "x402 payment recovery, where data.per_call.x402.recovery.available is true: the payer's base58 ed25519 signature of the UTF-8 text trellis:x402-recovery:<network>:<payer>:<nonce> (data.per_call.x402.recovery.message gives the template; nonce is the payer's transaction signature). Sent with the same X-PAYMENT or PAYMENT-SIGNATURE and the identical request after a paid answer was lost, it returns the answer kept for that payer and nonce byte for byte, with the same settlement headers, and never relays the payment again. Kept 24 hours. Refusals: 401 invalid_payment_recovery, 409 payment_request_mismatch, 404 payment_recovery_not_found with metadata.settled."
      },
      "PayWith": {
        "name": "X-Pay-With",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$"
        },
        "description": "Pay with a tokenized stock (docs §6): the base58 mint of an xStock or other tokenized stock with a Jupiter route. A Swig session key with a per-day cap in that token signs an ExactOut swap for the USDC owed, batched until 1 USD or 24 hours; the fill must be within 1% of the oracle value, and a mint whose Scaled UI Amount multiplier changes within 24 hours falls back to credits. On any failure the call is paid from prepaid credits, then 402. Only for keys with a pay-with session; a key's pay_with_default applies when the header is absent."
      },
      "DisclosureMax": {
        "name": "X-Trellis-Disclosure-Max",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "none",
            "policy",
            "any"
          ],
          "default": "any"
        },
        "description": "Same as provider.disclosure. When both are given the stricter one applies."
      },
      "Lane": {
        "name": "X-Trellis-Lane",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "public",
            "attested",
            "unlinkable"
          ],
          "default": "public"
        },
        "description": "Same as provider.lane. When both are given the stricter one applies. unlinkable is served only where the router enables Oblivious HTTP or serves the lane over its Tor onion service (otherwise 501), and then only through a relay, or through the onion service, with a blind token."
      },
      "LaneDowngrade": {
        "name": "X-Trellis-Lane-Downgrade",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "none",
            "attested"
          ],
          "default": "none"
        },
        "description": "Same as provider.lane_downgrade: attested lets a request for lane unlinkable that carries an API key or a wallet be served on lane attested. none in either setting refuses the downgrade."
      },
      "TlogKind": {
        "name": "kind",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "receipt_key",
            "ohttp_key_config",
            "blind_issuer_key",
            "measurement_bundle",
            "attestation_binding",
            "data_inventory",
            "host_policy"
          ]
        }
      },
      "TlogSha256": {
        "name": "sha256",
        "in": "query",
        "required": true,
        "description": "Lowercase hex SHA-256 of the key or configuration.",
        "schema": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        }
      },
      "DecisionTag": {
        "name": "X-Trellis-Decision-Tag",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^(sha256:)?[0-9a-fA-F]{64}$"
        },
        "description": "Optional sha256:<64 hex>, for example the SHA-256 of the order intent this call informs. Signed into the receipt as payload.decision_tag and v2 claims.decision_tag. Refused with 400 invalid_decision_tag when malformed and 400 decision_tag_unlinkable on the unlinkable lane. Ignored while DECISION_TAGS_ENABLED is false (the default)."
      },
      "TrellisTab": {
        "name": "X-Trellis-Tab",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$"
        },
        "description": "The tab x402 scheme (docs §5.2, program trellis_tab): the base58 address of an open Tab account whose payee is this router (opened by the payer's wallet with open_tab(payer, payee, mint = USDC, cap, expiry, session_key), which moves cap into the tab's escrow; expiry is at most 30 days out; a tab bound to the payer's rulebook also passes the rulebook, the rules config and the rules program to open_tab and top_up, never to close or reclaim). Sent together with X-Trellis-Tab-Voucher on every request the tab pays for; the router bills the voucher delta and stops serving when unvouched usage exceeds max(0.25 x last request cost, 0.05 USDC). On close the payee posts the highest voucher: the program pays cumulative_used and refunds the rest; anyone can reclaim 24 hours after expiry if no close happened (no signature is needed: the payee gets its highest posted voucher, the payer the rest)."
      },
      "TrellisTabVoucher": {
        "name": "X-Trellis-Tab-Voucher",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9+/=]{148}\\.[A-Za-z0-9+/=]{88}$"
        },
        "description": "The voucher for X-Trellis-Tab: base64 of the 110-byte message \"trellis:tab:voucher:v1\" (22 ASCII bytes) || the tab program id (32 bytes) || tab (32 bytes) || Tab.created_at i64 little-endian || cumulative_used u64 little-endian || seq u64 little-endian, a dot, then base64 of the 64-byte ed25519 signature of that message by the tab's session key (registered at open_tab; the wallet itself never signs vouchers). The domain string keeps a voucher from being any other message the key signed; the program id binds it to one deployment, and so to one cluster; created_at (the time the program recorded when open_tab landed, read from the Tab account) binds it to one opening of the tab address, so a voucher of a closed tab is worth nothing against a tab opened again at the same address. Only this form is accepted: the earlier 48-byte message (tab || cumulative_used || seq) is refused (400 invalid_tab_voucher). cumulative_used is the total in USDC base units the payer authorizes so far and must not decrease; seq must strictly increase per tab; cumulative_used may not exceed the tab's cap. Refusals: 402 voucher_required (unvouched usage over the allowance), 402 cap_exceeded, 402 voucher_wrong_program (signed for another tab program), 402 voucher_wrong_tab_opening (signed for an earlier opening of this tab address), 402 invalid_voucher_signature, 402 voucher_stale, 402 tab_not_found, 402 tab_expired."
      }
    },
    "headers": {
      "RouteExplanation": {
        "description": "V84: compact JSON RouteExplanation, on chat/text completions and embeddings when ROUTE_EXPLAIN_ENABLED is true (default false; switched on at trellis.example). The signed receipt route claim has the same fields. Streams wait for the serving provider before sending this header and also deliver the claim in the final receipt. Cache and encrypted-chat paths omit it.",
        "schema": {
          "type": "string"
        }
      },
      "Disclosure": {
        "description": "The disclosure class the answering provider was served under: attested (retention declared attested and a fresh TEE attestation), policy (a documented no-retention policy, no legal hold) or vendor-forwarded (anything else). On a stream it is sent only when every provider the request can reach shares one class; the signed receipt always carries it.",
        "schema": {
          "type": "string",
          "enum": [
            "attested",
            "policy",
            "vendor-forwarded"
          ]
        }
      },
      "LaneServed": {
        "description": "The lane the request was served under: public (any provider), attested (only providers under attested retention with a fresh attestation) or unlinkable (attested providers, reached through an Oblivious HTTP relay or over Tor through the router's onion service, and paid with a blind token). It is the lane the router enforced: the one the request asked for (or its key's or saved route's default), attested when an unlinkable request with a key allowed that downgrade, unlinkable for a relayed blind-token request that named none, and otherwise public.",
        "schema": {
          "type": "string",
          "enum": [
            "public",
            "attested",
            "unlinkable"
          ]
        }
      },
      "ReceiptId": {
        "description": "The id of this generation's signed receipt: the same value as the response's id and receipt.id. Read the receipt with GET /api/v1/receipts/{id}. On a stream it is sent before the first chunk; the final event carries the receipt itself.",
        "schema": {
          "type": "string"
        }
      },
      "InferenceId": {
        "description": "The same id as X-Receipt-Id, under the header name Hugging Face inference clients read.",
        "schema": {
          "type": "string"
        }
      },
      "GenerationId": {
        "description": "The same id as X-Receipt-Id (GET /api/v1/generation?id=...).",
        "schema": {
          "type": "string"
        }
      },
      "PolicyHash": {
        "description": "Present only when the serving endpoint's fresh, verified attestation bound the hash of the policy its in-enclave classifier enforces (\"sha256:<64 hex>\"). Omitted otherwise, and on a stream unless every endpoint the request can reach attested the same hash. The router relays the attested value; it never computes one.",
        "schema": {
          "type": "string",
          "pattern": "^sha256:[0-9a-f]{64}$"
        }
      }
    },
    "responses": {
      "ApiError": {
        "description": "OpenRouter-shaped API error. A 402 payment response may include payment metadata and is not a signal to repeat payment automatically.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "BadRequest": {
        "description": "The request body, JSON or parameters failed validation. error.type is, for example, invalid_request, invalid_json or invalid_guardrails; do not retry the same request unchanged. On chat, completions, embeddings and the Messages, Responses and Ollama adapters it can also be unboundable_input: the request carries input whose token count has no upper bound, so no hold can be priced for it (image, audio, video or file input to a model whose catalog entry declares no input_token_limits for that kind, with error.metadata.kinds; an unknown content-part type, with error.metadata.part_type; a provider-side tool, which is a tools entry whose type is not function; web_search_options; or an embeddings input that is neither text nor token ids). Send text, or choose a model that declares the limit. On /completions, prompt may be a string, an array of strings, an array of token ids or an array of token-id arrays, and each string or id array of a list is its own completion, held and priced as one: more than 16 (operator setting HOLD_MAX_PROMPT_BATCH; error.metadata.max) is prompt_batch_too_large, and any other shape is invalid_request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Authentication is missing or was rejected: no API key, an unknown, disabled or expired key, or invalid wallet authentication. error.type is missing_key, invalid_key, key_disabled, key_expired or invalid_wallet_auth.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "The call cannot be paid: the balance or the key's budget is insufficient (insufficient_credits, key_budget_exceeded; the balance must cover the hold, error.metadata.required_usd, which is the request's worst case and a bound, not an estimate: the prompt's bytes plus the output cap, so a lower max_tokens lowers it, and what the call does not use is released when it settles),a per-call payment is required or was not accepted (payment_required with the x402 requirement in the body and payment_error naming the reason, payment_pending while a bare transaction signature is not finalized, payment_failed, per_call_too_large above the per-call maximum), or a tab voucher is needed (voucher_required, cap_exceeded, tab_expired). A payment_required body is also the x402 v1 PaymentRequirementsResponse {x402Version: 1, error, accepts: [X402Requirement], price_usdc, model} and binds to this exact request; never repeat a payment automatically.",
        "headers": {
          "PAYMENT-REQUIRED": {
            "description": "Present when the router has x402 enabled: the x402 v2 PaymentRequired (base64 JSON {x402Version: 2, error, resource: {url, description, mimeType}, accepts: [{scheme: \"exact\", network, amount, asset, payTo, maxTimeoutSeconds, extra: {feePayer, decimals}}]}) for the same price as the body, with the CAIP-2 network (mainnet solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) and amount in USDC base units.",
            "schema": {
              "type": "string"
            }
          },
          "PAYMENT-RESPONSE": {
            "description": "x402 v2, only when a payment was rejected or its settlement failed: base64 JSON {success: false, errorReason, transaction: \"\", network, payer}.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        },
        "x-x402-body": {
          "$ref": "#/components/schemas/X402PaymentRequired"
        }
      },
      "Forbidden": {
        "description": "The key is valid but may not do this: its role does not allow the action, or its model allowlist excludes the model. error.type is forbidden or model_not_allowed. On a model call it can also be early_access: the model is inside its early-access window and not open to the caller yet. error.metadata then holds model, opens_at, early_access_until and tier (the caller's tier name or null), Retry-After gives the seconds until it opens to the caller, and nothing is charged. On a holder vote it is not_a_holder: the wallet holds no tier with a vote.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "With early_access: seconds until the model opens to the caller.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      },
      "NotFound": {
        "description": "The model, provider route, key, team, generation or receipt does not exist or is not visible to the caller. error.type is, for example, not_found, model_not_found or no_providers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "DisclosureUnavailable": {
        "description": "409 disclosure_unavailable. No provider meets provider.disclosure, though the model has providers that would otherwise serve the request (a lane that no attested endpoint can serve is 503 no_attested_endpoint instead). On chat completions it can also be verification_unavailable: verify \"dual\" found fewer than two providers of the model that support temperature and seed (on lane attested: fewer than two different attested providers of the model). The request is never routed to a provider that does not meet the setting; nothing was sent to any provider and nothing was charged. Also credits_closing: the key's credits are being closed (the closure from POST /api/v1/credits/close is registered on chain), so the key is frozen until its refund is paid; error.metadata.closure names the closure, and retrying with the same key does not help.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "LaneNotAvailable": {
        "description": "501 lane_not_available. Lane unlinkable is not available on this router: it needs the Oblivious HTTP gateway, or the lane over its Tor onion service, with blind tokens, which it does not run. Nothing was sent to any provider.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "DisclosureProviderDown": {
        "description": "503. no_attested_endpoint: lane attested or unlinkable, and no endpoint of the model with a fresh, verified attestation can serve it; error.metadata.reason is none_attested, or attested_endpoints_down (with Retry-After) when attested endpoints exist but are all in an outage. A council with an attested seat (a member or the judge) that has none is refused the same way, and error.metadata.council_seat names the seat. disclosure_provider_unavailable: providers that meet provider.disclosure exist but are all in an outage right now; retry after Retry-After. Either way the request is not routed to any other provider and nothing was charged.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "A rate limit was reached (rate_limited). Wait for the Retry-After interval before retrying.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying, when the limit reports it.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "AnthropicError": {
        "description": "Anthropic's error shape, for the Messages endpoints. error.type follows the status: 400 invalid_request_error, 401 authentication_error, 402 billing_error, 403 permission_error, 404 not_found_error, 413 request_too_large, 429 rate_limit_error (with Retry-After), 5xx api_error, 504 timeout_error. A status Anthropic does not define keeps its own (409 for a lane no provider can serve, 501 for a lane the router does not run) and sends X-Should-Retry: false. trellis carries the router's own error type and metadata, and the receipt_id when a refused call was billed. A 400 whose trellis.type is unboundable_input is input no hold can be priced for: for example an image sent to a model whose catalog entry declares no per-image token limit (input_token_limits).",
        "headers": {
          "Request-Id": {
            "description": "An id for this request (req_...), also in the error body's request_id.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AnthropicErrorBody"
            }
          }
        }
      },
      "OllamaError": {
        "description": "Ollama's error shape, {\"error\": \"...\"}, with the router's status: 400 for a bad field (the message names it), 401 or 402 without a usable key, 404 for an unknown model (the message names one to use), 409 or 503 when the requested lane cannot be served, 429 with Retry-After, 501 for local-model operations, 502 when every provider failed before any output.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/OllamaErrorBody"
            }
          }
        }
      },
      "CreditsClosing": {
        "description": "credits_closing: this key's credits are being closed. Once the closure (POST /api/v1/credits/close) is registered on chain the key is frozen and anything that would spend is refused until the refund is paid or the closure is cancelled (POST /api/v1/credits/close/cancel); error.metadata.closure is the closure's id. Not a transient error: do not retry with the same key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "example": {
              "error": {
                "code": 409,
                "message": "This key's credits are being closed and refunded; it cannot start new calls.",
                "type": "credits_closing",
                "metadata": {
                  "closure": "close_…"
                }
              }
            }
          }
        }
      },
      "NotEnabled": {
        "description": "This route is not on the router's launch surface. A router running LAUNCH_SURFACE=core (the default) registers only the operations marked `x-launch-surface: core`; every other path answers this, whatever the feature's own setting says. `GET /api/v1/status` reports the surface under `data.launch_surface`.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "const": 404
                    },
                    "type": {
                      "const": "not_enabled"
                    },
                    "message": {
                      "type": "string"
                    },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "launch_surface": {
                          "const": "core"
                        }
                      }
                    }
                  }
                }
              }
            },
            "example": {
              "error": {
                "code": 404,
                "type": "not_enabled",
                "message": "POST /api/v1/batches is not enabled on this router (launch surface: core). GET /api/v1/status lists what is.",
                "metadata": {
                  "launch_surface": "core"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "AgentReplay": {
        "type": "object",
        "required": [
          "window",
          "evaluated",
          "allowed",
          "denied",
          "asked",
          "by_reason",
          "actual",
          "changed",
          "examples",
          "truncated",
          "notes"
        ],
        "properties": {
          "window": {
            "type": "object",
            "required": [
              "from",
              "to",
              "days"
            ],
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              },
              "days": {
                "type": "integer"
              }
            }
          },
          "evaluated": {
            "type": "integer"
          },
          "allowed": {
            "type": "integer"
          },
          "denied": {
            "type": "integer"
          },
          "asked": {
            "type": "integer",
            "description": "Sent to ask me first; counted as not run."
          },
          "stopped_at": {
            "type": "string",
            "format": "date-time",
            "description": "Present when the draft would have stopped the key; every later call is refused."
          },
          "stopped_reason": {
            "type": "string"
          },
          "by_reason": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "actual": {
            "type": "object",
            "description": "What happened to the same calls and actions. not_recorded counts calls that ran with no rulebook decision.",
            "required": [
              "allowed",
              "denied",
              "asked",
              "not_recorded"
            ],
            "properties": {
              "allowed": {
                "type": "integer"
              },
              "denied": {
                "type": "integer"
              },
              "asked": {
                "type": "integer"
              },
              "not_recorded": {
                "type": "integer"
              }
            }
          },
          "changed": {
            "type": "integer",
            "description": "Calls and actions whose replayed decision differs from the recorded one."
          },
          "examples": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "required": [
                "time",
                "kind",
                "model",
                "lane",
                "action",
                "cost_usd",
                "decision",
                "reason",
                "actual"
              ],
              "properties": {
                "time": {
                  "type": "string",
                  "format": "date-time"
                },
                "kind": {
                  "enum": [
                    "call",
                    "action"
                  ]
                },
                "model": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "lane": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "action": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "cost_usd": {
                  "type": "number"
                },
                "decision": {
                  "enum": [
                    "allow",
                    "deny",
                    "approval_required"
                  ]
                },
                "reason": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "actual": {
                  "enum": [
                    "allow",
                    "deny",
                    "approval_required",
                    null
                  ]
                }
              }
            }
          },
          "truncated": {
            "type": "boolean"
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "FacilitatorPaymentRequest": {
        "type": "object",
        "properties": {
          "x402Version": {
            "type": "integer",
            "enum": [
              1,
              2
            ]
          },
          "paymentPayload": {
            "type": "object",
            "properties": {
              "x402Version": {
                "type": "integer",
                "enum": [
                  1,
                  2
                ]
              },
              "scheme": {
                "type": "string",
                "enum": [
                  "exact",
                  "tab"
                ]
              },
              "network": {
                "type": "string",
                "example": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
              },
              "accepted": {
                "type": "object",
                "properties": {
                  "scheme": {
                    "type": "string"
                  },
                  "network": {
                    "type": "string"
                  }
                },
                "description": "v2: the chosen requirement."
              },
              "resource": {
                "type": "object"
              },
              "payload": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "transaction": {
                        "type": "string",
                        "description": "exact: the payer-signed base64 transaction (see X402PaymentPayload)."
                      }
                    },
                    "required": [
                      "transaction"
                    ],
                    "title": "exact"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "voucher": {
                        "$ref": "#/components/schemas/TabVoucher"
                      },
                      "transaction": {
                        "type": "string",
                        "description": "tab, required for /settle: the payee-signed close transaction [Ed25519(voucher), trellis_tab::close(cumulative_used, seq)] with the facilitator's relay key as fee payer, base64. The facilitator checks it is exactly that close, co-signs as fee payer and submits: escrow pays cumulative_used to the payee and refunds the rest to the payer."
                      }
                    },
                    "required": [
                      "voucher"
                    ],
                    "title": "tab"
                  }
                ]
              }
            },
            "required": [
              "x402Version",
              "payload"
            ]
          },
          "paymentRequirements": {
            "type": "object",
            "properties": {
              "scheme": {
                "type": "string",
                "enum": [
                  "exact",
                  "tab"
                ]
              },
              "network": {
                "type": "string"
              },
              "payTo": {
                "type": "string",
                "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$"
              },
              "asset": {
                "type": "string",
                "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
                "description": "Must be the USDC mint."
              },
              "maxAmountRequired": {
                "type": "string",
                "description": "v1 amount in base units."
              },
              "amount": {
                "type": "string",
                "description": "v2 amount in base units."
              },
              "maxTimeoutSeconds": {
                "type": "integer"
              },
              "extra": {
                "type": "object"
              }
            },
            "required": [
              "scheme",
              "network",
              "payTo",
              "asset"
            ]
          }
        },
        "required": [
          "paymentPayload",
          "paymentRequirements"
        ],
        "description": "The x402 facilitator request (Coinbase facilitator shape). exact: the payer's signed USDC transfer, co-signed by the relay as fee payer. tab: the voucher, plus for settlement the payee-signed trellis_tab::close the relay co-signs; the relay key only ever pays fees."
      },
      "FacilitatorVerifyResponse": {
        "type": "object",
        "properties": {
          "isValid": {
            "type": "boolean"
          },
          "invalidReason": {
            "type": "string",
            "description": "exact: invalid_exact_svm_payload_transaction*, invalid_network, unsupported_scheme, unsupported_asset, amount_below_minimum; tab: invalid_tab_voucher, tab_not_found, tab_payee_mismatch, tab_asset_mismatch, tab_expired, voucher_exceeds_cap, voucher_stale, invalid_voucher_signature, voucher_below_amount, invalid_tab_close_*, tab_close_transaction_required."
          },
          "payer": {
            "type": [
              "string",
              "null"
            ],
            "description": "The payer's base58 address when it could be read."
          }
        },
        "required": [
          "isValid"
        ]
      },
      "FacilitatorSettleResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "errorReason": {
            "type": "string"
          },
          "transaction": {
            "type": "string",
            "description": "The base58 Solana transaction signature; empty when nothing was settled."
          },
          "network": {
            "type": "string"
          },
          "payer": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "transaction",
          "network",
          "payer"
        ]
      },
      "FacilitatorSupported": {
        "type": "object",
        "properties": {
          "kinds": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "x402Version": {
                  "type": "integer"
                },
                "scheme": {
                  "type": "string",
                  "enum": [
                    "exact",
                    "tab"
                  ]
                },
                "network": {
                  "type": "string"
                },
                "extra": {
                  "type": "object",
                  "properties": {
                    "feePayer": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The relay key that co-signs as fee payer."
                    },
                    "program": {
                      "type": "string",
                      "description": "tab: the trellis_tab program id."
                    },
                    "maxCapUnits": {
                      "type": "string",
                      "description": "tab: the largest cap a tab may hold while the programs are pre-audit."
                    },
                    "settlement": {
                      "type": "string",
                      "const": "payee_signed_close_relayed"
                    }
                  }
                }
              }
            }
          },
          "fee_bps": {
            "type": "integer",
            "description": "0 while the fee is waived."
          },
          "fee_waiver_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "networks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "kinds",
          "fee_bps",
          "networks"
        ]
      },
      "NetworkStats": {
        "type": "object",
        "required": [
          "as_of",
          "cache_seconds",
          "hosts",
          "attested_hosts",
          "capacity",
          "tokens",
          "bonds",
          "interest",
          "policy_version"
        ],
        "properties": {
          "as_of": {
            "type": "string",
            "format": "date-time"
          },
          "cache_seconds": {
            "type": "integer",
            "const": 30
          },
          "hosts": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "minimum": 0
              },
              "probation": {
                "type": "integer",
                "minimum": 0
              },
              "live": {
                "type": "integer",
                "minimum": 0
              },
              "rejected": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "total",
              "probation",
              "live",
              "rejected"
            ]
          },
          "attested_hosts": {
            "type": "integer",
            "minimum": 0
          },
          "capacity": {
            "type": "object",
            "properties": {
              "model_count": {
                "type": "integer",
                "minimum": 0
              },
              "models": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "definition": {
                "type": "string"
              }
            },
            "required": [
              "model_count",
              "models",
              "definition"
            ]
          },
          "tokens": {
            "type": "object",
            "properties": {
              "public_lane": {
                "type": "object",
                "properties": {
                  "days_7": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "lower": {
                        "type": "string",
                        "pattern": "^[0-9]+$"
                      },
                      "upper_exclusive": {
                        "type": "string",
                        "pattern": "^[0-9]+$"
                      }
                    },
                    "required": [
                      "lower",
                      "upper_exclusive"
                    ]
                  },
                  "days_30": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "lower": {
                        "type": "string",
                        "pattern": "^[0-9]+$"
                      },
                      "upper_exclusive": {
                        "type": "string",
                        "pattern": "^[0-9]+$"
                      }
                    },
                    "required": [
                      "lower",
                      "upper_exclusive"
                    ]
                  },
                  "bucket_size": {
                    "type": "string",
                    "const": "100000"
                  }
                },
                "required": [
                  "days_7",
                  "days_30",
                  "bucket_size"
                ]
              },
              "private_lanes": {
                "type": "null"
              },
              "dp_stats_url": {
                "type": "string",
                "const": "/api/v1/stats"
              },
              "definition": {
                "type": "string"
              }
            },
            "required": [
              "public_lane",
              "private_lanes",
              "dp_stats_url",
              "definition"
            ]
          },
          "bonds": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "total_units": {
                "type": "string",
                "pattern": "^[0-9]+$"
              },
              "active_units": {
                "type": "string",
                "pattern": "^[0-9]+$"
              },
              "asset": {
                "type": "string",
                "const": "USDC"
              },
              "decimals": {
                "type": "integer",
                "const": 6
              },
              "fresh": {
                "type": "boolean"
              },
              "indexed_block": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "total_units",
              "active_units",
              "asset",
              "decimals",
              "fresh",
              "indexed_block"
            ]
          },
          "interest": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "minimum": 0
              },
              "by_role": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "by_region": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "readiness_mentions": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "total",
              "by_role",
              "by_region",
              "readiness_mentions"
            ]
          },
          "policy_version": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          }
        }
      },
      "AgentApproval": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "key_hash": {
            "type": "string"
          },
          "intent": {
            "description": "Routing identifiers, output limit and estimated cost only. Multi-model requests contain an intents array. No prompt or response fields.",
            "type": "object"
          },
          "intent_hash": {
            "type": "string"
          },
          "max_cost_pico": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "denied",
              "expired",
              "used"
            ]
          },
          "requested_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "decided_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "decided_by": {
            "type": [
              "string",
              "null"
            ]
          },
          "used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "key_hash",
          "intent",
          "intent_hash",
          "max_cost_pico",
          "status",
          "requested_at",
          "expires_at",
          "decided_at",
          "decided_by",
          "used_at"
        ]
      },
      "AgentBreakers": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "max_spend_usd_per_minute": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 1000000
          },
          "max_requests_per_minute": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "max_denials_per_10min": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "max_distinct_models_per_hour": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          }
        },
        "description": "Optional rolling recorded-state circuit breakers. Inclusive thresholds trip the router kill switch before the next admission with reason breaker:<field> and HTTP 403 agent_killed; no charge for the refused request. Account locking serializes observations, including inherited session admissions. Manual principal resume resets breaker observations and spend window, not cap spend. Recorded spend includes open usage reservations; in-flight work may finish. Only requests through Trellis. AGENT_POLICY_ENABLED defaults false."
      },
      "AgentPolicy": {
        "type": "object",
        "properties": {
          "alerts": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "at_percent": {
                "type": "array",
                "maxItems": 64,
                "items": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 100
                },
                "default": [
                  80,
                  100
                ]
              },
              "denials_in_10min": {
                "type": "integer",
                "minimum": 1,
                "maximum": 10000,
                "default": 5
              },
              "channels": {
                "type": "array",
                "maxItems": 3,
                "items": {
                  "enum": [
                    "webhook",
                    "email",
                    "telegram"
                  ]
                },
                "default": [
                  "webhook",
                  "telegram"
                ]
              }
            },
            "description": "Optional opt-in. Omission preserves behavior and hashes; empty object uses defaults. Reuses linked channels; email has no destination."
          },
          "version": {
            "type": "number",
            "const": 1
          },
          "models": {
            "type": "object",
            "properties": {
              "allow": {
                "maxItems": 64,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160
                }
              },
              "deny": {
                "maxItems": 64,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160
                }
              }
            },
            "additionalProperties": false
          },
          "lanes": {
            "maxItems": 64,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "public",
                "attested",
                "unlinkable"
              ]
            }
          },
          "caps": {
            "type": "object",
            "properties": {
              "per_request_usd": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000
              },
              "per_hour_usd": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000
              },
              "per_day_usd": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000
              },
              "per_week_usd": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000
              },
              "max_output_tokens": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 10000000
              }
            },
            "additionalProperties": false
          },
          "tools": {
            "type": "object",
            "properties": {
              "allow": {
                "maxItems": 64,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160
                }
              },
              "deny": {
                "maxItems": 64,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160
                }
              }
            },
            "additionalProperties": false
          },
          "windows": {
            "maxItems": 64,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "days": {
                  "maxItems": 64,
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 6
                  }
                },
                "start": {
                  "type": "string",
                  "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$"
                },
                "end": {
                  "type": "string",
                  "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$"
                }
              },
              "required": [
                "days",
                "start",
                "end"
              ],
              "additionalProperties": false
            }
          },
          "approval": {
            "type": "object",
            "properties": {
              "above_usd": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000
              },
              "above_calls_per_hour": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "Optional. Ask the principal first once the rolling hour already holds this many model calls the rulebook admitted, plus approvals used (reason approval_calls_per_hour)."
              }
            },
            "required": [
              "above_usd"
            ],
            "additionalProperties": false
          },
          "on_breach": {
            "type": "string",
            "enum": [
              "deny",
              "kill"
            ]
          },
          "autonomy": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "rungs",
              "demote_on"
            ],
            "properties": {
              "rungs": {
                "type": "array",
                "minItems": 1,
                "maxItems": 5,
                "description": "Requirements cannot decrease; spending multipliers must strictly increase above 1. Both thresholds apply at each rung.",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "after_days",
                    "clean_requests",
                    "caps_multiplier"
                  ],
                  "properties": {
                    "after_days": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    "clean_requests": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    "caps_multiplier": {
                      "type": "number",
                      "exclusiveMinimum": 1,
                      "maximum": 10
                    }
                  }
                }
              },
              "demote_on": {
                "type": "array",
                "maxItems": 3,
                "items": {
                  "type": "string",
                  "enum": [
                    "deny",
                    "kill",
                    "breaker"
                  ]
                }
              }
            }
          },
          "breakers": {
            "$ref": "#/components/schemas/AgentBreakers"
          }
        },
        "required": [
          "version",
          "models",
          "caps",
          "on_breach"
        ],
        "additionalProperties": false
      },
      "AgentIntent": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "kind",
              "model",
              "lane",
              "est_cost_pico",
              "tools"
            ],
            "properties": {
              "kind": {
                "const": "inference"
              },
              "model": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "lane": {
                "enum": [
                  "public",
                  "attested",
                  "unlinkable"
                ]
              },
              "est_cost_pico": {
                "type": "string",
                "pattern": "^[0-9]+$",
                "description": "Integer pico-USD, 1 USD = 10^12 pico."
              },
              "max_output_tokens": {
                "type": "integer",
                "minimum": 1,
                "maximum": 10000000
              },
              "tools": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160
                },
                "maxItems": 64
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "kind",
              "name"
            ],
            "properties": {
              "kind": {
                "const": "mcp_tool"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              }
            }
          }
        ]
      },
      "AgentDecision": {
        "type": "object",
        "required": [
          "decision",
          "reasons"
        ],
        "properties": {
          "decision": {
            "enum": [
              "allow",
              "deny",
              "approval_required"
            ]
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "code",
                "message"
              ],
              "properties": {
                "code": {
                  "enum": [
                    "killed",
                    "model_not_allowed",
                    "lane_not_allowed",
                    "over_per_request",
                    "over_per_hour",
                    "over_per_day",
                    "over_per_week",
                    "max_tokens",
                    "tool_not_allowed",
                    "outside_window",
                    "approval_required",
                    "breaker:max_spend_usd_per_minute",
                    "breaker:max_requests_per_minute",
                    "breaker:max_denials_per_10min",
                    "breaker:max_distinct_models_per_hour"
                  ]
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Playbook": {
        "type": "object",
        "required": [
          "id",
          "name",
          "team_id",
          "policy",
          "sha256",
          "version",
          "followers",
          "keys",
          "can_edit"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "team_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The owning team, or null for an account-wide playbook."
          },
          "policy": {
            "$ref": "#/components/schemas/AgentPolicy"
          },
          "sha256": {
            "type": "string",
            "description": "SHA-256 of the canonical rules; each following key's rulebook carries the same digest."
          },
          "version": {
            "type": "integer",
            "minimum": 1,
            "description": "1 at creation, plus one for each change of rules. A rename keeps it."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_by": {
            "type": "string",
            "description": "Hash of the key that made the last change."
          },
          "followers": {
            "type": "integer",
            "minimum": 0,
            "description": "Every key that follows the playbook."
          },
          "keys": {
            "type": "array",
            "description": "The following keys the caller manages.",
            "items": {
              "type": "object",
              "required": [
                "key_hash",
                "name"
              ],
              "properties": {
                "key_hash": {
                  "type": "string"
                },
                "name": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "can_edit": {
            "type": "boolean"
          }
        }
      },
      "PlaybookInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "policy"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "policy": {
            "$ref": "#/components/schemas/AgentPolicy"
          },
          "team_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Management keys only: a team the account owns."
          }
        }
      },
      "PlaybookUpdate": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "policy": {
            "$ref": "#/components/schemas/AgentPolicy"
          }
        }
      },
      "PlaybookChange": {
        "type": "object",
        "required": [
          "action",
          "version",
          "sha256",
          "name",
          "followers",
          "at"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "create",
              "update",
              "rename",
              "delete"
            ]
          },
          "version": {
            "type": "integer"
          },
          "sha256": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "followers": {
            "type": "integer",
            "minimum": 0
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PlaybookFollow": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "playbook_id"
        ],
        "properties": {
          "playbook_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "PlaybookFollowResult": {
        "type": "object",
        "required": [
          "key_hash",
          "changed",
          "playbook",
          "policy",
          "sha256",
          "killed",
          "playbook_id"
        ],
        "properties": {
          "key_hash": {
            "type": "string"
          },
          "changed": {
            "type": "boolean"
          },
          "playbook": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "integer"
              }
            }
          },
          "policy": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/AgentPolicy"
              },
              {
                "type": "null"
              }
            ]
          },
          "sha256": {
            "type": [
              "string",
              "null"
            ]
          },
          "killed": {
            "type": "boolean"
          },
          "playbook_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "AgentPolicyResult": {
        "type": "object",
        "required": [
          "policy",
          "sha256",
          "version",
          "killed"
        ],
        "properties": {
          "policy": {
            "$ref": "#/components/schemas/AgentPolicy"
          },
          "sha256": {
            "type": "string"
          },
          "version": {
            "const": 1
          },
          "stopped_until": {
            "type": "string",
            "format": "date-time",
            "description": "B117: Present only on a timed stop; omitted on running or indefinitely stopped policies."
          },
          "killed": {
            "type": "boolean"
          },
          "killed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "killed_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "playbook_id": {
            "type": "string",
            "description": "Present only while the key follows a playbook (POST /api/v1/agents/{key_hash}/playbook); its rules are then that playbook's current rules."
          }
        }
      },
      "HostPublic": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "admission": {
            "type": [
              "object",
              "null"
            ],
            "description": "Null for curated providers. Approval requires admitted probation/live status, no refusal reasons and a fresh successful latest hardware attestation plus the recorded checked policy.",
            "required": [
              "status",
              "policy_version",
              "reasons",
              "checked_at"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "approved",
                  "not_approved"
                ]
              },
              "policy_version": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 1,
                "description": "Version recorded by admission or renewal, not necessarily the latest published policy."
              },
              "reasons": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "checked_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "tee_kind": {
            "type": "string"
          },
          "attested": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "probation": {
            "type": "boolean"
          },
          "shadow_until": {
            "type": [
              "string",
              "null"
            ]
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "attestation": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "attested",
                  "unverified"
                ]
              },
              "reason": {
                "type": "string"
              },
              "tee": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "verifiers": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "last_verified_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "last_attempt_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "last_attempt_ok": {
                "type": [
                  "boolean",
                  "null"
                ]
              }
            },
            "required": [
              "status",
              "tee",
              "verifiers",
              "last_verified_at",
              "last_attempt_at",
              "last_attempt_ok"
            ]
          },
          "verify_url": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "tee_kind",
          "attested",
          "status",
          "probation",
          "shadow_until",
          "models",
          "attestation",
          "verify_url"
        ]
      },
      "HostDetail": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "admission": {
            "type": [
              "object",
              "null"
            ],
            "description": "Null for curated providers. Approval requires admitted probation/live status, no refusal reasons and a fresh successful latest hardware attestation plus the recorded checked policy.",
            "required": [
              "status",
              "policy_version",
              "reasons",
              "checked_at"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "approved",
                  "not_approved"
                ]
              },
              "policy_version": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 1,
                "description": "Version recorded by admission or renewal, not necessarily the latest published policy."
              },
              "reasons": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "checked_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "tee_kind": {
            "type": "string"
          },
          "attested": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "probation": {
            "type": "boolean"
          },
          "shadow_until": {
            "type": [
              "string",
              "null"
            ]
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "attestation": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "attested",
                  "unverified"
                ]
              },
              "reason": {
                "type": "string"
              },
              "tee": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "verifiers": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "last_verified_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "last_attempt_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "last_attempt_ok": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "checks": {
                "type": "object",
                "description": "The existing attestation endpoint checks."
              },
              "not_checked": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "status",
              "tee",
              "verifiers",
              "last_verified_at",
              "last_attempt_at",
              "last_attempt_ok",
              "checks",
              "not_checked"
            ]
          },
          "verify_url": {
            "type": "string"
          },
          "attestation_history": {
            "type": [
              "object",
              "null"
            ],
            "description": "First 50 sanitized events from the existing attestation history endpoint, with data, next cursor, history_days and url. Null when history is disabled."
          },
          "measurement": {
            "type": [
              "object",
              "null"
            ],
            "description": "Existing attestation endpoint current measurement: digests, status, timestamps, hardware registers, registry state and transparency_log with Rekor entry_url and verification checks; no raw quote."
          },
          "measurement_history": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "Existing attestation endpoint superseded measurements, each with its own superseded_at and transparency_log entry_url."
            }
          },
          "anchoring": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "roots": {
                "type": "integer",
                "minimum": 0
              },
              "anchored_roots": {
                "type": "integer",
                "minimum": 0
              },
              "latest": {
                "anyOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "id": {
                        "type": "integer",
                        "minimum": 0
                      },
                      "root": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "local",
                          "pending",
                          "confirmed"
                        ]
                      },
                      "anchored": {
                        "type": "boolean"
                      },
                      "tx_hash": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "block_number": {
                        "type": [
                          "integer",
                          "null"
                        ]
                      },
                      "from_ts": {
                        "type": "string"
                      },
                      "to_ts": {
                        "type": "string"
                      },
                      "receipts": {
                        "type": "integer",
                        "minimum": 0
                      },
                      "attestation_ref": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "root",
                      "status",
                      "anchored",
                      "tx_hash",
                      "block_number",
                      "from_ts",
                      "to_ts",
                      "receipts",
                      "attestation_ref"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "roots",
              "anchored_roots",
              "latest"
            ]
          },
          "uptime": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "success_pct_30d": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 0,
                "maximum": 100
              },
              "observations_30d": {
                "type": "integer",
                "minimum": 0
              },
              "definition": {
                "type": "string"
              }
            },
            "required": [
              "success_pct_30d",
              "observations_30d",
              "definition"
            ]
          },
          "proof_time": {
            "type": [
              "object",
              "null"
            ],
            "description": "Existing proof-time summary metadata (generated_at, history_days, fresh_within_ms) and its host record. Host is null when absent from that summary. Proof-time itself is null when history is disabled."
          },
          "earnings": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "band": {
                "type": "string",
                "enum": [
                  "none yet",
                  "<$1",
                  "$1–10",
                  "$10–100",
                  "$100–1,000",
                  "$1,000+"
                ]
              },
              "basis": {
                "type": "string"
              }
            },
            "required": [
              "band",
              "basis"
            ]
          },
          "operator": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "payout_address": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "payout_mode": {
                "type": "string"
              },
              "invoiced_usdc_units": {
                "type": "string",
                "pattern": "^[0-9]+$"
              },
              "unpaid_usdc_units": {
                "type": "string",
                "pattern": "^[0-9]+$"
              },
              "decimals": {
                "type": "integer",
                "const": 6
              }
            },
            "required": [
              "payout_address",
              "payout_mode",
              "invoiced_usdc_units",
              "unpaid_usdc_units",
              "decimals"
            ],
            "description": "Present only after walletAuth recovers the stored provider operator. Lifetime invoice units include paid invoices; unpaid units have no recorded payment transaction and can include a pending payout."
          }
        },
        "required": [
          "id",
          "name",
          "tee_kind",
          "attested",
          "status",
          "probation",
          "shadow_until",
          "models",
          "attestation",
          "verify_url",
          "attestation_history",
          "measurement",
          "measurement_history",
          "anchoring",
          "uptime",
          "proof_time",
          "earnings"
        ]
      },
      "ApiError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "suggested_models": {
            "description": "B121: optional availability-error alternatives; empty if none match. Never switches models or charges. Messages also returns this top-level field; Responses stream errors carry it in the error event and response.error.",
            "type": "array",
            "maxItems": 3,
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "prompt_price",
                "completion_price",
                "why"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "prompt_price": {
                  "type": "string",
                  "description": "Dollars per input token"
                },
                "completion_price": {
                  "type": "string",
                  "description": "Dollars per output token"
                },
                "why": {
                  "type": "string"
                }
              }
            }
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "type"
            ],
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "metadata": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "description": "A 402 payment_required body additionally carries the x402 fields of X402PaymentRequired (x402Version, accepts, price_usdc, network_fee_max_usdc, model, payment_error). price_usdc (equal to accepts[0].maxAmountRequired in base units) is what the payment must carry: the request's worst-case price plus network_fee_max_usdc, and never less than the minimum payment (0.03 USDC by default). network_fee_max_usdc is the most the Solana network fee of an exact payment can be (0.005 USDC at the default settings); the router pays that fee and passes it on at cost, with no margin: what is kept back is the fee of the transaction as signed (5,000 lamports per signature plus its priority fee) at the router's stated SOL price, shown on the receipt as its own line (network_fee: lamports, usdc, sol_usdc, basis pass_through). Everything else is credited, and what the call does not use stays on the payer's wallet account as change. Sponsored payments are limited per payer, per source and in total, over any minute and any 24 hours (429 rate_limited); a payer whose sponsored payment failed after it was sent is refused with 403 payer_not_sponsored and can still pay its own fee and present the signature with X-Wallet-Auth. GET /api/v1/status reports lamports paid and USDC recovered under per_call.x402.network_fees."
      },
      "Model": {
        "description": "When UPSTREAM_MONITOR_ENABLED is on, availability is temporarily_unavailable if every eligible provider account has a last successful USD balance at or below UPSTREAM_BALANCE_EXHAUSTED_USD (default 0). This optional field is omitted otherwise. A failed check retains an exhausted state until a later reading exceeds the threshold. Account balances remain operator-only.",
        "type": "object",
        "required": [
          "id",
          "name",
          "created",
          "description",
          "context_length",
          "architecture",
          "pricing",
          "supported_parameters"
        ],
        "properties": {
          "availability": {
            "type": "string",
            "enum": [
              "temporarily_unavailable"
            ],
            "description": "Optional; all eligible upstream accounts are exhausted. Omitted otherwise."
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "vision",
                "imageOut",
                "audio",
                "tools",
                "longContext",
                "attested",
                "network",
                "encrypted"
              ]
            },
            "description": "Shared catalogue tags; longContext means at least 128,000 tokens. network requires a live fresh-attested network-host offer for an admitted model. encrypted requires the separate enabled gateway path, exact model ID and fresh evidence; ordinary chat remains readable by the router."
          },
          "provider_names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of providers with live servable offers for this model."
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "created": {
            "type": "integer"
          },
          "description": {
            "type": "string"
          },
          "context_length": {
            "type": "integer"
          },
          "architecture": {
            "type": "object"
          },
          "pricing": {
            "type": "object",
            "description": "Prices are returned as decimal strings per token; consult the live response."
          },
          "supported_parameters": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "input_token_limits": {
            "type": "object",
            "description": "The most prompt tokens one non-text input item can cost, per kind, as the model's providers declare it in their /models entry (the largest across them). Present only for models that declare it. A hold counts each such item at this figure; a request with image, audio, video or file input to a model that declares no figure for that kind is refused with 400 unboundable_input.",
            "properties": {
              "image": {
                "type": "integer",
                "minimum": 1
              },
              "audio": {
                "type": "integer",
                "minimum": 1
              },
              "video": {
                "type": "integer",
                "minimum": 1
              },
              "file": {
                "type": "integer",
                "minimum": 1
              }
            }
          },
          "data_policy": {
            "type": "object"
          },
          "attested_available": {
            "type": "boolean"
          },
          "lanes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "public",
                "attested",
                "unlinkable"
              ]
            },
            "description": "The lanes this model can be served on right now: public whenever it has a live endpoint; attested while one of its endpoints has attested retention and a fresh, verified attestation; unlinkable as well where the router serves that lane (Oblivious HTTP, or its Tor onion service). The endpoints listing carries the same field per endpoint."
          },
          "disclosure": {
            "type": "object",
            "description": "How many live endpoints are served under each disclosure class right now.",
            "properties": {
              "best": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "attested",
                  "policy",
                  "vendor-forwarded",
                  null
                ]
              },
              "endpoints": {
                "type": "object",
                "properties": {
                  "attested": {
                    "type": "integer"
                  },
                  "policy": {
                    "type": "integer"
                  },
                  "vendor-forwarded": {
                    "type": "integer"
                  }
                }
              }
            }
          },
          "creator": {
            "type": [
              "string",
              "null"
            ],
            "description": "Address that receives the model's creator royalty, once claimed."
          },
          "royalty_bps": {
            "type": "integer",
            "description": "Creator royalty in basis points of the notional price; 0 until a creator is recorded."
          },
          "variant": {
            "type": "string",
            "enum": [
              "mainstream",
              "native_low_refusal",
              "abliterated"
            ],
            "description": "native_low_refusal and abliterated are restricted: they are routed only to providers served under attested retention with a fresh attestation whose attestation reported the in-enclave hard-block classifier as enabled. Whatever lane or disclosure setting a request carries, and however the provider is pinned, they are never sent to a public or vendor-forwarded provider."
          },
          "variant_source": {
            "type": "string",
            "enum": [
              "declared",
              "candidate",
              "inferred",
              "default"
            ],
            "description": "declared: an operator recorded the variant. candidate: the model is the weights of a day-zero candidate. inferred: nobody has classified the model and its name says its refusals were removed, so it is treated as abliterated. default: no record, treated as mainstream."
          },
          "license": {
            "type": [
              "string",
              "null"
            ],
            "description": "License identifier from the weights' model card, when an operator recorded one."
          },
          "base_model": {
            "type": [
              "string",
              "null"
            ],
            "description": "The model these weights derive from."
          },
          "weights": {
            "type": [
              "object",
              "null"
            ],
            "description": "Where the weights came from, as recorded by the operator.",
            "properties": {
              "source": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "For example huggingface:owner/repo."
              },
              "revision": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Commit the weights were taken from."
              },
              "digest": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "sha256:<hex> of the weights, when recorded (for a day-zero model, the model digest in the provider's verified attestation)."
              }
            }
          },
          "creator_handle": {
            "type": [
              "string",
              "null"
            ],
            "description": "Hugging Face handle of the uploader."
          },
          "attestation": {
            "$ref": "#/components/schemas/ModelAttestation"
          },
          "datacenter_region": {
            "type": [
              "string",
              "null"
            ],
            "description": "The one datacenter region every live endpoint of the model reports; null when any endpoint does not report one or they differ."
          },
          "routing_variants": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "nitro",
                "floor",
                "free",
                "private"
              ]
            },
            "description": "Model suffixes that change how this model is routed right now: nitro (fastest providers first, as provider.sort throughput) and floor (cheapest first, as provider.sort price) always; free while a free endpoint serves it; private while an endpoint has a fresh TEE attestation."
          },
          "early_access": {
            "$ref": "#/components/schemas/EarlyAccess"
          }
        }
      },
      "ModelAttestation": {
        "type": [
          "object",
          "null"
        ],
        "description": "What the strongest live endpoint serving the model has proven. Every value comes from the router's own attestation and measurement records; a value that is not known is null, never filled in. null when no endpoint serves the model.",
        "required": [
          "best",
          "manifest_ref",
          "exec_profile_id",
          "policy_hash"
        ],
        "properties": {
          "best": {
            "type": "string",
            "enum": [
              "attested",
              "policy",
              "vendor-forwarded"
            ],
            "description": "The strongest disclosure class any live endpoint is served under right now (the same value as disclosure.best)."
          },
          "manifest_ref": {
            "type": [
              "object",
              "null"
            ],
            "description": "Where that endpoint's measured image is recorded, while its attestation is fresh. null when neither is known.",
            "properties": {
              "rekor_entry": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The transparency log entry uuid, once its inclusion proof was checked."
              },
              "registry_tx": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The on-chain MeasurementRegistry transaction, once the registry reports the measurement."
              }
            }
          },
          "exec_profile_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The attested execution profile. null until an attestation the router checks reports one."
          },
          "policy_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "The classifier policy hash that endpoint's fresh attestation bound (as sent in X-Trellis-Policy-Hash), else null."
          }
        }
      },
      "StructuredOutputOptions": {
        "type": "object",
        "properties": {
          "json_check": {
            "type": "string",
            "enum": [
              "validate",
              "repair"
            ],
            "description": "V83: Requires STRUCTURED_OUTPUT_CHECK_ENABLED (default false; switched on at trellis.example). validate checks the final JSON; repair permits one correction by the same routed model/provider. Both calls are billed normally. Streaming repair validates only. Requires json_object or json_schema and n=1; no council or dual verification. Non-streaming repair requires a bearer API key and bypasses the response cache. Explicit request settings override preset defaults."
          }
        }
      },
      "StructuredOutputIssue": {
        "type": "object",
        "required": [
          "path",
          "reason"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "JSON Pointer path; empty string is the root."
          },
          "reason": {
            "type": "string"
          }
        }
      },
      "StructuredOutputResult": {
        "type": "object",
        "description": "V83: Unsigned response metadata; not written to generation receipts or returned by receipt lookup. Existing batch outputs may retain it with the answer. Original signed payload/sig/v2 stay intact. Top-level usage is for the returned call only; total_cost includes both served calls even if the correction is invalid. Checks do not establish factual accuracy. Supported schema assertions: type (including arrays), nullable, properties, required, additionalProperties, items, enum, const, anyOf, minLength/maxLength, minimum/maximum/exclusiveMinimum/exclusiveMaximum, minItems/maxItems, minProperties/maxProperties, and existing local #/ references via $defs/definitions. Unknown assertions are refused before billing. Limits: 1 MiB answer, 4096 schema nodes, 100000 validation steps, 64 levels, 16 reported errors. Oversized/non-text answers cannot be repaired.",
        "required": [
          "mode",
          "valid",
          "errors",
          "retry_attempted",
          "calls",
          "total_cost"
        ],
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "validate",
              "repair"
            ]
          },
          "valid": {
            "type": "boolean"
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StructuredOutputIssue"
            }
          },
          "initial_errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StructuredOutputIssue"
            }
          },
          "retry_attempted": {
            "type": "boolean"
          },
          "retry_error": {
            "type": "object",
            "description": "Correction did not return a usable answer. The first charge remains, and a signed correction charge is included even if its attestation was refused after settlement. status when known, reason."
          },
          "repair_supported": {
            "type": "boolean",
            "description": "false for streaming repair; no second call is made."
          },
          "note": {
            "type": "string"
          },
          "calls": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2,
            "items": {
              "type": "object",
              "required": [
                "attempt",
                "cost",
                "receipt"
              ],
              "properties": {
                "attempt": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 2
                },
                "cost": {
                  "type": "string",
                  "description": "Exact USDC charge for this call."
                },
                "receipt": {
                  "$ref": "#/components/schemas/Receipt"
                }
              }
            }
          },
          "total_cost": {
            "type": "string",
            "description": "Sum of the served calls' USDC charges."
          }
        }
      },
      "ChatRequest": {
        "type": "object",
        "required": [
          "messages"
        ],
        "anyOf": [
          {
            "required": [
              "model"
            ]
          },
          {
            "required": [
              "models"
            ]
          }
        ],
        "properties": {
          "trellis": {
            "$ref": "#/components/schemas/StructuredOutputOptions"
          },
          "model": {
            "type": "string",
            "description": "Public model ID, optionally with routing suffixes: :nitro sorts providers by throughput (fastest first) and :floor by price (cheapest first), the same as provider.sort throughput and price and winning over it; both only order the providers the other preferences and the lane allow. :free and :private also apply. The reserved ID trellis/council selects council mode when the router enables it. @route/<slug> calls a saved route and @preset/<name> (or @preset/<name>@<version> to pin one version) calls a preset of the key's account. @character/<id> calls a character: the card is the prompt and models[0], or the character's default model, answers."
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Ordered candidate model IDs."
          },
          "messages": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "role"
              ],
              "properties": {
                "role": {
                  "type": "string",
                  "enum": [
                    "system",
                    "developer",
                    "user",
                    "assistant",
                    "tool",
                    "function"
                  ]
                },
                "content": {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            }
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "The output cap. Optional: the router always sends a cap to the provider, the smallest of this value, the catalog's output limit for the model (16,384 when the catalog has none) and the room the context leaves after the prompt bound. A higher value is clamped, not refused; an omitted value is filled in. The cap is what the hold prices, so a lower value lowers the hold."
          },
          "max_completion_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Same as max_tokens; the smaller of the two applies when both are sent. Sent to the provider, set to the cap, when the caller sent it."
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Requires a model/provider that supports tools."
          },
          "tool_choice": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object"
              }
            ]
          },
          "response_format": {
            "type": "object",
            "description": "Requires a model/provider that supports the requested response format."
          },
          "provider": {
            "$ref": "#/components/schemas/ProviderPreferences"
          },
          "council": {
            "$ref": "#/components/schemas/CouncilRequest"
          },
          "verify": {
            "type": "string",
            "enum": [
              "dual"
            ],
            "description": "Send the same request to two providers of the model at temperature 0 with a fixed seed and compare the outputs. Both calls are billed. Needs the router's council feature; not combinable with stream, models, cache or n above 1. Provider preferences, disclosure ceiling and lane apply to both calls. With lane attested the two calls go to two different attested providers of the model (retention declared attested, attestation fresh); each receipt then records its provider's attestation as payload.attestation_ref, and the verification field carries attested and attestation_refs next to agree. If two such providers do not exist the answer is 409, and nothing is sent or charged."
          }
        },
        "additionalProperties": true
      },
      "CouncilRequest": {
        "type": "object",
        "description": "Used with model trellis/council. Members are called in parallel through the normal routing path, then the judge chooses one answer (judge) or writes a final one (fuse). Every call is billed and receipted; the worst case of all calls is held up front. provider preferences, including a disclosure ceiling or lane, apply to every member and to the judge.",
        "properties": {
          "models": {
            "type": "array",
            "minItems": 2,
            "maxItems": 5,
            "uniqueItems": true,
            "items": {
              "type": "string"
            },
            "description": "Member model IDs. Falls back to the router's configured default when omitted."
          },
          "judge": {
            "type": "string",
            "description": "Model ID of the judge. Falls back to the router's configured default when omitted."
          },
          "mode": {
            "type": "string",
            "enum": [
              "judge",
              "fuse"
            ],
            "default": "judge",
            "description": "judge returns one member's answer unchanged; fuse returns the judge's own text and does not support tools or response_format."
          },
          "max_cost_usd": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Refuse the request with 402 council_budget_exceeded unless the worst case of every call fits. Lower max_tokens to fit."
          },
          "min_members": {
            "type": "integer",
            "minimum": 2,
            "description": "Members that must answer before the judge runs. Defaults to 2."
          },
          "attested": {
            "type": "boolean",
            "default": false,
            "description": "true holds every member and the judge to the attested lane (retention declared attested and a fresh attestation the router verified), the same as provider.lane attested for the whole council. Nothing is downgraded or dropped: a member, or the judge, with no attested provider refuses the request with 503 no_attested_endpoint, and nothing is sent or charged. The response then carries attested and attestation_refs in council, and each call's receipt carries attestation_ref. A production router has few attested providers today, so this often returns that 503."
          }
        },
        "additionalProperties": false
      },
      "CouncilResult": {
        "type": "object",
        "description": "Present on council responses. The top-level receipt is the judge's call and its signed payload carries the same members list; its disclosure is the weakest class among all the calls.",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "judge",
              "fuse"
            ]
          },
          "members": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "model": {
                  "type": "string"
                },
                "provider": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "disclosure": {
                  "type": "string",
                  "enum": [
                    "attested",
                    "policy",
                    "vendor-forwarded"
                  ],
                  "description": "The class this member was served under."
                },
                "receipt_id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Null for a member that failed; it was not billed."
                },
                "cost": {
                  "type": "string",
                  "description": "USD charged for this member."
                },
                "latency_ms": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "ok",
                    "failed"
                  ]
                },
                "error": {
                  "type": "string"
                }
              }
            }
          },
          "judge": {
            "type": "object",
            "properties": {
              "model": {
                "type": "string"
              },
              "provider": {
                "type": "string"
              },
              "disclosure": {
                "type": "string",
                "enum": [
                  "attested",
                  "policy",
                  "vendor-forwarded"
                ]
              },
              "receipt_id": {
                "type": "string"
              },
              "cost": {
                "type": "string"
              },
              "latency_ms": {
                "type": "integer"
              },
              "request_sha256": {
                "type": "string"
              }
            }
          },
          "selected": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "label": {
                "type": "string"
              },
              "receipt_id": {
                "type": "string"
              }
            }
          },
          "outcome": {
            "type": "string",
            "enum": [
              "selected",
              "fused"
            ]
          },
          "members_cost": {
            "type": "string"
          },
          "total_cost": {
            "type": "string",
            "description": "USD charged across every member and the judge."
          },
          "answer_sha256": {
            "type": "string"
          },
          "attested": {
            "type": "boolean",
            "description": "Present when the council ran on the attested lane (council.attested true, or lane attested). True only when every member and the judge were served under the attested class and each has a reference in attestation_refs. Signed in the top-level receipt."
          },
          "attestation_simulated": {
            "type": "boolean",
            "description": "True when any attestation behind the council is a development report; a production router never accepts one."
          },
          "attestation_refs": {
            "type": "array",
            "description": "One entry per call that took part, members in order and then the judge: what the router itself verified about the provider that served it. Signed in the top-level receipt.",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/AttestationRef"
                },
                {
                  "type": "object",
                  "properties": {
                    "role": {
                      "type": "string",
                      "enum": [
                        "member",
                        "judge"
                      ]
                    },
                    "label": {
                      "type": "string",
                      "description": "The member's label; absent for the judge."
                    },
                    "receipt_id": {
                      "type": "string",
                      "description": "The receipt of that call."
                    }
                  }
                }
              ]
            }
          }
        },
        "additionalProperties": true
      },
      "AttestationRef": {
        "type": "object",
        "description": "The attestation the router had verified for a provider when it served a call: the hash of the attestation report and, when the provider attested through a self-signed TLS certificate, the pinned key the router's connection to it accepts. Recorded in the signed receipt of a call made under an attested council or attested dual verification, as payload.attestation_ref. Receipts made any other way do not carry it. The same data is at GET /api/v1/attestation/{providerId}.",
        "required": [
          "provider",
          "report_hash",
          "tls_pin"
        ],
        "properties": {
          "provider": {
            "type": "string"
          },
          "tee": {
            "type": [
              "string",
              "null"
            ],
            "description": "tdx, snp, nvidia-cc, tinfoil or dev."
          },
          "report_hash": {
            "type": "string",
            "description": "Hash of the attestation report the router verified (the payload.attestation field of the same receipt)."
          },
          "attested_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "tls_pin": {
            "type": [
              "object",
              "null"
            ],
            "description": "Null when the provider did not attest through a self-signed certificate.",
            "properties": {
              "spki_sha256": {
                "type": "string",
                "description": "SHA-256 of the pinned certificate's SubjectPublicKeyInfo."
              },
              "attestation_ref": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "SHA-256 of the quote the certificate names."
              }
            }
          },
          "simulated": {
            "type": "boolean",
            "description": "true when the report is development evidence."
          }
        }
      },
      "VerificationResult": {
        "type": "object",
        "description": "Present on verify \"dual\" responses. agree is true when both providers returned the same output (exactly, or after whitespace is collapsed); it says nothing about whether either provider is attested, unless the request used lane attested (then attested and attestation_refs say so). The response body is the first provider's output.",
        "properties": {
          "providers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 2,
            "maxItems": 2
          },
          "agree": {
            "type": "boolean"
          },
          "match": {
            "type": "string",
            "enum": [
              "exact",
              "normalized",
              "none"
            ]
          },
          "receipts": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 2,
            "maxItems": 2
          },
          "seed": {
            "type": "integer"
          },
          "temperature": {
            "type": "number",
            "enum": [
              0
            ]
          },
          "quantizations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "attested": {
            "type": "boolean",
            "description": "Present only on lane attested. True when both calls were served by two different providers under the attested class and each has a reference in attestation_refs. Signed in both receipts, next to agree."
          },
          "attestation_refs": {
            "type": "array",
            "description": "One entry per call that ran (label A or B), in the same order as receipts. Each receipt also carries its own provider's reference as payload.attestation_ref.",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/AttestationRef"
                },
                {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "receipt_id": {
                      "type": "string"
                    }
                  }
                }
              ]
            }
          }
        },
        "additionalProperties": true
      },
      "EmbeddingRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "input": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "minItems": 1,
                "maxItems": 2048,
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "provider": {
            "$ref": "#/components/schemas/ProviderPreferences"
          }
        }
      },
      "ProviderPreferences": {
        "type": "object",
        "description": "Provider routing preferences (order, only, ignore, sort, max_price, private and others) plus the disclosure options below.",
        "additionalProperties": true,
        "properties": {
          "disclosure": {
            "type": "string",
            "enum": [
              "none",
              "policy",
              "any"
            ],
            "default": "any",
            "description": "Ceiling on how a prompt may be handled. none: only providers whose retention is declared attested and whose TEE attestation is fresh. policy: those, plus providers with a documented no-retention policy and no legal hold. any: no filter. Never silently relaxed: if nothing qualifies the request fails (409, or 503 when qualifying providers are down). A request with a ceiling never uses the response cache."
          },
          "lane": {
            "type": "string",
            "enum": [
              "public",
              "attested",
              "unlinkable"
            ],
            "default": "public",
            "description": "public: any endpoint; attested endpoints get attested_bonus (default 1.25) in the selection weight. attested: only endpoints with attested retention and a fresh, verified attestation, with no fallback to any other (503 no_attested_endpoint). unlinkable: the same endpoints, and only for a request that arrived through the Oblivious HTTP gateway by way of an independent relay (see Oblivious HTTP), or through the router's Tor onion service where it serves the lane that way, and is paid with a blind token; 501 where the router serves the lane on neither path, 403 lane_requires_anonymous_auth for an API key or a wallet, 403 unlinkable_requires_relay or unlinkable_requires_independent_relay, 401 unlinkable_requires_token otherwise. Unset: the key's default (routing.provider.lane), then the saved route's, then public; a request through an independent relay paid with a blind token defaults to unlinkable. provider.order, only and ignore still apply inside a lane. On attested and unlinkable the router still terminates TLS and sees the prompt; end-to-end encryption through the router is planned."
          },
          "lane_downgrade": {
            "type": "string",
            "enum": [
              "none",
              "attested"
            ],
            "default": "none",
            "description": "attested: a request for lane unlinkable that carries an API key or a wallet is served on lane attested instead of being refused with lane_requires_anonymous_auth. Never downgrades to public. Same as the X-Trellis-Lane-Downgrade header; none in either refuses the downgrade."
          }
        }
      },
      "DisclosureClaim": {
        "type": "object",
        "required": [
          "source",
          "as_of"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "The document or statement the value comes from."
          },
          "as_of": {
            "type": "string",
            "format": "date",
            "description": "The date the source was checked."
          }
        }
      },
      "DisclosureProfile": {
        "type": "object",
        "required": [
          "provider",
          "declared",
          "retention",
          "jurisdiction",
          "legal_hold",
          "training_use",
          "claims",
          "current"
        ],
        "properties": {
          "provider": {
            "type": "string"
          },
          "declared": {
            "type": "boolean",
            "description": "False when the operator has recorded nothing; every value is then the conservative default."
          },
          "retention": {
            "type": "string",
            "enum": [
              "attested",
              "policy",
              "logs"
            ],
            "description": "attested: the provider states prompts are not retained and runs in a TEE. policy: a documented no-retention policy. logs: prompts may be logged (default)."
          },
          "jurisdiction": {
            "type": "string",
            "description": "Where the operator is subject to legal process; unknown by default."
          },
          "legal_hold": {
            "type": "object",
            "properties": {
              "active": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "null = not declared. A no-retention policy is not trusted while a hold is active or undeclared."
              },
              "note": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "training_use": {
            "type": "string",
            "enum": [
              "none",
              "opt_in",
              "yes",
              "unknown"
            ]
          },
          "claims": {
            "type": "object",
            "description": "The source and date behind each value; null when the value is a default.",
            "properties": {
              "retention": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/DisclosureClaim"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "jurisdiction": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/DisclosureClaim"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "legal_hold": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/DisclosureClaim"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "training_use": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/DisclosureClaim"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "current": {
            "type": "object",
            "properties": {
              "class": {
                "type": "string",
                "enum": [
                  "attested",
                  "policy",
                  "vendor-forwarded"
                ]
              },
              "attestation_fresh": {
                "type": "boolean"
              },
              "tee": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "simulated": {
                "type": "boolean",
                "description": "True when the attestation behind an attested class is a development report."
              }
            }
          }
        }
      },
      "DisclosureInput": {
        "type": "object",
        "additionalProperties": false,
        "description": "Every claim is optional and carries its own source and date.",
        "properties": {
          "retention": {
            "type": "object",
            "required": [
              "value",
              "source",
              "as_of"
            ],
            "properties": {
              "value": {
                "type": "string",
                "enum": [
                  "attested",
                  "policy",
                  "logs"
                ]
              },
              "source": {
                "type": "string"
              },
              "as_of": {
                "type": "string",
                "format": "date"
              }
            }
          },
          "jurisdiction": {
            "type": "object",
            "required": [
              "value",
              "source",
              "as_of"
            ],
            "properties": {
              "value": {
                "type": "string",
                "minLength": 2,
                "maxLength": 64
              },
              "source": {
                "type": "string"
              },
              "as_of": {
                "type": "string",
                "format": "date"
              }
            }
          },
          "legal_hold": {
            "type": "object",
            "required": [
              "active",
              "source",
              "as_of"
            ],
            "properties": {
              "active": {
                "type": "boolean"
              },
              "note": {
                "type": "string",
                "maxLength": 500
              },
              "source": {
                "type": "string"
              },
              "as_of": {
                "type": "string",
                "format": "date"
              }
            }
          },
          "training_use": {
            "type": "object",
            "required": [
              "value",
              "source",
              "as_of"
            ],
            "properties": {
              "value": {
                "type": "string",
                "enum": [
                  "none",
                  "opt_in",
                  "yes"
                ]
              },
              "source": {
                "type": "string"
              },
              "as_of": {
                "type": "string",
                "format": "date"
              }
            }
          }
        }
      },
      "KeyCreateRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "limit": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "USD budget; alias of budget_usd."
          },
          "budget_usd": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          },
          "limit_reset": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "daily",
              "weekly",
              "monthly",
              null
            ]
          },
          "rpm": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          },
          "tpm": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          },
          "allowed_models": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "team": {
            "type": [
              "string",
              "null"
            ],
            "description": "Applies to authenticated management-key creation."
          },
          "pay_with_default": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 16
          },
          "disabled": {
            "type": "boolean"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "guardrails": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "pii": {
                "type": "string",
                "enum": [
                  "redact",
                  "block"
                ]
              },
              "deny_patterns": {
                "type": "array",
                "maxItems": 50,
                "items": {
                  "type": "string"
                }
              },
              "max_input_chars": {
                "type": "integer",
                "minimum": 1
              },
              "redact_output": {
                "type": "boolean"
              }
            }
          },
          "routing": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "management": {
            "type": "boolean",
            "description": "Only honored for authorized authenticated sub-key creation; root-key management is never granted by this field."
          },
          "tracing": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TracingSettings"
              },
              {
                "type": "null"
              }
            ],
            "description": "Trace export for this key's public-lane calls; null removes it."
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "dev",
              "member",
              "viewer",
              "agent"
            ],
            "description": "The new key's role in its team (default member). A key cannot hand out a role above its own. In a team with an org budget every key needs a limit that fits."
          },
          "topup": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/KeyTopup"
              },
              {
                "type": "null"
              }
            ],
            "description": "PATCH only. Auto top-up of this key's limit from the account's credits; null clears it. The key needs a limit without limit_reset."
          }
        },
        "additionalProperties": false
      },
      "KeyTopup": {
        "type": "object",
        "description": "When the key has less than below_usd of its limit left, the router raises the limit by add_usd, at most max_per_week_usd per UTC week (Monday to Sunday), and only while the account's available credits cover the key's remaining allowance after it. No money moves. It runs after a debit and when the key's limit would refuse a request. Each top-up, or skipped top-up with its reason, shows in Activity (kind topup) and the inbox. Rulebook caps still apply.",
        "required": [
          "below_usd",
          "add_usd",
          "max_per_week_usd"
        ],
        "properties": {
          "below_usd": {
            "type": "number",
            "minimum": 0.01,
            "maximum": 1000
          },
          "add_usd": {
            "type": "number",
            "minimum": 0.01,
            "maximum": 1000,
            "description": "At most max_per_week_usd."
          },
          "max_per_week_usd": {
            "type": "number",
            "minimum": 0.01,
            "maximum": 5000
          }
        },
        "additionalProperties": false
      },
      "Key": {
        "type": "object",
        "required": [
          "hash",
          "name",
          "disabled",
          "created_at"
        ],
        "properties": {
          "hash": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "disabled": {
            "type": "boolean"
          },
          "limit": {
            "type": [
              "number",
              "null"
            ]
          },
          "usage": {
            "type": "number"
          },
          "allowed_models": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "tracing": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Tracing"
              },
              {
                "type": "null"
              }
            ]
          },
          "topup": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/KeyTopup"
              },
              {
                "type": "null"
              }
            ]
          },
          "topups_this_week_usd": {
            "type": "number",
            "description": "GET /api/v1/keys/{hash} and PATCH: the auto top-ups added to this key's limit since Monday 00:00 UTC."
          }
        }
      },
      "GenerationSummary": {
        "type": "object",
        "required": [
          "id",
          "created_at",
          "model",
          "total_cost"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "model": {
            "type": "string"
          },
          "provider_name": {
            "type": "string"
          },
          "tokens_prompt": {
            "type": "integer"
          },
          "tokens_completion": {
            "type": "integer"
          },
          "total_cost": {
            "type": "number"
          },
          "streamed": {
            "type": "boolean"
          },
          "cancelled": {
            "type": "boolean"
          }
        }
      },
      "ReceiptKeys": {
        "type": "object",
        "required": [
          "keys"
        ],
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "kty",
                "crv",
                "x",
                "kid"
              ],
              "properties": {
                "kty": {
                  "const": "OKP"
                },
                "crv": {
                  "const": "Ed25519"
                },
                "x": {
                  "type": "string",
                  "description": "The raw 32-byte public key, base64url."
                },
                "kid": {
                  "type": "string",
                  "description": "First 16 hex characters of SHA-256 of the raw key."
                },
                "use": {
                  "const": "sig"
                },
                "alg": {
                  "const": "EdDSA"
                },
                "valid_from": {
                  "type": "string",
                  "format": "date-time"
                },
                "retired_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "onchain_tx": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "anchor": {
            "type": "object",
            "description": "Where receipt roots are posted and which key signs them. Not signed: use it as your own configuration only when you fetched it yourself from the router's origin, and pin the first anchorer key.",
            "properties": {
              "mode": {
                "enum": [
                  "memo",
                  "program"
                ]
              },
              "network": {
                "type": "string",
                "description": "The cluster's CAIP-2 id: solana:<first 32 characters of the genesis hash>. A verifier compares it with getGenesisHash of the RPC it uses."
              },
              "program": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Program mode: the trellis_anchor program id."
              },
              "memo_program": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "anchorer": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The current anchorer key."
              },
              "anchorers": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "key",
                    "from_hour"
                  ],
                  "properties": {
                    "key": {
                      "type": "string"
                    },
                    "from_hour": {
                      "type": "integer",
                      "description": "Unix seconds on an hour boundary; 0 for the first key."
                    },
                    "rotation_tx": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The transaction in which the key before this one and this key signed trellis:anchorer:v1:<network>:<from hour>:<key>."
                    }
                  }
                }
              },
              "memo_v2_from_hour": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Memo mode: root lines of this hour and later are v2 lines (trellis:root:v2:<network>:<hour>:<count>:<root>:<previous root's transaction, or 0>)."
              },
              "max_late_seconds": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Memo mode: a root that lands later than this after its hour closed is late and is not an anchor."
              }
            }
          }
        }
      },
      "AttestationSummary": {
        "type": "object",
        "required": [
          "generated_at",
          "attestation_interval_ms",
          "fresh_within_ms",
          "history_days",
          "providers"
        ],
        "properties": {
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "attestation_interval_ms": {
            "type": "integer"
          },
          "fresh_within_ms": {
            "type": "integer",
            "description": "How old a verified attestation may be and still count as fresh."
          },
          "history_days": {
            "type": "integer"
          },
          "providers": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "provider",
                "name",
                "status",
                "fresh"
              ],
              "properties": {
                "provider": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "attested",
                    "simulated",
                    "unverified"
                  ]
                },
                "reason": {
                  "type": "string",
                  "description": "Present when status is unverified."
                },
                "tee": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "attested_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "history_since": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time",
                  "description": "The first recorded attestor run."
                },
                "runs_7d": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "attested": {
                      "type": "integer",
                      "description": "Runs that passed with hardware evidence (simulated evidence is not counted)."
                    },
                    "attested_pct": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  }
                },
                "fresh": {
                  "type": "object",
                  "required": [
                    "24h",
                    "7d"
                  ],
                  "properties": {
                    "24h": {
                      "type": "object",
                      "required": [
                        "share",
                        "observed_ms",
                        "observed_from",
                        "history_complete",
                        "buckets"
                      ],
                      "properties": {
                        "share": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "minimum": 0,
                          "maximum": 1,
                          "description": "Covered part of the time the record spans within the window; null when nothing is recorded."
                        },
                        "observed_ms": {
                          "type": "integer",
                          "description": "How much of the window the record spans."
                        },
                        "observed_from": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "history_complete": {
                          "type": "boolean",
                          "description": "False when the record does not reach back to the start of the window; the earlier time is unknown, not covered and not uncovered."
                        },
                        "buckets": {
                          "type": "array",
                          "items": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "minimum": 0,
                            "maximum": 100
                          },
                          "description": "Equal slices from the start of the window to now (48 for 24h, 84 for 7d): percent covered, or null before the record begins."
                        }
                      }
                    },
                    "7d": {
                      "type": "object",
                      "required": [
                        "share",
                        "observed_ms",
                        "observed_from",
                        "history_complete",
                        "buckets"
                      ],
                      "properties": {
                        "share": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "minimum": 0,
                          "maximum": 1,
                          "description": "Covered part of the time the record spans within the window; null when nothing is recorded."
                        },
                        "observed_ms": {
                          "type": "integer",
                          "description": "How much of the window the record spans."
                        },
                        "observed_from": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "history_complete": {
                          "type": "boolean",
                          "description": "False when the record does not reach back to the start of the window; the earlier time is unknown, not covered and not uncovered."
                        },
                        "buckets": {
                          "type": "array",
                          "items": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "minimum": 0,
                            "maximum": 100
                          },
                          "description": "Equal slices from the start of the window to now (48 for 24h, 84 for 7d): percent covered, or null before the record begins."
                        }
                      }
                    }
                  }
                },
                "measurement": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "digests": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Digests only: image_digest, compose_hash, model_digest, mrtd, rtmr0 to rtmr3, measurement.",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  }
                },
                "measurement_changes_7d": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "at": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "changed": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "last_measurement_change": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "changed": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "from": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Digests only: image_digest, compose_hash, model_digest, mrtd, rtmr0 to rtmr3, measurement.",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "to": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Digests only: image_digest, compose_hash, model_digest, mrtd, rtmr0 to rtmr3, measurement.",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  }
                },
                "last_failure": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "probe": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "description": "The latest health-probe outcome and when it began.",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "since": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "reason": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "A code from a fixed list with its message; never the provider's own text.",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "canary": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "model": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "reason": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "A code from a fixed list with its message; never the provider's own text.",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "AttestationEvent": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "at",
          "ok"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "kind": {
            "type": "string",
            "enum": [
              "attestation",
              "canary",
              "probe"
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "ok": {
            "type": "boolean"
          },
          "reason": {
            "type": [
              "object",
              "null"
            ],
            "description": "A code from a fixed list with its message; never the provider's own text.",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "tee": {
            "type": [
              "string",
              "null"
            ]
          },
          "simulated": {
            "type": "boolean",
            "description": "Development evidence: never counted as a fresh attestation."
          },
          "attestation_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "tls_spki_sha256": {
            "type": [
              "string",
              "null"
            ],
            "description": "SPKI hash of the certificate the connection was pinned to, when it was."
          },
          "measurements": {
            "type": [
              "object",
              "null"
            ],
            "description": "Digests only: image_digest, compose_hash, model_digest, mrtd, rtmr0 to rtmr3, measurement.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "measurement_changed": {
            "type": "boolean",
            "description": "The run's digests differ from the previous accepted run's, comparing the fields both report."
          },
          "verifiers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "detail": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          }
        }
      },
      "AttestationHistory": {
        "type": "object",
        "required": [
          "provider",
          "history_days",
          "data",
          "next"
        ],
        "properties": {
          "provider": {
            "type": "string"
          },
          "history_days": {
            "type": "integer"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AttestationEvent"
            }
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as before for the next page; null on the last page."
          }
        }
      },
      "ProviderAttestation": {
        "type": "object",
        "required": [
          "provider",
          "status",
          "checks",
          "not_checked"
        ],
        "properties": {
          "provider": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "attested",
              "simulated",
              "unverified"
            ]
          },
          "reason": {
            "type": "string",
            "enum": [
              "no_attestation",
              "last_attempt_failed",
              "simulated_evidence_refused",
              "attestation_stale"
            ],
            "description": "Present when status is unverified."
          },
          "tee": {
            "type": [
              "string",
              "null"
            ]
          },
          "attested_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "attestation_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "verifiers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The verifiers that accepted the quote; empty unless status is attested."
          },
          "policy_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "The classifier policy hash this fresh attestation bound (the value sent as X-Trellis-Policy-Hash); null unless status is attested and one was bound."
          },
          "measurement": {
            "type": [
              "object",
              "null"
            ],
            "description": "Last recorded digests (image_digest, compose_hash, model_digest), status, attested_now, registers { mrtd, rtmr3 } of the recorded quote, transparency_log { found, inclusion_verified, checkpoint_signature_verified, subject (measurement_bundle or image_digest), entry_url, bundle, ... } and registry { address, state, tx_hash, registered_at }.",
            "additionalProperties": true
          },
          "checks": {
            "type": "object",
            "required": [
              "quote_verified",
              "digests_bound_to_quote",
              "transparency_log_entry",
              "transparency_log_checkpoint_signature",
              "registered_on_chain"
            ],
            "additionalProperties": {
              "type": "boolean"
            }
          },
          "not_checked": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "RouteExplanation": {
        "type": "object",
        "additionalProperties": false,
        "description": "Versioned additive router statement, not an independent selection proof. eligible counts final-plan candidate offers before attempt limits for the serving model; skipped counts its exclusions. Fallback error classes cover earlier attempts, including earlier models, without raw errors or provider identities. No URLs, keys, addresses, content or weights. Both receipt signatures cover route.",
        "required": [
          "v",
          "provider",
          "reason",
          "eligible",
          "skipped",
          "lane",
          "parameters",
          "network_host"
        ],
        "properties": {
          "v": {
            "type": "integer",
            "const": 1
          },
          "provider": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,96}$"
          },
          "reason": {
            "type": "string",
            "enum": [
              "lowest_price",
              "lowest_latency",
              "highest_throughput",
              "weighted_choice",
              "provider_order",
              "preferred_performance",
              "byok_priority",
              "only_eligible",
              "only_parameter_support",
              "fallback"
            ]
          },
          "eligible": {
            "type": "integer",
            "minimum": 1
          },
          "skipped": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "health": {
                "type": "integer",
                "minimum": 1
              },
              "lane": {
                "type": "integer",
                "minimum": 1
              },
              "disclosure": {
                "type": "integer",
                "minimum": 1
              },
              "attestation": {
                "type": "integer",
                "minimum": 1
              },
              "parameters": {
                "type": "integer",
                "minimum": 1
              },
              "price": {
                "type": "integer",
                "minimum": 1
              },
              "context": {
                "type": "integer",
                "minimum": 1
              },
              "preferences": {
                "type": "integer",
                "minimum": 1
              },
              "availability": {
                "type": "integer",
                "minimum": 1
              },
              "other": {
                "type": "integer",
                "minimum": 1
              }
            }
          },
          "lane": {
            "type": "string",
            "enum": [
              "public",
              "attested",
              "unlinkable"
            ]
          },
          "parameters": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "tools",
                "tool_choice",
                "response_format",
                "temperature",
                "seed",
                "max_tokens",
                "stop",
                "top_p",
                "top_k",
                "reasoning",
                "include_reasoning",
                "modalities",
                "audio"
              ]
            }
          },
          "network_host": {
            "type": "boolean"
          },
          "fallback": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "http_5xx": {
                "type": "integer",
                "minimum": 1
              },
              "timeout": {
                "type": "integer",
                "minimum": 1
              },
              "connection": {
                "type": "integer",
                "minimum": 1
              },
              "rate_limited": {
                "type": "integer",
                "minimum": 1
              },
              "provider_auth": {
                "type": "integer",
                "minimum": 1
              },
              "rejected": {
                "type": "integer",
                "minimum": 1
              },
              "empty200": {
                "type": "integer",
                "minimum": 1
              },
              "unreadable": {
                "type": "integer",
                "minimum": 1
              },
              "interrupted": {
                "type": "integer",
                "minimum": 1
              },
              "other": {
                "type": "integer",
                "minimum": 1
              }
            }
          }
        }
      },
      "Receipt": {
        "type": "object",
        "properties": {
          "structured_output": {
            "$ref": "#/components/schemas/StructuredOutputResult"
          },
          "id": {
            "type": "string"
          },
          "payload": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "route": {
                "$ref": "#/components/schemas/RouteExplanation"
              },
              "decision_tag": {
                "type": "string",
                "pattern": "^sha256:[0-9a-f]{64}$",
                "description": "The caller's X-Trellis-Decision-Tag, when DECISION_TAGS_ENABLED is true."
              },
              "cost_details": {
                "type": "object",
                "additionalProperties": true,
                "description": "The parts of the charge as USD decimal strings (upstream, royalty, margin and others).",
                "properties": {
                  "over_hold": {
                    "type": "string",
                    "description": "Present only when the provider reported usage priced above the hold: the list price of the reported usage, as a USD decimal string. The caller was charged the hold (payload.cost), never more, and the provider was paid no more than that."
                  }
                }
              }
            },
            "description": "Signed fields. cost is what the caller was charged, which is never more than the hold taken before the call; cost_details.over_hold is present when a provider reported usage priced above that hold (on an encrypted chat receipt it is e2ee.over_hold). Optional route is a versioned additive claim when ROUTE_EXPLAIN_ENABLED is true (default false). Optional decision_tag is the caller-computed digest sent as X-Trellis-Decision-Tag (DECISION_TAGS_ENABLED, default false). Among them, disclosure (attested, policy or vendor-forwarded) and lane (public, attested or unlinkable) record how the call was served; attestation_simulated is true when the attestation behind an attested call is a development report. attestation_ref (see AttestationRef) is present on calls made under an attested council or attested dual verification. For a call paid with a blind token, payer is null and nullifier (the SHA-256 of the spent token) and token_key_id are present; nothing names an account. Receipts issued before these fields existed do not carry them."
          },
          "sig": {
            "type": "string"
          },
          "key_id": {
            "type": "string"
          },
          "leaf": {
            "type": [
              "string",
              "null"
            ]
          },
          "anchor": {
            "type": [
              "object",
              "null"
            ]
          },
          "version": {
            "type": "integer",
            "enum": [
              1,
              2
            ]
          },
          "v2": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ReceiptV2"
              },
              {
                "type": "null"
              }
            ]
          },
          "privacy": {
            "$ref": "#/components/schemas/PrivacyLabel",
            "description": "The privacy label derived from payload for readers. It is not part of what is signed."
          }
        }
      },
      "ReceiptV2": {
        "type": "object",
        "description": "Receipt v2 (spec 0004 Section 4): a COSE_Sign1 over deterministic CBOR claims, signed EdDSA with the same key as v1 (kid is the key id's 8 bytes). claims is the JSON view of exactly what cose signs. Token counts are bucketed; nothing names a payer, an address or content.",
        "properties": {
          "alg": {
            "type": "string",
            "const": "EdDSA"
          },
          "kid": {
            "type": "string"
          },
          "content_type": {
            "type": "string"
          },
          "cose": {
            "type": "string",
            "contentEncoding": "base64"
          },
          "leaf": {
            "type": "string",
            "description": "sha256(sha256(COSE bytes)), as 0x and 64 hex characters."
          },
          "anchor": {
            "type": [
              "object",
              "null"
            ]
          },
          "claims": {
            "$ref": "#/components/schemas/ReceiptClaimsV2"
          }
        }
      },
      "ReceiptClaimsV2": {
        "type": "object",
        "properties": {
          "route": {
            "$ref": "#/components/schemas/RouteExplanation"
          },
          "decision_tag": {
            "type": "string",
            "pattern": "^sha256:[0-9a-f]{64}$",
            "description": "Optional: the caller's X-Trellis-Decision-Tag (DECISION_TAGS_ENABLED)."
          },
          "v": {
            "type": "integer",
            "const": 2
          },
          "rid": {
            "type": "string"
          },
          "iat": {
            "type": "integer"
          },
          "iss": {
            "type": "string"
          },
          "model": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              }
            }
          },
          "node": {
            "type": "object",
            "properties": {
              "provider": {
                "type": "string"
              },
              "quote_ref": {
                "type": "string"
              },
              "policy_hash": {
                "type": "string"
              }
            }
          },
          "req": {
            "type": "object",
            "properties": {
              "h": {
                "type": "string"
              },
              "n_in_bucket": {
                "type": "string",
                "examples": [
                  "512-1024"
                ]
              }
            }
          },
          "resp": {
            "type": "object",
            "properties": {
              "h": {
                "type": "string"
              },
              "chain": {
                "type": "string",
                "description": "Streams only: the chunk hash chain head."
              },
              "n_out_bucket": {
                "type": "string"
              },
              "finish": {
                "type": "string"
              },
              "stream": {
                "type": "boolean"
              },
              "complete": {
                "type": "boolean"
              }
            }
          },
          "lane": {
            "type": "string"
          },
          "disclosure": {
            "type": "string"
          },
          "policy": {
            "type": "object",
            "description": "Present only when the serving endpoint's fresh attestation bound a classifier policy.",
            "properties": {
              "enforced": {
                "type": "boolean"
              },
              "blocked": {
                "type": "boolean"
              }
            }
          },
          "credit": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string"
              },
              "cost_units": {
                "type": "integer",
                "description": "Amount charged in millionths of a US dollar, rounded up."
              },
              "keyset": {
                "type": "string"
              }
            }
          }
        }
      },
      "ReceiptProof": {
        "type": "object",
        "properties": {
          "rid": {
            "type": "string"
          },
          "leaf": {
            "type": [
              "string",
              "null"
            ]
          },
          "leaf_version": {
            "type": "integer",
            "enum": [
              1,
              2
            ]
          },
          "rooted": {
            "type": "boolean"
          },
          "anchored": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "local",
              "confirmed"
            ]
          },
          "root": {
            "type": "string"
          },
          "anchor_index": {
            "type": "integer"
          },
          "leaf_index": {
            "type": "integer"
          },
          "proof": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "window": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "tx": {
            "type": [
              "string",
              "null"
            ]
          },
          "chain": {
            "type": "integer"
          },
          "contract": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "HostAnchorProof": {
        "type": "object",
        "required": [
          "leaf",
          "rooted",
          "anchored",
          "status",
          "provider",
          "provider_id_hash",
          "attestation_ref",
          "receipt_key",
          "root",
          "leaf_index",
          "proof"
        ],
        "properties": {
          "rid": {
            "type": "string",
            "description": "The receipt id the sidecar gave it."
          },
          "leaf": {
            "type": "string"
          },
          "rooted": {
            "type": "boolean",
            "const": true
          },
          "anchored": {
            "type": "boolean",
            "description": "True only when the root was posted on chain and confirmed."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "local",
              "confirmed"
            ],
            "description": "confirmed: on chain; pending: to be posted (the chain was unreachable); local: kept off chain because no chain is configured."
          },
          "provider": {
            "type": "string"
          },
          "provider_id_hash": {
            "type": "string",
            "description": "sha256 of the provider id's bytes: the providerId the root is posted under (trellis_anchor::post_host_root)."
          },
          "attestation_ref": {
            "type": "string",
            "description": "64 hex: SHA-256 of the boot quote the router verified, which every leaf in the root names."
          },
          "receipt_key": {
            "type": "object",
            "description": "The receipt key the quote binds; every leaf in the root verified under it.",
            "properties": {
              "key_id": {
                "type": "string"
              },
              "public_key": {
                "type": "string",
                "description": "Raw Ed25519 public key, hex."
              }
            }
          },
          "root_id": {
            "type": "integer"
          },
          "root": {
            "type": "string"
          },
          "leaf_index": {
            "type": "integer"
          },
          "proof": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Sorted-pair sha256 Merkle path (node = sha256(min || max)) from the leaf to the root."
          },
          "count": {
            "type": "integer"
          },
          "window": {
            "type": "object",
            "description": "When the router collected the root's leaves: [from, to).",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "anchor_index": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Index in ReceiptAnchor.attestedAnchors once posted."
          },
          "tx": {
            "type": [
              "string",
              "null"
            ]
          },
          "block": {
            "type": [
              "integer",
              "null"
            ]
          },
          "chain": {
            "type": "integer"
          },
          "contract": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ReceiptV2VerificationRequest": {
        "type": "object",
        "required": [
          "cose"
        ],
        "properties": {
          "cose": {
            "type": "string",
            "contentEncoding": "base64"
          },
          "request_sha256": {
            "type": "string"
          },
          "response_sha256": {
            "type": "string"
          },
          "chunks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "anchor": {
            "type": "object",
            "required": [
              "root",
              "proof"
            ],
            "properties": {
              "root": {
                "type": "string"
              },
              "proof": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "index": {
                "type": "integer"
              }
            }
          },
          "decision_tag": {
            "type": "string",
            "pattern": "^(sha256:)?[0-9a-fA-F]{64}$",
            "description": "Optional: the SHA-256 of your order, computed on your side as the decision-receipt helpers do (canonical JSON, sha256:<64 hex>). The result reports decision_tag (the tag the receipt's signed contents carry, or null) and decision_tag_valid (whether it equals this value; null when omitted), and valid is false when they differ. Only the hash is sent."
          }
        }
      },
      "ReceiptVerificationRequest": {
        "type": "object",
        "required": [
          "payload",
          "sig",
          "key_id"
        ],
        "properties": {
          "payload": {
            "type": "object",
            "additionalProperties": true
          },
          "sig": {
            "type": "string"
          },
          "key_id": {
            "type": "string"
          },
          "anchor": {
            "type": "object",
            "required": [
              "root",
              "proof"
            ],
            "properties": {
              "root": {
                "type": "string"
              },
              "proof": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "index": {
                "type": "integer"
              }
            }
          },
          "decision_tag": {
            "type": "string",
            "pattern": "^(sha256:)?[0-9a-fA-F]{64}$",
            "description": "Optional: the SHA-256 of your order, computed on your side as the decision-receipt helpers do (canonical JSON, sha256:<64 hex>). The result reports decision_tag (the tag the receipt's signed contents carry, or null) and decision_tag_valid (whether it equals this value; null when omitted), and valid is false when they differ. Only the hash is sent."
          }
        }
      },
      "SavedRouteConfig": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "models"
        ],
        "properties": {
          "models": {
            "type": "array",
            "minItems": 1,
            "maxItems": 8,
            "items": {
              "type": "string"
            },
            "description": "Catalog model ids in fallback order; no nested @route/."
          },
          "provider": {
            "type": [
              "object",
              "null"
            ],
            "description": "Provider preferences: order, only, ignore, allow_fallbacks, sort (price|latency|throughput), data_collection, zdr, require_parameters, max_price, and the privacy settings lane (public|attested) and disclosure (none|policy|any). For lane and disclosure the stricter of the route and the request applies, so a request can tighten a route but never loosen it; a route on the attested lane is served only by attested providers or refused. lane attested already implies disclosure none."
          },
          "params": {
            "type": [
              "object",
              "null"
            ],
            "description": "Default request parameters from a closed whitelist (temperature, top_p, top_k, min_p, top_a, frequency_penalty, presence_penalty, repetition_penalty, max_tokens, seed, stop, reasoning, verbosity). Prompt fields are rejected."
          }
        }
      },
      "SavedRoute": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "model",
          "name",
          "config"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{1,47}$"
          },
          "model": {
            "type": "string",
            "description": "Use as the request model, e.g. @route/my-coder."
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "config": {
            "$ref": "#/components/schemas/SavedRouteConfig"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SavedRouteInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "description": {
            "type": "string",
            "maxLength": 280
          },
          "config": {
            "$ref": "#/components/schemas/SavedRouteConfig"
          }
        }
      },
      "AgentSession": {
        "type": "object",
        "required": [
          "id",
          "status",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "ended",
              "expired",
              "budget_exhausted"
            ]
          },
          "key_label": {
            "type": "string"
          },
          "key_hash": {
            "type": "string"
          },
          "budget_usd": {
            "type": "number"
          },
          "spent_usd": {
            "type": "number"
          },
          "reserved_usd": {
            "type": "number"
          },
          "remaining_usd": {
            "type": "number"
          },
          "calls": {
            "type": "integer"
          },
          "last_call_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "allowed_models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "metadata": {
            "type": [
              "object",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "expires_at": {
            "type": "string"
          },
          "time_left_s": {
            "type": "integer"
          },
          "ended_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "end_reason": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "AgentSessionCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "budget_usd"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "budget_usd": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 1000
          },
          "ttl_minutes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1440,
            "default": 60
          },
          "allowed_models": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "string"
            },
            "description": "Catalog ids or @route/<slug>; must be within the creator's allowlist."
          },
          "metadata": {
            "type": "object",
            "description": "Labels only, at most 2 KB; prompt-like keys are refused."
          }
        }
      },
      "SpendReport": {
        "type": "object",
        "description": "Spend for the caller's scope (a management key sees its account; other keys see themselves). UTC calendar.",
        "properties": {
          "scope": {
            "type": "string"
          },
          "period": {
            "type": "string"
          },
          "group_by": {
            "type": "string"
          },
          "totals": {
            "type": "object"
          },
          "anomaly": {
            "type": "object"
          },
          "series": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string"
                },
                "cost_usd": {
                  "type": "number"
                },
                "requests": {
                  "type": "integer"
                }
              }
            }
          },
          "breakdown": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "budgets": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "SpendAlert": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "threshold",
              "budget_pct",
              "anomaly"
            ]
          },
          "window": {
            "type": "string",
            "enum": [
              "day",
              "week",
              "month"
            ]
          },
          "key_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "threshold_usd": {
            "type": [
              "number",
              "null"
            ]
          },
          "pct": {
            "type": [
              "integer",
              "null"
            ]
          },
          "multiplier": {
            "type": [
              "number",
              "null"
            ]
          },
          "webhook_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Masked as https://host/…"
          },
          "enabled": {
            "type": "boolean"
          },
          "last_fired_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "history": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "HolderTier": {
        "type": "object",
        "description": "One membership level. No field is an amount of money.",
        "required": [
          "name",
          "min",
          "rpm_multiplier",
          "tpm_multiplier",
          "max_agent_keys",
          "max_saved_routes",
          "max_batch_rows",
          "sealed_priority",
          "early_access_hours",
          "vote_weight",
          "credits_never_expire",
          "badge"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "min": {
            "type": "string",
            "description": "The threshold: the smallest balance that holds this tier, in whole tokens (decimal string). Holding more inside a tier adds nothing."
          },
          "rpm_multiplier": {
            "type": "number",
            "minimum": 1,
            "description": "Multiplies the key's requests-per-minute limit."
          },
          "tpm_multiplier": {
            "type": "number",
            "minimum": 1,
            "description": "Multiplies the key's tokens-per-minute limit."
          },
          "max_agent_keys": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "description": "Active Agent Session keys per account, when higher than the standard limit; null leaves the standard limit."
          },
          "max_saved_routes": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "description": "Saved routes and presets per account, when higher than the standard limit; null leaves the standard limit."
          },
          "max_batch_rows": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "description": "Lines in one batch, when higher than the standard limit; null leaves the standard limit."
          },
          "sealed_priority": {
            "type": "integer",
            "minimum": 0,
            "description": "Place in the sealed-lane admission queue when a host is full, and in Bushel purchase ordering; higher is served first, 0 is the standard place. A share of capacity is always kept for callers with no tier."
          },
          "early_access_hours": {
            "type": "integer",
            "minimum": 0,
            "description": "How long before a newly listed model's early-access window ends this tier may use it."
          },
          "vote_weight": {
            "type": "integer",
            "minimum": 0,
            "description": "The fixed weight of this tier's one vote in an advisory poll (0: no vote). Never the balance."
          },
          "credits_never_expire": {
            "type": "boolean",
            "description": "While a wallet holds this tier, the router sends no expiry notice or sweep for its key's credits."
          },
          "badge": {
            "type": "boolean",
            "description": "Whether an opted-in public agent profile may show the tier name."
          }
        }
      },
      "BlindKeys": {
        "type": "object",
        "required": [
          "token_type",
          "scheme",
          "challenge",
          "challenge_digest",
          "keys"
        ],
        "properties": {
          "token_type": {
            "const": 2
          },
          "scheme": {
            "const": "RSABSSA-SHA384-PSS-Deterministic"
          },
          "modulus_bits": {
            "type": "integer"
          },
          "issuer_name": {
            "type": "string"
          },
          "challenge": {
            "type": "string",
            "description": "The TokenChallenge (RFC 9577), base64url."
          },
          "challenge_digest": {
            "type": "string",
            "description": "SHA-256 of the challenge, hex; the challenge_digest field of every token."
          },
          "unit_price_usd": {
            "type": "string",
            "description": "USD per token-unit for keys created from now on; each key states its own value_usd."
          },
          "epoch_seconds": {
            "type": "integer"
          },
          "redeem_grace_seconds": {
            "type": "integer"
          },
          "max_batch": {
            "type": "integer"
          },
          "epoch": {
            "type": "integer"
          },
          "now": {
            "type": "string",
            "format": "date-time"
          },
          "keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BlindKey"
            }
          },
          "commitments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "epoch": {
                  "type": "integer"
                },
                "commitment": {
                  "type": "string",
                  "description": "sha256(uint64be epoch || uint32be count || uint32be denominations[] || uint32be count || keyIds[]), the epoch commitment the issuer publishes; 0x and 64 hex characters."
                }
              }
            }
          }
        }
      },
      "BlindKey": {
        "type": "object",
        "required": [
          "token_key_id",
          "token_key",
          "epoch",
          "denomination",
          "status"
        ],
        "properties": {
          "token_key_id": {
            "type": "string",
            "description": "SHA-256 of the SubjectPublicKeyInfo, hex."
          },
          "token_key": {
            "type": "string",
            "description": "RFC 9578 SubjectPublicKeyInfo (RSASSA-PSS, SHA-384, 48-byte salt), base64url."
          },
          "epoch": {
            "type": "integer"
          },
          "denomination": {
            "enum": [
              1000,
              10000,
              100000
            ],
            "description": "Token-units one token is worth."
          },
          "value_usd": {
            "type": "string",
            "description": "What one token of this key is worth; fixed for the key's life."
          },
          "unit_price_usd": {
            "type": "string"
          },
          "status": {
            "enum": [
              "upcoming",
              "issuing",
              "redeem_only",
              "expired",
              "revoked"
            ]
          },
          "not_before": {
            "type": "string",
            "format": "date-time"
          },
          "issue_until": {
            "type": "string",
            "format": "date-time"
          },
          "redeem_until": {
            "type": "string",
            "format": "date-time"
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "issued": {
            "type": "integer",
            "description": "Tokens signed with this key (a count)."
          },
          "redeemed": {
            "type": "integer",
            "description": "Tokens spent (a count)."
          }
        }
      },
      "OhttpKeyList": {
        "type": "object",
        "required": [
          "data",
          "signature"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "v",
              "kind",
              "keys",
              "log",
              "relays"
            ],
            "properties": {
              "v": {
                "type": "integer",
                "const": 1
              },
              "kind": {
                "type": "string",
                "const": "ohttp-key-list"
              },
              "issued": {
                "type": "string",
                "format": "date-time"
              },
              "router": {
                "type": "string"
              },
              "gateway": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "keys_url": {
                    "type": "string"
                  },
                  "media_type": {
                    "type": "string"
                  }
                }
              },
              "suites": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kem": {
                      "type": "string"
                    },
                    "kem_id": {
                      "type": "integer"
                    },
                    "kdf": {
                      "type": "string"
                    },
                    "kdf_id": {
                      "type": "integer"
                    },
                    "aead": {
                      "type": "string"
                    },
                    "aead_id": {
                      "type": "integer"
                    }
                  }
                }
              },
              "epoch_seconds": {
                "type": "integer"
              },
              "grace_seconds": {
                "type": "integer"
              },
              "keys": {
                "type": "array",
                "description": "Oldest first; at most the latest 512.",
                "items": {
                  "type": "object",
                  "properties": {
                    "epoch": {
                      "type": "integer"
                    },
                    "key_id": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 255,
                      "description": "The 8-bit key identifier: the epoch modulo 256."
                    },
                    "kem_id": {
                      "type": "integer"
                    },
                    "public_key": {
                      "type": "string",
                      "description": "Raw X25519 public key, base64url."
                    },
                    "config": {
                      "type": "string",
                      "description": "The key configuration (RFC 9458 section 3.1), base64url."
                    },
                    "config_sha256": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "upcoming",
                        "current",
                        "grace",
                        "expired",
                        "revoked"
                      ]
                    },
                    "valid_from": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "accept_until": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "private_key_destroyed": {
                      "type": "boolean"
                    },
                    "entry_hash": {
                      "type": "string",
                      "description": "SHA-256 chain: this entry committed to the one before it."
                    }
                  }
                }
              },
              "log": {
                "type": "object",
                "properties": {
                  "algorithm": {
                    "type": "string",
                    "const": "sha256-chain"
                  },
                  "entries": {
                    "type": "integer",
                    "description": "Keys ever created."
                  },
                  "head": {
                    "type": "string"
                  },
                  "first_prev": {
                    "type": "string",
                    "description": "The entry hash before the first key listed (64 zeros when the list starts at the first key ever)."
                  }
                }
              },
              "relays": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Relay"
                }
              }
            }
          },
          "signature": {
            "type": "object",
            "properties": {
              "alg": {
                "type": "string",
                "const": "Ed25519"
              },
              "key_id": {
                "type": "string",
                "description": "A receipt signing key; see GET /api/v1/receipts/keys."
              },
              "sig": {
                "type": "string",
                "description": "Base64 Ed25519 signature over the canonical JSON of data."
              }
            }
          }
        }
      },
      "Relay": {
        "type": "object",
        "required": [
          "operator",
          "url",
          "key_id",
          "independent"
        ],
        "properties": {
          "operator": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Where a client sends message/ohttp-req."
          },
          "key_id": {
            "type": "string",
            "description": "Identifier of the credential this relay presents to the gateway."
          },
          "independent": {
            "type": "boolean",
            "description": "False when the relay's operator is the gateway's own operator."
          }
        }
      },
      "RelayList": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "lane": {
                "type": "string",
                "const": "unlinkable"
              },
              "gateway": {
                "type": "object",
                "properties": {
                  "operator": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "keys_url": {
                    "type": "string"
                  },
                  "key_list_url": {
                    "type": "string"
                  },
                  "chunked": {
                    "type": "object",
                    "description": "Present only where the gateway accepts chunked Oblivious HTTP.",
                    "properties": {
                      "request": {
                        "type": "string",
                        "const": "message/ohttp-chunked-req"
                      },
                      "response": {
                        "type": "string",
                        "const": "message/ohttp-chunked-res"
                      }
                    }
                  }
                }
              },
              "relays": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Relay"
                }
              },
              "independent_operators": {
                "type": "integer",
                "description": "Distinct operators of independent relays."
              },
              "note": {
                "type": "string"
              }
            }
          }
        }
      },
      "BlindPurchaseRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "token_key_id",
          "blinded_msgs"
        ],
        "properties": {
          "token_key_id": {
            "type": "string",
            "description": "A key whose status is issuing."
          },
          "blinded_msgs": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "description": "256 bytes, base64url: the blinded token input, below the key's modulus."
            },
            "description": "Distinct blinded messages, at most max_batch."
          }
        }
      },
      "BlindPurchase": {
        "type": "object",
        "required": [
          "token_key_id",
          "epoch",
          "denomination",
          "count",
          "cost_usd",
          "signatures"
        ],
        "properties": {
          "token_key_id": {
            "type": "string"
          },
          "epoch": {
            "type": "integer"
          },
          "denomination": {
            "type": "integer"
          },
          "count": {
            "type": "integer"
          },
          "cost_usd": {
            "type": "string"
          },
          "replayed": {
            "type": "boolean",
            "description": "True when this exact purchase had already been made; nothing was charged again."
          },
          "signatures": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "signatures[i] answers blinded_msgs[i]; 256 bytes each, base64url."
          }
        }
      },
      "HolderStatus": {
        "type": "object",
        "description": "The tier of the wallet behind the calling key and the perks that apply to the key now. A key that does not belong to a wallet sign-in account gets the same shape with wallet null and a hint.",
        "required": [
          "enabled",
          "token",
          "wallet",
          "balance",
          "balance_error",
          "tier",
          "next_tier",
          "perks"
        ],
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "Whether holder tiers run on this router."
          },
          "token": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "address",
              "symbol"
            ],
            "properties": {
              "address": {
                "type": "string",
                "description": "The token mint (base58)."
              },
              "symbol": {
                "type": "string"
              }
            }
          },
          "wallet": {
            "type": [
              "string",
              "null"
            ],
            "description": "The wallet behind this key (wallet sign-in keys only)."
          },
          "balance": {
            "type": [
              "string",
              "null"
            ],
            "description": "Token balance in whole tokens (decimal string); null without a wallet or when it could not be read."
          },
          "balance_error": {
            "type": "boolean",
            "description": "True when the balance could not be read; no tier applies until it can."
          },
          "tier": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/HolderTier"
              },
              {
                "type": "null"
              }
            ]
          },
          "next_tier": {
            "type": [
              "object",
              "null"
            ],
            "description": "The next threshold above the balance; null at the top tier or when tiers are off.",
            "required": [
              "name",
              "min",
              "remaining"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "min": {
                "type": "string"
              },
              "remaining": {
                "type": "string",
                "description": "How far the balance is below that threshold, in whole tokens."
              }
            }
          },
          "perks": {
            "type": "object",
            "required": [
              "limits",
              "sealed_priority",
              "early_access_hours",
              "vote_weight",
              "credits_never_expire",
              "badge"
            ],
            "properties": {
              "limits": {
                "type": "object",
                "description": "The limits this key runs under now. With no tier these are the standard limits.",
                "required": [
                  "rpm",
                  "tpm",
                  "agent_keys",
                  "saved_routes",
                  "presets",
                  "batch_rows"
                ],
                "properties": {
                  "rpm": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Requests per minute (0: no cap)."
                  },
                  "tpm": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "minimum": 0,
                    "description": "Tokens per minute (0: no cap; null: not set on this key)."
                  },
                  "agent_keys": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Active Agent Session keys per account (0: no cap)."
                  },
                  "saved_routes": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Saved routes per account."
                  },
                  "presets": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Presets per account."
                  },
                  "batch_rows": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Lines in one batch."
                  }
                }
              },
              "sealed_priority": {
                "type": "integer",
                "minimum": 0
              },
              "early_access_hours": {
                "type": "integer",
                "minimum": 0
              },
              "vote_weight": {
                "type": "integer",
                "minimum": 0
              },
              "credits_never_expire": {
                "type": "boolean"
              },
              "badge": {
                "type": "boolean"
              }
            }
          },
          "hint": {
            "type": "string",
            "description": "Present when the key has no wallet: how to see a tier."
          }
        }
      },
      "ModelLaneInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "variant"
        ],
        "description": "A model's lane record. native_low_refusal and abliterated need license and base_model.",
        "properties": {
          "variant": {
            "type": "string",
            "enum": [
              "mainstream",
              "native_low_refusal",
              "abliterated"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "servable",
              "candidate"
            ],
            "default": "servable",
            "description": "candidate routes the model to no provider."
          },
          "base_model": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200
          },
          "license": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64,
            "pattern": "^[\\w.+-]+$",
            "description": "License identifier such as apache-2.0."
          },
          "weights": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": false,
            "properties": {
              "source": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 200,
                "description": "For example huggingface:owner/repo. A creator claim is checked against this repository."
              },
              "revision": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^[0-9a-fA-F]{7,64}$"
              },
              "digest": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^sha256:[0-9a-fA-F]{64}$"
              }
            }
          },
          "creator_handle": {
            "type": [
              "string",
              "null"
            ],
            "description": "Hugging Face handle of the uploader."
          }
        }
      },
      "LaneCandidate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "hugging_face_id": {
            "type": "string"
          },
          "base_model": {
            "type": "string"
          },
          "revision": {
            "type": [
              "string",
              "null"
            ],
            "description": "The revision seen at discovery; the one evaluated."
          },
          "license": {
            "type": [
              "string",
              "null"
            ]
          },
          "variant": {
            "type": "string",
            "enum": [
              "abliterated",
              "native_low_refusal"
            ]
          },
          "creator_handle": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "discovered",
              "rejected",
              "evaluated",
              "failed",
              "approved",
              "servable"
            ]
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why a candidate was rejected or failed."
          },
          "model": {
            "type": [
              "string",
              "null"
            ],
            "description": "The catalog model that serves it, once linked."
          },
          "provider": {
            "type": [
              "string",
              "null"
            ]
          },
          "discovered_at": {
            "type": "string",
            "format": "date-time"
          },
          "approved_by": {
            "type": [
              "string",
              "null"
            ]
          },
          "approved_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "servable_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "last_evaluation": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "passed": {
                "type": "boolean"
              },
              "refusal_rate": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Share of the benign probe prompts the endpoint refused."
              },
              "capability_score": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Share of the exact-check prompts answered correctly."
              },
              "canary_accuracy": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "canary_quant_match": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "detail": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "CreatorClaim": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "hugging_face_id": {
            "type": "string"
          },
          "handle": {
            "type": "string",
            "description": "Owner of the repository, from its id."
          },
          "address": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "verified"
            ]
          },
          "challenge": {
            "type": "string"
          },
          "file": {
            "type": "string",
            "description": "File name to commit to the main branch of the repository."
          },
          "file_content": {
            "type": "string",
            "description": "What the file must contain: the challenge on its own line."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "verified_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "onchain_tx": {
            "type": [
              "string",
              "null"
            ]
          },
          "royalty_bps": {
            "type": "integer"
          },
          "expired": {
            "type": "boolean"
          },
          "already_verified": {
            "type": "boolean"
          }
        }
      },
      "SpendAlertInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "threshold",
              "budget_pct",
              "anomaly"
            ]
          },
          "window": {
            "type": "string",
            "enum": [
              "day",
              "week",
              "month"
            ]
          },
          "threshold_usd": {
            "type": "number"
          },
          "pct": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
          },
          "multiplier": {
            "type": "number"
          },
          "key_hash": {
            "type": "string"
          },
          "webhook_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "HTTPS, public address only; stored encrypted."
          },
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "AnthropicMessagesRequest": {
        "type": "object",
        "required": [
          "model",
          "max_tokens",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "A model id from GET /v1/models, or a name the operator mapped with ANTHROPIC_MODEL_MAP."
          },
          "messages": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "role",
                "content"
              ],
              "properties": {
                "role": {
                  "type": "string",
                  "enum": [
                    "user",
                    "assistant"
                  ]
                },
                "content": {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A content block: text, image (source base64 or url), tool_use, tool_result, document (text source only); thinking blocks are dropped.",
                        "required": [
                          "type"
                        ],
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": [
                              "text",
                              "image",
                              "tool_use",
                              "tool_result",
                              "document",
                              "thinking",
                              "redacted_thinking"
                            ]
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  ]
                }
              }
            }
          },
          "system": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "type",
                    "text"
                  ],
                  "properties": {
                    "type": {
                      "const": "text"
                    },
                    "text": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            ]
          },
          "tools": {
            "type": "array",
            "description": "Custom tools (name, description, input_schema). Tools hosted by Anthropic are left out and named in X-Trellis-Ignored.",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "input_schema": {
                  "type": "object"
                }
              },
              "additionalProperties": true
            }
          },
          "tool_choice": {
            "type": "object",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "auto",
                  "any",
                  "tool",
                  "none"
                ]
              },
              "name": {
                "type": "string"
              },
              "disable_parallel_tool_use": {
                "type": "boolean"
              }
            }
          },
          "thinking": {
            "type": "object",
            "description": "Accepted and not acted on.",
            "additionalProperties": true
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Lowered to the model's output limit, and to what is left of its context, when higher."
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2
          },
          "top_p": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "top_k": {
            "type": "integer",
            "minimum": 0,
            "description": "Dropped for a provider that does not list it."
          },
          "stop_sequences": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "metadata": {
            "type": "object",
            "properties": {
              "user_id": {
                "type": "string",
                "description": "Sent to the provider as user."
              }
            }
          },
          "provider": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ProviderPreferences"
              }
            ],
            "description": "Routing preferences as on chat completions; provider.lane (public or attested) and provider.disclosure work as documented there."
          }
        },
        "additionalProperties": true
      },
      "AnthropicCountTokensRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "A model id from GET /v1/models, or a name the operator mapped with ANTHROPIC_MODEL_MAP."
          },
          "messages": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "role",
                "content"
              ],
              "properties": {
                "role": {
                  "type": "string",
                  "enum": [
                    "user",
                    "assistant"
                  ]
                },
                "content": {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A content block: text, image (source base64 or url), tool_use, tool_result, document (text source only); thinking blocks are dropped.",
                        "required": [
                          "type"
                        ],
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": [
                              "text",
                              "image",
                              "tool_use",
                              "tool_result",
                              "document",
                              "thinking",
                              "redacted_thinking"
                            ]
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  ]
                }
              }
            }
          },
          "system": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "type",
                    "text"
                  ],
                  "properties": {
                    "type": {
                      "const": "text"
                    },
                    "text": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            ]
          },
          "tools": {
            "type": "array",
            "description": "Custom tools (name, description, input_schema). Tools hosted by Anthropic are left out and named in X-Trellis-Ignored.",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "input_schema": {
                  "type": "object"
                }
              },
              "additionalProperties": true
            }
          },
          "tool_choice": {
            "type": "object",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "auto",
                  "any",
                  "tool",
                  "none"
                ]
              },
              "name": {
                "type": "string"
              },
              "disable_parallel_tool_use": {
                "type": "boolean"
              }
            }
          },
          "thinking": {
            "type": "object",
            "description": "Accepted and not acted on.",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "AnthropicMessage": {
        "type": "object",
        "required": [
          "id",
          "type",
          "role",
          "model",
          "content",
          "stop_reason",
          "stop_sequence",
          "usage"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The id of the generation's signed receipt (GET /api/v1/receipts/{id})."
          },
          "type": {
            "const": "message"
          },
          "role": {
            "const": "assistant"
          },
          "model": {
            "type": "string",
            "description": "The catalog model that answered."
          },
          "content": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "type"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "text",
                    "tool_use"
                  ]
                },
                "text": {
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "input": {
                  "type": "object"
                }
              }
            }
          },
          "stop_reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "end_turn",
              "max_tokens",
              "stop_sequence",
              "tool_use",
              "refusal",
              null
            ]
          },
          "stop_sequence": {
            "type": [
              "string",
              "null"
            ]
          },
          "usage": {
            "type": "object",
            "required": [
              "input_tokens",
              "output_tokens"
            ],
            "properties": {
              "input_tokens": {
                "type": "integer",
                "description": "Prompt tokens not read from or written to the provider's cache."
              },
              "output_tokens": {
                "type": "integer"
              },
              "cache_creation_input_tokens": {
                "type": "integer"
              },
              "cache_read_input_tokens": {
                "type": "integer"
              }
            }
          },
          "trellis": {
            "type": "object",
            "description": "What the router says about the call.",
            "properties": {
              "receipt_id": {
                "type": "string"
              },
              "lane": {
                "type": "string",
                "enum": [
                  "public",
                  "attested",
                  "unlinkable"
                ]
              },
              "disclosure": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "attested",
                  "policy",
                  "vendor-forwarded",
                  null
                ]
              },
              "policy_hash": {
                "type": "string"
              },
              "provider": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "cost_usd": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "upstream_attestation": {
                "type": "object",
                "additionalProperties": true
              },
              "receipt": {
                "$ref": "#/components/schemas/Receipt"
              }
            }
          }
        }
      },
      "AnthropicErrorBody": {
        "type": "object",
        "required": [
          "type",
          "error"
        ],
        "properties": {
          "type": {
            "const": "error"
          },
          "error": {
            "type": "object",
            "required": [
              "type",
              "message"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "invalid_request_error",
                  "authentication_error",
                  "billing_error",
                  "permission_error",
                  "not_found_error",
                  "request_too_large",
                  "rate_limit_error",
                  "api_error",
                  "timeout_error",
                  "overloaded_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          },
          "request_id": {
            "type": "string"
          },
          "trellis": {
            "type": "object",
            "description": "The router's own error type (for example lane_unavailable), its metadata, and receipt_id when a refused call was billed.",
            "additionalProperties": true
          }
        }
      },
      "ResponsesInputItem": {
        "description": "An input item: a message, a function_call or custom_tool_call from an earlier turn, or the function_call_output or custom_tool_call_output for it.",
        "oneOf": [
          {
            "type": "object",
            "required": [
              "role",
              "content"
            ],
            "properties": {
              "type": {
                "const": "message"
              },
              "role": {
                "type": "string",
                "enum": [
                  "user",
                  "assistant",
                  "system",
                  "developer"
                ],
                "description": "developer is sent to the model as system."
              },
              "content": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "input_text ({type, text}), input_image ({type, image_url: an https or data: URL, detail}); output_text and refusal in an earlier assistant message. File ids and input_file are refused.",
                      "required": [
                        "type"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "input_text",
                            "input_image",
                            "output_text",
                            "refusal"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  }
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "type",
              "call_id",
              "name"
            ],
            "properties": {
              "type": {
                "const": "function_call"
              },
              "call_id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "arguments": {
                "type": "string",
                "description": "JSON text."
              }
            }
          },
          {
            "type": "object",
            "required": [
              "type",
              "call_id",
              "output"
            ],
            "properties": {
              "type": {
                "const": "function_call_output"
              },
              "call_id": {
                "type": "string"
              },
              "output": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                ],
                "description": "The function's result: text, or input_text parts."
              }
            }
          },
          {
            "type": "object",
            "required": [
              "type",
              "call_id",
              "name"
            ],
            "properties": {
              "type": {
                "const": "custom_tool_call"
              },
              "call_id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "input": {
                "type": "string",
                "description": "The freeform text the model gave the tool."
              }
            }
          },
          {
            "type": "object",
            "required": [
              "type",
              "call_id",
              "output"
            ],
            "properties": {
              "type": {
                "const": "custom_tool_call_output"
              },
              "call_id": {
                "type": "string"
              },
              "output": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "ResponsesRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "description": "A Responses API request. Options Trellis cannot honour because they need stored state are refused (store true, previous_response_id, conversation, background, prompt) and so is every tool that is not a function or custom tool.",
        "properties": {
          "model": {
            "type": "string",
            "description": "Public model ID, as in chat completions."
          },
          "input": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ResponsesInputItem"
                }
              }
            ],
            "description": "The whole conversation: one user message as text, or input items. reasoning items are ignored; item_reference and hosted tool items are refused."
          },
          "instructions": {
            "type": "string",
            "description": "Sent as a system message before the input."
          },
          "tools": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "object",
                  "required": [
                    "type",
                    "name"
                  ],
                  "properties": {
                    "type": {
                      "const": "function"
                    },
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "parameters": {
                      "type": "object",
                      "description": "JSON Schema of the arguments."
                    },
                    "strict": {
                      "type": "boolean"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "type",
                    "name"
                  ],
                  "properties": {
                    "type": {
                      "const": "custom"
                    },
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "format": {
                      "type": "object",
                      "description": "{type: text}, or {type: grammar, syntax: lark or regex, definition}. The grammar is given to the model in the tool's description as guidance and is not enforced.",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "text",
                            "grammar"
                          ]
                        },
                        "syntax": {
                          "type": "string"
                        },
                        "definition": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  }
                }
              ]
            },
            "description": "Function and custom tools. Requires a model and provider that support tools. A custom tool takes freeform text; its name must differ from every function's."
          },
          "tool_choice": {
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "auto",
                  "none",
                  "required"
                ]
              },
              {
                "type": "object",
                "required": [
                  "type",
                  "name"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "function",
                      "custom"
                    ]
                  },
                  "name": {
                    "type": "string"
                  }
                }
              }
            ]
          },
          "parallel_tool_calls": {
            "type": "boolean"
          },
          "max_output_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Sent to the chat call as its output cap. The router always sends the provider an explicit cap: the smallest of this value, the catalog's output limit for the model (16,384 when the catalog has none) and the room the context leaves after the prompt bound; a higher value is clamped, not refused, and an omitted value is filled in."
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2
          },
          "top_p": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "text": {
            "type": "object",
            "properties": {
              "format": {
                "type": "object",
                "description": "text (default), json_object, or json_schema ({type, name, schema, strict, description}), sent as response_format. Requires a model and provider that support it.",
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "text",
                      "json_object",
                      "json_schema"
                    ]
                  }
                },
                "additionalProperties": true
              }
            }
          },
          "reasoning": {
            "type": "object",
            "properties": {
              "effort": {
                "type": "string"
              }
            },
            "description": "reasoning.effort is passed on as reasoning.effort; providers that do not support it drop it."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Echoed in the Response. Not sent to a provider."
          },
          "user": {
            "type": "string",
            "description": "Passed to the provider as the end-user identity, as in chat completions."
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "store": {
            "type": "boolean",
            "enum": [
              false
            ],
            "default": false,
            "description": "Must be false or omitted: Trellis stores no responses."
          },
          "provider": {
            "$ref": "#/components/schemas/ProviderPreferences"
          }
        },
        "additionalProperties": true
      },
      "ResponsesObject": {
        "type": "object",
        "required": [
          "id",
          "object",
          "created_at",
          "status",
          "model",
          "output",
          "metadata"
        ],
        "description": "A Response. The request's instructions, tools, tool_choice, max_output_tokens, temperature, top_p, parallel_tool_calls, text, reasoning and user are echoed back; store is always false and previous_response_id null.",
        "properties": {
          "id": {
            "type": "string",
            "description": "resp_ followed by the receipt id. There is nothing to fetch with it; the receipt is at GET /api/v1/receipts/{id} for the id without the resp_ prefix."
          },
          "object": {
            "const": "response"
          },
          "created_at": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "in_progress",
              "completed",
              "incomplete",
              "failed"
            ],
            "description": "incomplete: the answer was cut off (incomplete_details.reason max_output_tokens or content_filter). failed appears only in a stream, in response.failed."
          },
          "error": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "incomplete_details": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "reason": {
                "type": "string",
                "enum": [
                  "max_output_tokens",
                  "content_filter"
                ]
              }
            }
          },
          "model": {
            "type": "string",
            "description": "The model the router resolved the request to."
          },
          "output": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "object",
                  "required": [
                    "type",
                    "id",
                    "role",
                    "status",
                    "content"
                  ],
                  "properties": {
                    "type": {
                      "const": "message"
                    },
                    "id": {
                      "type": "string"
                    },
                    "role": {
                      "const": "assistant"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "in_progress",
                        "completed"
                      ]
                    },
                    "content": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "type"
                        ],
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": [
                              "output_text",
                              "refusal"
                            ]
                          },
                          "text": {
                            "type": "string"
                          },
                          "annotations": {
                            "type": "array",
                            "items": {}
                          },
                          "refusal": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "type",
                    "id",
                    "call_id",
                    "name",
                    "arguments",
                    "status"
                  ],
                  "properties": {
                    "type": {
                      "const": "function_call"
                    },
                    "id": {
                      "type": "string"
                    },
                    "call_id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "arguments": {
                      "type": "string",
                      "description": "JSON text."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "in_progress",
                        "completed"
                      ]
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "type",
                    "id",
                    "call_id",
                    "name",
                    "input",
                    "status"
                  ],
                  "properties": {
                    "type": {
                      "const": "custom_tool_call"
                    },
                    "id": {
                      "type": "string"
                    },
                    "call_id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "input": {
                      "type": "string",
                      "description": "The freeform text the model gave the custom tool."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "in_progress",
                        "completed"
                      ]
                    }
                  }
                }
              ]
            },
            "description": "A message with output_text, and a function_call or custom_tool_call item for each tool call the model made."
          },
          "usage": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "input_tokens": {
                "type": "integer"
              },
              "input_tokens_details": {
                "type": "object",
                "properties": {
                  "cached_tokens": {
                    "type": "integer"
                  }
                }
              },
              "output_tokens": {
                "type": "integer"
              },
              "output_tokens_details": {
                "type": "object",
                "properties": {
                  "reasoning_tokens": {
                    "type": "integer"
                  }
                }
              },
              "total_tokens": {
                "type": "integer"
              },
              "cost": {
                "type": "number",
                "description": "What the call cost in USD, as usage.cost in chat completions."
              }
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "The request's metadata plus trellis_receipt_id (the id of the signed receipt), trellis_lane (public, attested or unlinkable), trellis_disclosure (the class the receipt records, once known) and trellis_policy_hash (only when the serving endpoint attested one)."
          }
        },
        "additionalProperties": true
      },
      "RagRequest": {
        "type": "object",
        "required": [
          "documents",
          "question",
          "model"
        ],
        "additionalProperties": false,
        "description": "Unknown fields are refused (400), so a misspelt option is never silently ignored. There is no cache option: the response cache is never used.",
        "properties": {
          "documents": {
            "type": "array",
            "minItems": 1,
            "description": "The text to search: plain strings or {id, text}. At most 200 documents and 2 MiB of UTF-8 text by default (RAG_MAX_DOCUMENTS, RAG_MAX_BYTES). A string, or an object without id, is named doc-<position>, starting at 1. Ids must be unique; a document with no text is refused.",
            "items": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "object",
                  "required": [
                    "text"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200
                    },
                    "text": {
                      "type": "string"
                    }
                  }
                }
              ]
            }
          },
          "question": {
            "type": "string",
            "minLength": 1,
            "maxLength": 8000
          },
          "model": {
            "type": "string",
            "description": "The chat model that writes the answer. An embedding model is refused."
          },
          "embedding_model": {
            "type": "string",
            "description": "The model that embeds the chunks and the question. Default: qwen/qwen3-embedding-8b if the catalog serves it, else the cheapest embedding model; models with an attested endpoint are considered first unless the request asks for a lane or ceiling, when only models that meet it are."
          },
          "top_k": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "default": 4,
            "description": "How many of the best chunks go into the prompt. A request whose largest possible prompt would not fit the chat model's context is refused (400 context_too_small) before anything is embedded."
          },
          "chunk": {
            "type": "object",
            "additionalProperties": false,
            "description": "Sizes are in characters (UTF-16 code units). A chunk ends at a paragraph, line or sentence boundary when there is one in its last 40%, otherwise at a space.",
            "properties": {
              "size": {
                "type": "integer",
                "minimum": 100,
                "maximum": 8000,
                "default": 1000
              },
              "overlap": {
                "type": "integer",
                "minimum": 0,
                "description": "Characters shared by neighbouring chunks: at most half of size. Default: 15% of size."
              }
            }
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Passed to the chat call."
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2,
            "description": "Passed to the chat call."
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "include_excerpts": {
            "type": "boolean",
            "default": false,
            "description": "Return each source's text as excerpt. Off by default: the response then carries where each source lies (start, end) and never the text."
          },
          "provider": {
            "type": "object",
            "additionalProperties": false,
            "description": "The lane and disclosure ceiling, applied to every call. Other routing options are not accepted. If you send none, the lane pinned on the key (routing.provider) is used, and if there is none the router chooses (see the operation description).",
            "properties": {
              "lane": {
                "type": "string",
                "enum": [
                  "public",
                  "attested"
                ],
                "description": "attested: every call goes only to a provider with attested retention and a fresh attestation the router verified; when one cannot be served the request is refused, never downgraded. unlinkable is not available here (400)."
              },
              "disclosure": {
                "type": "string",
                "enum": [
                  "none",
                  "policy",
                  "any"
                ],
                "description": "Same as provider.disclosure on chat completions."
              }
            }
          }
        }
      },
      "RagSource": {
        "type": "object",
        "required": [
          "ref",
          "document_id",
          "chunk_index",
          "score",
          "start",
          "end"
        ],
        "properties": {
          "ref": {
            "type": "integer",
            "description": "The number of the source in the prompt, and in the citations ([1], [2]) the model was asked to make. Sources are in rank order."
          },
          "document_id": {
            "type": "string"
          },
          "chunk_index": {
            "type": "integer",
            "description": "Position of the chunk within its document, from 0."
          },
          "score": {
            "type": "number",
            "description": "Cosine similarity of the chunk's vector with the question's, rounded to 6 places."
          },
          "start": {
            "type": "integer"
          },
          "end": {
            "type": "integer",
            "description": "The chunk is the document text from start to end (characters)."
          },
          "excerpt": {
            "type": "string",
            "description": "The chunk's text. Present only when include_excerpts is true."
          }
        }
      },
      "RagCall": {
        "type": "object",
        "required": [
          "step",
          "receipt_id",
          "lane",
          "disclosure",
          "cost",
          "tokens"
        ],
        "description": "One provider call, as its signed receipt records it. Read the receipt with GET /api/v1/receipts/{receipt_id}.",
        "properties": {
          "step": {
            "type": "string",
            "enum": [
              "embeddings",
              "chat"
            ]
          },
          "receipt_id": {
            "type": "string"
          },
          "model": {
            "type": [
              "string",
              "null"
            ]
          },
          "provider": {
            "type": [
              "string",
              "null"
            ]
          },
          "lane": {
            "type": [
              "string",
              "null"
            ],
            "description": "The lane the call was made under."
          },
          "disclosure": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "attested",
              "policy",
              "vendor-forwarded",
              null
            ],
            "description": "The class the call was served under, from its receipt."
          },
          "cost": {
            "type": "number",
            "description": "USD charged for this call."
          },
          "tokens": {
            "type": "object",
            "properties": {
              "prompt": {
                "type": "integer"
              },
              "completion": {
                "type": "integer"
              }
            }
          },
          "inputs": {
            "type": "integer",
            "description": "Embeddings calls: how many texts (the question and chunks) the call embedded."
          },
          "policy_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "The classifier policy hash the serving endpoint attested, when it did (X-Trellis-Policy-Hash of that call)."
          },
          "upstream_attestation": {
            "type": "object",
            "description": "For an attested gateway: what the router checked of the gateway's receipt for this call. attested is true only when the receipt shows an upstream the gateway verified inside a TEE.",
            "properties": {
              "attested": {
                "type": "boolean"
              },
              "gpu_attested": {
                "type": "boolean"
              },
              "receipt_verified": {
                "type": "boolean"
              },
              "kind": {},
              "receipt_id": {},
              "reason": {
                "type": "string"
              }
            }
          },
          "withheld": {
            "const": true,
            "description": "The provider had answered, but the router withheld the reply because the receipt did not show an attested upstream. The call is billed; its signed receipt says why."
          },
          "attestation_simulated": {
            "const": true,
            "description": "The attestation behind this call is a development report; a production router refuses those."
          }
        }
      },
      "RagAnswer": {
        "type": "object",
        "required": [
          "id",
          "object",
          "answer",
          "sources",
          "receipts",
          "lane",
          "lane_source",
          "embedding_model",
          "retrieval",
          "usage"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The chat call's receipt id: the same as X-Receipt-Id."
          },
          "object": {
            "const": "rag.answer"
          },
          "model": {
            "type": "string",
            "description": "The chat model that answered."
          },
          "answer": {
            "type": "string"
          },
          "finish_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RagSource"
            }
          },
          "receipts": {
            "type": "array",
            "description": "Every provider call the request made, in order: the embeddings calls, then the chat call.",
            "items": {
              "$ref": "#/components/schemas/RagCall"
            }
          },
          "embedding_model": {
            "type": "string"
          },
          "lane": {
            "type": "string",
            "enum": [
              "public",
              "attested"
            ],
            "description": "The lane every call was made under."
          },
          "lane_source": {
            "type": "string",
            "enum": [
              "request",
              "default"
            ],
            "description": "request: you stated a lane or a disclosure ceiling (even public or any) and it was used as stated. default: you stated none, and the router chose attested when the chat model and the embedding model both have an attested endpoint, else public."
          },
          "lane_note": {
            "type": "string",
            "description": "Present when the default lane was public: which model had no known attested endpoint."
          },
          "disclosure": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "attested",
              "policy",
              "vendor-forwarded",
              null
            ],
            "description": "The weakest class among all the calls, from their receipts; null when a call's class is not known."
          },
          "attestation_simulated": {
            "const": true,
            "description": "Present when any call's attestation was a development report."
          },
          "retrieval": {
            "type": "object",
            "properties": {
              "documents": {
                "type": "integer"
              },
              "chunks": {
                "type": "integer"
              },
              "top_k": {
                "type": "integer"
              },
              "chunk": {
                "type": "object",
                "properties": {
                  "size": {
                    "type": "integer"
                  },
                  "overlap": {
                    "type": "integer"
                  }
                }
              },
              "embedding_calls": {
                "type": "integer"
              }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "embedding_tokens": {
                "type": "integer"
              },
              "prompt_tokens": {
                "type": "integer"
              },
              "completion_tokens": {
                "type": "integer"
              },
              "cost": {
                "type": "number",
                "description": "Total USD across all calls."
              },
              "cost_usd": {
                "type": "string",
                "description": "The same total, exact."
              }
            }
          }
        }
      },
      "TlogCheckpoint": {
        "type": "object",
        "required": [
          "size",
          "root_hash",
          "note",
          "cosigned_by",
          "witnessed"
        ],
        "properties": {
          "size": {
            "type": "integer",
            "minimum": 0
          },
          "root_hash": {
            "type": "string",
            "description": "Base64 (standard, padded) 32-byte hash.",
            "contentEncoding": "base64"
          },
          "note": {
            "type": "string",
            "description": "The signed note, as served at /tlog/checkpoint."
          },
          "cosigned_by": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of the configured witnesses whose cosignatures are attached."
          },
          "witnessed": {
            "type": "boolean",
            "description": "True when at least the quorum of configured witnesses cosigned."
          },
          "rekor": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TlogRekorAnchor"
              },
              {
                "type": "null"
              }
            ],
            "description": "Present only with Rekor anchoring on: this checkpoint's Rekor entry, or null until it is anchored."
          }
        }
      },
      "TlogInfo": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "origin",
              "verifier_key",
              "kinds",
              "witnesses",
              "quorum",
              "size",
              "checkpoint"
            ],
            "properties": {
              "origin": {
                "type": "string",
                "description": "Checkpoint origin and the log's key name."
              },
              "verifier_key": {
                "type": "string",
                "description": "Signed-note verifier key <origin>+<key id>+<base64(0x01 || Ed25519 key)>."
              },
              "formats": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "kinds": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "receipt_key",
                    "ohttp_key_config",
                    "blind_issuer_key",
                    "measurement_bundle",
                    "attestation_binding",
                    "data_inventory",
                    "host_policy"
                  ]
                }
              },
              "witnesses": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "name",
                    "verifier_key"
                  ],
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "verifier_key": {
                      "type": "string",
                      "description": "<name>+<key id>+<base64(0x04 || Ed25519 key)>, a cosignature/v1 key."
                    }
                  }
                }
              },
              "quorum": {
                "type": "integer",
                "minimum": 1
              },
              "size": {
                "type": "integer",
                "minimum": 0
              },
              "checkpoint": {
                "$ref": "#/components/schemas/TlogCheckpoint"
              },
              "witnessed_size": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Tree size of the newest checkpoint the quorum cosigned."
              },
              "tiles_url": {
                "type": "string",
                "format": "uri"
              },
              "rekor": {
                "type": [
                  "object",
                  "null"
                ],
                "description": "Rekor anchoring (TLOG_REKOR_ENABLED): the same fields as GET /api/v1/tlog/rekor without the list; null when anchoring is off.",
                "properties": {
                  "rekor_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "entry_type": {
                    "type": "string"
                  },
                  "algorithm": {
                    "type": "string",
                    "enum": [
                      "ecdsa-p256-sha256"
                    ]
                  },
                  "key_id": {
                    "type": "string",
                    "description": "SHA-256 of the key's SubjectPublicKeyInfo, hex.",
                    "pattern": "^[0-9a-f]{64}$"
                  },
                  "public_key_pem": {
                    "type": "string",
                    "description": "The anchoring key, an ECDSA P-256 public key (PEM)."
                  },
                  "min_interval_ms": {
                    "type": "integer"
                  },
                  "latest": {
                    "oneOf": [
                      {
                        "$ref": "#/components/schemas/TlogRekorAnchor"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "TlogEntry": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "index",
              "kind",
              "sha256",
              "subject",
              "entry",
              "leaf_hash"
            ],
            "properties": {
              "index": {
                "type": "integer",
                "minimum": 0
              },
              "kind": {
                "type": "string",
                "enum": [
                  "receipt_key",
                  "ohttp_key_config",
                  "blind_issuer_key",
                  "measurement_bundle",
                  "attestation_binding",
                  "data_inventory",
                  "host_policy"
                ]
              },
              "sha256": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              "subject": {
                "type": "string",
                "description": "The key id, epoch or provider the entry is about."
              },
              "entry": {
                "type": "string",
                "description": "The entry's canonical JSON; its leaf hash is SHA-256(0x00 || these bytes)."
              },
              "leaf_hash": {
                "type": "string",
                "description": "Base64 (standard, padded) 32-byte hash.",
                "contentEncoding": "base64"
              }
            }
          }
        }
      },
      "TlogConsistency": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "from",
              "to",
              "proof"
            ],
            "properties": {
              "from": {
                "type": "integer",
                "minimum": 0
              },
              "to": {
                "type": "integer",
                "minimum": 0
              },
              "proof": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "Base64 (standard, padded) 32-byte hash.",
                  "contentEncoding": "base64"
                }
              }
            }
          }
        }
      },
      "TlogProof": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "origin",
              "index",
              "kind",
              "sha256",
              "entry",
              "checkpoint",
              "inclusion"
            ],
            "properties": {
              "origin": {
                "type": "string"
              },
              "index": {
                "type": "integer",
                "minimum": 0
              },
              "kind": {
                "type": "string",
                "enum": [
                  "receipt_key",
                  "ohttp_key_config",
                  "blind_issuer_key",
                  "measurement_bundle",
                  "attestation_binding",
                  "data_inventory",
                  "host_policy"
                ]
              },
              "sha256": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              "subject": {
                "type": "string",
                "description": "The key id, epoch or provider the entry is about."
              },
              "entry": {
                "type": "string",
                "description": "The entry's canonical JSON; its leaf hash is SHA-256(0x00 || these bytes)."
              },
              "checkpoint": {
                "$ref": "#/components/schemas/TlogCheckpoint"
              },
              "inclusion": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "Base64 (standard, padded) 32-byte hash.",
                  "contentEncoding": "base64"
                },
                "description": "RFC 6962 inclusion proof from the entry's leaf to checkpoint.root_hash."
              },
              "consistency": {
                "type": [
                  "object",
                  "null"
                ],
                "required": [
                  "from",
                  "to",
                  "proof"
                ],
                "properties": {
                  "from": {
                    "type": "integer"
                  },
                  "to": {
                    "type": "integer"
                  },
                  "proof": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "Base64 (standard, padded) 32-byte hash.",
                      "contentEncoding": "base64"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "TlogCosignatureResult": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "size",
              "accepted",
              "cosignatures",
              "witnessed"
            ],
            "properties": {
              "size": {
                "type": "integer"
              },
              "accepted": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Witnesses whose cosignature on this note verified."
              },
              "cosignatures": {
                "type": "integer",
                "description": "Configured witnesses that have now cosigned this tree size."
              },
              "witnessed": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "TlogRekorKey": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "algorithm",
              "key_id",
              "public_key_pem"
            ],
            "properties": {
              "algorithm": {
                "type": "string",
                "enum": [
                  "ecdsa-p256-sha256"
                ]
              },
              "key_id": {
                "type": "string",
                "description": "SHA-256 of the key's SubjectPublicKeyInfo, hex.",
                "pattern": "^[0-9a-f]{64}$"
              },
              "public_key_pem": {
                "type": "string",
                "description": "The anchoring key, an ECDSA P-256 public key (PEM)."
              }
            }
          }
        }
      },
      "TlogRekorAnchor": {
        "type": "object",
        "description": "A Rekor entry that anchors one checkpoint. Rekor's own hashes (inclusion_proof) are hex, as Rekor writes them.",
        "required": [
          "size",
          "root_hash",
          "note",
          "artifact_sha256",
          "key_id",
          "rekor_url",
          "uuid",
          "log_index",
          "integrated_time",
          "entry_url",
          "body",
          "inclusion_proof",
          "verified",
          "anchored_at"
        ],
        "properties": {
          "size": {
            "type": "integer",
            "minimum": 1
          },
          "root_hash": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "The checkpoint's root hash, base64 as in checkpoints."
          },
          "note": {
            "type": "string",
            "description": "The artifact: the checkpoint text, a blank line and the log's own signature line."
          },
          "artifact_sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "SHA-256 of note; the hash the hashedrekord entry holds (search.sigstore.dev finds the entry by it)."
          },
          "key_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "The anchoring key that signed the entry."
          },
          "rekor_url": {
            "type": "string",
            "format": "uri"
          },
          "uuid": {
            "type": "string",
            "description": "The entry's uuid (tree id and leaf hash, hex)."
          },
          "log_index": {
            "type": [
              "integer",
              "null"
            ]
          },
          "integrated_time": {
            "type": [
              "integer",
              "null"
            ],
            "description": "When Rekor integrated the entry (seconds since the Unix epoch)."
          },
          "log_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "entry_url": {
            "type": "string",
            "format": "uri"
          },
          "search_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "The entry on search.sigstore.dev, for the public Rekor instance."
          },
          "body": {
            "type": [
              "string",
              "null"
            ],
            "contentEncoding": "base64",
            "description": "The entry body as Rekor returned it; its leaf hash is SHA-256(0x00 || body)."
          },
          "inclusion_proof": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "log_index",
              "tree_size",
              "root_hash",
              "hashes"
            ],
            "properties": {
              "log_index": {
                "type": "integer"
              },
              "tree_size": {
                "type": "integer"
              },
              "root_hash": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              "hashes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^[0-9a-f]{64}$"
                }
              },
              "checkpoint": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Rekor's signed checkpoint for tree_size and root_hash."
              }
            }
          },
          "signed_entry_timestamp": {
            "type": [
              "string",
              "null"
            ],
            "contentEncoding": "base64"
          },
          "verified": {
            "type": "object",
            "required": [
              "inclusion",
              "checkpoint_signature",
              "signed_entry_timestamp"
            ],
            "description": "What the router checked when it stored the entry; checkpoint_signature and signed_entry_timestamp need REKOR_PUBLIC_KEY.",
            "properties": {
              "inclusion": {
                "type": "boolean"
              },
              "checkpoint_signature": {
                "type": "boolean"
              },
              "signed_entry_timestamp": {
                "type": "boolean"
              }
            }
          },
          "anchored_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TlogRekorAnchors": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "rekor_url",
              "entry_type",
              "algorithm",
              "key_id",
              "public_key_pem",
              "min_interval_ms",
              "latest",
              "anchors",
              "next_before"
            ],
            "properties": {
              "rekor_url": {
                "type": "string",
                "format": "uri"
              },
              "entry_type": {
                "type": "string",
                "enum": [
                  "hashedrekord"
                ]
              },
              "algorithm": {
                "type": "string",
                "enum": [
                  "ecdsa-p256-sha256"
                ]
              },
              "key_id": {
                "type": "string",
                "description": "SHA-256 of the key's SubjectPublicKeyInfo, hex.",
                "pattern": "^[0-9a-f]{64}$"
              },
              "public_key_pem": {
                "type": "string",
                "description": "The anchoring key, an ECDSA P-256 public key (PEM)."
              },
              "min_interval_ms": {
                "type": "integer",
                "description": "At most one submission to Rekor per this many milliseconds."
              },
              "latest": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/TlogRekorAnchor"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The newest anchored checkpoint under the current key."
              },
              "anchors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/TlogRekorAnchor"
                }
              },
              "next_before": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Pass as before for the next page; null on the last page."
              }
            }
          }
        }
      },
      "PrivacyLabel": {
        "type": "object",
        "required": [
          "receipt_id",
          "lane",
          "label",
          "summary",
          "short",
          "verify_url"
        ],
        "description": "The privacy label for one answer, computed from its signed receipt (privacyLabel in @trellis/client computes the same object from a receipt you hold; teeKind and the unlinkable transports are the two things it takes from the router).",
        "properties": {
          "receipt_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "lane": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "public",
              "attested",
              "unlinkable",
              null
            ],
            "description": "The lane the receipt records, or null for a receipt that predates lanes."
          },
          "label": {
            "type": "object",
            "required": [
              "prompt_readers",
              "network",
              "payment",
              "stored",
              "hardware"
            ],
            "properties": {
              "output": {
                "type": "object",
                "required": [
                  "unit_type",
                  "units",
                  "kind",
                  "text"
                ],
                "properties": {
                  "unit_type": {
                    "type": "string"
                  },
                  "units": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "text",
                      "image",
                      "video",
                      "audio",
                      "call",
                      "compute",
                      "unknown"
                    ]
                  },
                  "text": {
                    "type": "string"
                  }
                },
                "description": "Usage unit and quantity from the receipt. Missing unit types default to token; unfamiliar types carry no inferred content-retention guarantee."
              },
              "prompt_readers": {
                "type": "object",
                "required": [
                  "router",
                  "provider",
                  "text"
                ],
                "properties": {
                  "participants": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Provider ids named in an aggregate council receipt; individual receipts describe their access."
                  },
                  "router": {
                    "type": "boolean",
                    "const": true,
                    "description": "Always true: the router reads the prompt in memory to route it, on every lane."
                  },
                  "provider": {
                    "type": "object",
                    "required": [
                      "id",
                      "access",
                      "reply_withheld"
                    ],
                    "properties": {
                      "id": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "access": {
                        "type": "string",
                        "enum": [
                          "attested_enclave",
                          "documented_policy",
                          "provider",
                          "unproven_provider",
                          "unknown",
                          "none"
                        ],
                        "description": "attested_enclave: the router had verified the provider's hardware attestation (and, for a gateway, its signed receipt checked out). documented_policy: a no-retention policy the provider states, not proven by hardware. provider: may keep or log the prompt under its own terms. unproven_provider: an attested enclave was required or reported and not shown. unknown: the receipt does not say. none: served from the response cache, no provider ran."
                      },
                      "reply_withheld": {
                        "type": [
                          "boolean",
                          "null"
                        ],
                        "description": "true when the router withheld the reply because the attested-enclave check failed; null when the receipt does not show which."
                      }
                    }
                  },
                  "text": {
                    "type": "string"
                  }
                }
              },
              "network": {
                "type": "object",
                "required": [
                  "hidden",
                  "via",
                  "stored",
                  "counter",
                  "text"
                ],
                "properties": {
                  "hidden": {
                    "type": "boolean",
                    "description": "true only on the unlinkable lane."
                  },
                  "via": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "tor",
                      "relay",
                      "tor_or_relay",
                      null
                    ]
                  },
                  "stored": {
                    "type": [
                      "boolean",
                      "null"
                    ],
                    "enum": [
                      false,
                      null
                    ],
                    "description": "Trellis's software writes the client address to no table on current routes; null means handling is not established for an unfamiliar output type."
                  },
                  "counter": {
                    "type": "string",
                    "enum": [
                      "none",
                      "about_a_minute",
                      "possible"
                    ],
                    "description": "Whether the address was the key of a rate-limit counter that expires about a minute later. Calls with an API key are limited per key (none); a call with no key is limited per address (about_a_minute); possible when the receipt does not say which."
                  },
                  "text": {
                    "type": "string"
                  }
                }
              },
              "payment": {
                "type": "object",
                "required": [
                  "kind",
                  "identifies",
                  "text"
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "key_balance",
                      "pay_with_stock_token",
                      "own_provider_key",
                      "blind_token",
                      "wallet_balance",
                      "x402",
                      "cache_hit",
                      "unknown"
                    ]
                  },
                  "identifies": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "api_key",
                      "wallet",
                      "spent_token",
                      null
                    ],
                    "description": "What the receipt names as the payer: a key hash, a wallet address, or only the hash of a spent blind token."
                  },
                  "text": {
                    "type": "string"
                  }
                }
              },
              "stored": {
                "type": "object",
                "required": [
                  "prompt_text",
                  "reply_text",
                  "client_address",
                  "fingerprints",
                  "linked_to",
                  "cache",
                  "records",
                  "public_by_id",
                  "text"
                ],
                "properties": {
                  "prompt_text": {
                    "type": [
                      "boolean",
                      "null"
                    ],
                    "enum": [
                      false,
                      null
                    ]
                  },
                  "reply_text": {
                    "type": [
                      "boolean",
                      "null"
                    ],
                    "enum": [
                      false,
                      null
                    ]
                  },
                  "client_address": {
                    "type": [
                      "boolean",
                      "null"
                    ],
                    "enum": [
                      false,
                      null
                    ]
                  },
                  "fingerprints": {
                    "type": "boolean",
                    "description": "SHA-256 fingerprints of the request and the reply are kept."
                  },
                  "linked_to": {
                    "type": "string",
                    "enum": [
                      "api_key",
                      "wallet",
                      "nobody",
                      "unknown"
                    ]
                  },
                  "cache": {
                    "type": "string",
                    "enum": [
                      "never",
                      "only_if_requested",
                      "cache_hit",
                      "not_recorded"
                    ],
                    "description": "The opt-in response cache holds an encrypted copy of the reply, never the prompt itself, until it expires; semantic caching also keeps a hashed word vector. Unrecognized content paths report eligibility as not_recorded. It is never used on the attested or unlinkable lanes or with a blind token; on the public lane only if the request asked for it."
                  },
                  "records": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "public_by_id": {
                    "type": "boolean",
                    "const": true
                  },
                  "text": {
                    "type": "string"
                  }
                }
              },
              "hardware": {
                "type": "object",
                "required": [
                  "attested",
                  "tee",
                  "gpu_attested",
                  "verified_by",
                  "development_report",
                  "text"
                ],
                "properties": {
                  "attested": {
                    "type": "boolean"
                  },
                  "tee": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The TEE type from the router's attestation record for the receipt's attestation hash, when the receipt cites one; null when not known."
                  },
                  "gpu_attested": {
                    "type": "boolean",
                    "description": "true only when the gateway's signed receipt asserted GPU attestation."
                  },
                  "verified_by": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "gateway_receipt",
                      "router_attestation",
                      null
                    ]
                  },
                  "development_report": {
                    "type": "boolean",
                    "description": "true when the attestation behind the call was a development report, which is not a hardware proof."
                  },
                  "text": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "summary": {
            "type": "array",
            "minItems": 3,
            "maxItems": 5,
            "items": {
              "type": "string"
            },
            "description": "Three to five short lines a person who is not a developer can read."
          },
          "short": {
            "type": "string",
            "description": "The same in one line, for a chat message."
          },
          "verify_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "The verify page for this receipt, when the router's address is known."
          }
        }
      },
      "BatchRequestLine": {
        "type": "object",
        "required": [
          "custom_id",
          "method",
          "url",
          "body"
        ],
        "properties": {
          "custom_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Your id for the line, unique in the batch; results carry it back."
          },
          "method": {
            "type": "string",
            "enum": [
              "POST"
            ]
          },
          "url": {
            "type": "string",
            "enum": [
              "/v1/chat/completions",
              "/v1/embeddings",
              "/api/v1/chat/completions",
              "/api/v1/embeddings"
            ]
          },
          "body": {
            "type": "object",
            "additionalProperties": true,
            "description": "The chat completions or embeddings request body. stream true, model trellis/council and verify are refused."
          }
        }
      },
      "BatchCreateRequest": {
        "type": "object",
        "description": "Send requests or input_jsonl. input_file_id is refused with 400 (there is no files endpoint).",
        "oneOf": [
          {
            "required": [
              "requests"
            ]
          },
          {
            "required": [
              "input_jsonl"
            ]
          }
        ],
        "properties": {
          "requests": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/BatchRequestLine"
            }
          },
          "input_jsonl": {
            "type": "string",
            "description": "The lines as JSON Lines text: one BatchRequestLine object per line."
          },
          "endpoint": {
            "type": "string",
            "enum": [
              "/v1/chat/completions",
              "/v1/embeddings"
            ],
            "description": "When given, every line's url must match it."
          },
          "completion_window": {
            "type": "string",
            "enum": [
              "24h"
            ],
            "default": "24h"
          }
        }
      },
      "Batch": {
        "type": "object",
        "required": [
          "id",
          "object",
          "status",
          "completion_window",
          "created_at",
          "request_counts",
          "cost",
          "output_url",
          "errors_url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "batch_ followed by a random id."
          },
          "object": {
            "type": "string",
            "const": "batch"
          },
          "endpoint": {
            "type": [
              "string",
              "null"
            ],
            "description": "The endpoint of the lines, as sent or as the lines' url."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Problems found in the batch as a whole, else null.",
            "properties": {
              "object": {
                "type": "string",
                "const": "list"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "line": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "input_file_id": {
            "type": "null",
            "description": "Always null: the lines are sent inline."
          },
          "completion_window": {
            "type": "string",
            "const": "24h"
          },
          "status": {
            "type": "string",
            "enum": [
              "validating",
              "in_progress",
              "completed",
              "failed",
              "expired",
              "cancelling",
              "cancelled"
            ],
            "description": "validating: accepted, waiting for the worker. completed, failed, expired and cancelled are final."
          },
          "output_file_id": {
            "type": "null",
            "description": "Always null: read the results at output_url."
          },
          "error_file_id": {
            "type": "null",
            "description": "Always null: read the errors at errors_url."
          },
          "output_url": {
            "type": "string",
            "description": "/api/v1/batches/{id}/output"
          },
          "errors_url": {
            "type": "string",
            "description": "/api/v1/batches/{id}/errors"
          },
          "created_at": {
            "type": "integer",
            "description": "Unix seconds."
          },
          "in_progress_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds, or null."
          },
          "expires_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "When unfinished lines expire (the end of the completion window), unix seconds."
          },
          "finalizing_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds, or null."
          },
          "completed_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds, or null."
          },
          "failed_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds, or null."
          },
          "expired_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds, or null."
          },
          "cancelling_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds, or null."
          },
          "cancelled_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds, or null."
          },
          "request_counts": {
            "type": "object",
            "required": [
              "total",
              "completed",
              "failed"
            ],
            "properties": {
              "total": {
                "type": "integer"
              },
              "completed": {
                "type": "integer"
              },
              "failed": {
                "type": "integer"
              }
            }
          },
          "cost": {
            "type": "object",
            "required": [
              "usd",
              "discount_bps",
              "list_usd"
            ],
            "properties": {
              "usd": {
                "type": "number",
                "description": "What the answered lines cost so far, at the batch price."
              },
              "discount_bps": {
                "type": "integer",
                "description": "The reduction in basis points that applied when the batch was sent (BATCH_DISCOUNT_BPS): 0 by default, the normal price."
              },
              "list_usd": {
                "type": "number",
                "description": "What the same lines would cost as normal calls."
              }
            }
          },
          "results_expire_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "When the output and errors files are deleted, unix seconds; null until the batch finishes."
          },
          "metadata": {
            "type": "null"
          }
        }
      },
      "BatchList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "type": "string",
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Batch"
            }
          },
          "first_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "has_more": {
            "type": "boolean"
          }
        }
      },
      "BatchResultLine": {
        "type": "object",
        "required": [
          "id",
          "custom_id",
          "response",
          "error"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "batch_req_ followed by a random id."
          },
          "custom_id": {
            "type": "string"
          },
          "response": {
            "type": [
              "object",
              "null"
            ],
            "description": "The response to the line; null for a line that never ran.",
            "properties": {
              "status_code": {
                "type": "integer"
              },
              "request_id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The generation id (and receipt id) of an answered line."
              },
              "body": {
                "type": "object",
                "additionalProperties": true,
                "description": "The normal response body (usage.cost and receipt included), or { error } for a failed line."
              }
            }
          },
          "error": {
            "type": [
              "object",
              "null"
            ],
            "description": "null for an answered line.",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "PresetDocument": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "models"
        ],
        "description": "A preset: the routing part of a saved route plus prompt-side defaults. The whole document is at most 64 KB as JSON.",
        "properties": {
          "trellis": {
            "$ref": "#/components/schemas/StructuredOutputOptions"
          },
          "description": {
            "type": "string",
            "maxLength": 280
          },
          "models": {
            "type": "array",
            "minItems": 1,
            "maxItems": 8,
            "items": {
              "type": "string"
            },
            "description": "Catalog model ids in fallback order; no @route/ or @preset/ entries."
          },
          "provider": {
            "type": "object",
            "description": "The same provider preferences as a saved route (SavedRouteConfig.provider), including lane (public|attested) and disclosure (none|policy|any), where the stricter of the preset and the request applies."
          },
          "params": {
            "type": "object",
            "description": "The same closed list of sampling defaults as a saved route (SavedRouteConfig.params). Request values win."
          },
          "system_prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 16000,
            "description": "Prepended as a system message only when the request's messages have no system or developer message. Chat completions only."
          },
          "response_format": {
            "type": "object",
            "description": "text, json_object or json_schema (at most 16 KB). Used when the request sets no response_format."
          },
          "tools": {
            "type": "array",
            "maxItems": 32,
            "items": {
              "type": "object"
            },
            "description": "Function tool definitions (unique names, at most 32 KB). Used with tool_choice when the request sets no tools."
          },
          "tool_choice": {
            "description": "none, auto, required, or a function the preset's tools define.",
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "none",
                  "auto",
                  "required"
                ]
              },
              {
                "type": "object"
              }
            ]
          }
        }
      },
      "Preset": {
        "type": "object",
        "required": [
          "name",
          "model",
          "version",
          "hash",
          "config"
        ],
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{1,47}$"
          },
          "model": {
            "type": "string",
            "description": "Use as the request model, e.g. @preset/support; add @<version> to pin one."
          },
          "description": {
            "type": "string"
          },
          "version": {
            "type": "integer",
            "minimum": 1,
            "description": "The version shown: the latest unless one was asked for."
          },
          "hash": {
            "type": "string",
            "description": "SHA-256 (hex) of the version's canonical JSON. Equal content, equal hash."
          },
          "config": {
            "$ref": "#/components/schemas/PresetDocument"
          },
          "versions": {
            "type": "integer",
            "description": "In the list: how many versions the preset has."
          },
          "latest_version": {
            "type": "integer"
          },
          "changed": {
            "type": "boolean",
            "description": "PUT and rollback: false when the document equals the latest version, so no version was added."
          },
          "restored_from": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PresetVersion": {
        "type": "object",
        "required": [
          "version",
          "hash",
          "model",
          "source",
          "created_at"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "hash": {
            "type": "string"
          },
          "model": {
            "type": "string",
            "description": "The pinned model name, e.g. @preset/support@3."
          },
          "source": {
            "type": "string",
            "enum": [
              "put",
              "rollback"
            ]
          },
          "restored_from": {
            "type": "integer",
            "description": "For a rollback: the version whose content it copied."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PresetDiff": {
        "type": "object",
        "required": [
          "name",
          "from",
          "to",
          "identical",
          "changes"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "from": {
            "$ref": "#/components/schemas/PresetVersion"
          },
          "to": {
            "$ref": "#/components/schemas/PresetVersion"
          },
          "identical": {
            "type": "boolean"
          },
          "changes": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "op",
                "path"
              ],
              "properties": {
                "op": {
                  "type": "string",
                  "enum": [
                    "add",
                    "remove",
                    "replace"
                  ]
                },
                "path": {
                  "type": "string",
                  "description": "JSON Pointer into the preset document."
                },
                "from": {},
                "to": {}
              }
            }
          }
        }
      },
      "OllamaModel": {
        "type": "object",
        "required": [
          "name",
          "model",
          "modified_at",
          "size",
          "digest",
          "details"
        ],
        "properties": {
          "name": {
            "type": "string",
            "examples": [
              "meta-llama/llama-3.3-70b-instruct:latest"
            ]
          },
          "model": {
            "type": "string"
          },
          "modified_at": {
            "type": "string",
            "format": "date-time"
          },
          "size": {
            "type": "integer",
            "const": 0
          },
          "digest": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "details": {
            "type": "object",
            "properties": {
              "parent_model": {
                "type": "string"
              },
              "format": {
                "type": "string"
              },
              "family": {
                "type": "string"
              },
              "families": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "parameter_size": {
                "type": "string"
              },
              "quantization_level": {
                "type": "string"
              }
            }
          }
        }
      },
      "OllamaShowResponse": {
        "type": "object",
        "required": [
          "details",
          "capabilities",
          "model_info"
        ],
        "properties": {
          "modelfile": {
            "type": "string"
          },
          "parameters": {
            "type": "string"
          },
          "template": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "properties": {
              "parent_model": {
                "type": "string"
              },
              "format": {
                "type": "string"
              },
              "family": {
                "type": "string"
              },
              "families": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "parameter_size": {
                "type": "string"
              },
              "quantization_level": {
                "type": "string"
              }
            }
          },
          "model_info": {
            "type": "object",
            "description": "general.architecture, general.parameter_count where the name states it, and <family>.context_length."
          },
          "capabilities": {
            "type": "array",
            "items": {
              "enum": [
                "completion",
                "tools",
                "vision",
                "thinking",
                "embedding"
              ]
            }
          },
          "modified_at": {
            "type": "string",
            "format": "date-time"
          },
          "trellis": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "lanes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "context_length": {
                "type": "integer"
              }
            }
          }
        }
      },
      "OllamaChatRequest": {
        "type": "object",
        "required": [
          "model"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "A name from GET /ollama/api/tags. :latest names the model itself."
          },
          "stream": {
            "type": "boolean",
            "default": true
          },
          "format": {
            "description": "\"json\" for JSON mode, or a JSON schema for structured output (response_format).",
            "oneOf": [
              {
                "const": "json"
              },
              {
                "type": "object"
              }
            ]
          },
          "options": {
            "type": "object",
            "description": "temperature, top_p, top_k, min_p, seed, stop, frequency_penalty and presence_penalty map directly; repeat_penalty to repetition_penalty; num_predict to max_tokens (with -1, -2 or no num_predict the router still sends the provider an explicit cap: the model's output limit, or 16,384 when the catalog has none, and never more than the context leaves; a higher num_predict is lowered to it). Other options tune a local runtime and are named in X-Trellis-Ignored.",
            "properties": {
              "temperature": {
                "type": "number"
              },
              "top_p": {
                "type": "number"
              },
              "top_k": {
                "type": "number"
              },
              "min_p": {
                "type": "number"
              },
              "frequency_penalty": {
                "type": "number"
              },
              "presence_penalty": {
                "type": "number"
              },
              "repeat_penalty": {
                "type": "number"
              },
              "seed": {
                "type": "integer"
              },
              "num_predict": {
                "type": "integer"
              },
              "stop": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                ]
              }
            }
          },
          "think": {
            "description": "false leaves the model's reasoning out of the reply.",
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "enum": [
                  "low",
                  "medium",
                  "high"
                ]
              }
            ]
          },
          "keep_alive": {
            "description": "Accepted and ignored; 0 with no messages or prompt answers done_reason unload."
          },
          "provider": {
            "type": "object",
            "description": "The router's provider preferences, as on chat completions, for example {\"lane\":\"attested\"}."
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "role"
              ],
              "properties": {
                "role": {
                  "enum": [
                    "system",
                    "user",
                    "assistant",
                    "tool"
                  ]
                },
                "content": {
                  "type": "string"
                },
                "images": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Base64 images (user messages); the media type is read from the bytes."
                },
                "tool_calls": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "function"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "function": {
                        "type": "object",
                        "required": [
                          "name",
                          "arguments"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "arguments": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                },
                "tool_name": {
                  "type": "string",
                  "description": "On a tool message: the tool whose call it answers."
                },
                "tool_call_id": {
                  "type": "string"
                },
                "thinking": {
                  "type": "string"
                }
              }
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "function"
              ],
              "properties": {
                "type": {
                  "const": "function"
                },
                "function": {
                  "type": "object",
                  "required": [
                    "name"
                  ],
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "parameters": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "OllamaGenerateRequest": {
        "type": "object",
        "required": [
          "model"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "A name from GET /ollama/api/tags. :latest names the model itself."
          },
          "stream": {
            "type": "boolean",
            "default": true
          },
          "format": {
            "description": "\"json\" for JSON mode, or a JSON schema for structured output (response_format).",
            "oneOf": [
              {
                "const": "json"
              },
              {
                "type": "object"
              }
            ]
          },
          "options": {
            "type": "object",
            "description": "temperature, top_p, top_k, min_p, seed, stop, frequency_penalty and presence_penalty map directly; repeat_penalty to repetition_penalty; num_predict to max_tokens (with -1, -2 or no num_predict the router still sends the provider an explicit cap: the model's output limit, or 16,384 when the catalog has none, and never more than the context leaves; a higher num_predict is lowered to it). Other options tune a local runtime and are named in X-Trellis-Ignored.",
            "properties": {
              "temperature": {
                "type": "number"
              },
              "top_p": {
                "type": "number"
              },
              "top_k": {
                "type": "number"
              },
              "min_p": {
                "type": "number"
              },
              "frequency_penalty": {
                "type": "number"
              },
              "presence_penalty": {
                "type": "number"
              },
              "repeat_penalty": {
                "type": "number"
              },
              "seed": {
                "type": "integer"
              },
              "num_predict": {
                "type": "integer"
              },
              "stop": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                ]
              }
            }
          },
          "think": {
            "description": "false leaves the model's reasoning out of the reply.",
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "enum": [
                  "low",
                  "medium",
                  "high"
                ]
              }
            ]
          },
          "keep_alive": {
            "description": "Accepted and ignored; 0 with no messages or prompt answers done_reason unload."
          },
          "provider": {
            "type": "object",
            "description": "The router's provider preferences, as on chat completions, for example {\"lane\":\"attested\"}."
          },
          "prompt": {
            "type": "string"
          },
          "system": {
            "type": "string"
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "suffix": {
            "type": "string",
            "description": "Accepted and named in X-Trellis-Ignored."
          },
          "template": {
            "type": "string",
            "description": "Accepted and named in X-Trellis-Ignored."
          },
          "raw": {
            "type": "boolean"
          },
          "context": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "Deprecated in Ollama; accepted and named in X-Trellis-Ignored."
          }
        }
      },
      "OllamaChatResponse": {
        "type": "object",
        "required": [
          "model",
          "created_at",
          "done"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "message": {
            "type": "object",
            "properties": {
              "role": {
                "const": "assistant"
              },
              "content": {
                "type": "string"
              },
              "thinking": {
                "type": "string"
              },
              "tool_calls": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "function"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "function": {
                      "type": "object",
                      "required": [
                        "name",
                        "arguments"
                      ],
                      "properties": {
                        "index": {
                          "type": "integer"
                        },
                        "name": {
                          "type": "string"
                        },
                        "arguments": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "done": {
            "type": "boolean"
          },
          "done_reason": {
            "enum": [
              "stop",
              "length",
              "load",
              "unload"
            ]
          },
          "total_duration": {
            "type": "integer",
            "description": "Nanoseconds."
          },
          "load_duration": {
            "type": "integer",
            "const": 0
          },
          "prompt_eval_count": {
            "type": "integer"
          },
          "prompt_eval_duration": {
            "type": "integer"
          },
          "eval_count": {
            "type": "integer"
          },
          "eval_duration": {
            "type": "integer"
          },
          "trellis": {
            "type": "object",
            "description": "On the closing object: the receipt and where the call was served.",
            "properties": {
              "receipt_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "lane": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "disclosure": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "policy_hash": {
                "type": "string"
              },
              "provider": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "cost_usd": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          }
        }
      },
      "OllamaGenerateResponse": {
        "type": "object",
        "required": [
          "model",
          "created_at",
          "done"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "response": {
            "type": "string"
          },
          "thinking": {
            "type": "string"
          },
          "done": {
            "type": "boolean"
          },
          "done_reason": {
            "enum": [
              "stop",
              "length",
              "load",
              "unload"
            ]
          },
          "total_duration": {
            "type": "integer",
            "description": "Nanoseconds."
          },
          "load_duration": {
            "type": "integer",
            "const": 0
          },
          "prompt_eval_count": {
            "type": "integer"
          },
          "prompt_eval_duration": {
            "type": "integer"
          },
          "eval_count": {
            "type": "integer"
          },
          "eval_duration": {
            "type": "integer"
          },
          "trellis": {
            "type": "object",
            "description": "On the closing object: the receipt and where the call was served.",
            "properties": {
              "receipt_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "lane": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "disclosure": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "policy_hash": {
                "type": "string"
              },
              "provider": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "cost_usd": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          }
        }
      },
      "OllamaErrorBody": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "TracingSettings": {
        "type": "object",
        "description": "Where to send one span per public-lane call made with this key. Calls on the attested and unlinkable lanes are never exported. URLs must be public https:// addresses. The endpoint, headers and keys are encrypted at rest and never returned. A secret left out of a PATCH keeps the stored one when the type is unchanged.",
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "otlp",
              "langfuse",
              "helicone"
            ],
            "description": "otlp: OTLP/HTTP JSON to your collector. langfuse: Langfuse public ingestion API. helicone: Helicone custom log API."
          },
          "endpoint": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "otlp: collector base URL; /v1/traces is appended unless present. No query string."
          },
          "headers": {
            "type": "object",
            "maxProperties": 16,
            "additionalProperties": {
              "type": "string",
              "maxLength": 4096
            },
            "description": "otlp: headers sent with every export, e.g. x-honeycomb-team or Authorization. Write-only."
          },
          "host": {
            "type": "string",
            "format": "uri",
            "description": "langfuse (default https://cloud.langfuse.com) or helicone (default https://api.worker.helicone.ai)."
          },
          "public_key": {
            "type": "string",
            "description": "langfuse public key."
          },
          "secret_key": {
            "type": "string",
            "writeOnly": true,
            "description": "langfuse secret key. Write-only."
          },
          "api_key": {
            "type": "string",
            "writeOnly": true,
            "description": "helicone API key. Write-only."
          },
          "include_content": {
            "type": "boolean",
            "default": false,
            "description": "Also export the prompt messages and the completion text. Off unless set."
          },
          "enabled": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "Tracing": {
        "type": "object",
        "description": "A key's tracing destination as the API returns it: no URL path, header value or secret.",
        "required": [
          "type",
          "enabled",
          "include_content",
          "target",
          "header_names",
          "secrets_set",
          "updated_at"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "otlp",
              "langfuse",
              "helicone"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "include_content": {
            "type": "boolean"
          },
          "target": {
            "type": "string",
            "description": "Scheme and host only, e.g. https://api.honeycomb.io/…"
          },
          "header_names": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "public_key_hint": {
            "type": [
              "string",
              "null"
            ],
            "description": "langfuse: the public key's first and last characters."
          },
          "secrets_set": {
            "type": "boolean",
            "const": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": [
              "object",
              "null"
            ],
            "description": "This router process's export counters for the key (GET /api/v1/keys/{hash} and PATCH only). null before the first export.",
            "properties": {
              "queued": {
                "type": "integer"
              },
              "exported": {
                "type": "integer"
              },
              "dropped": {
                "type": "integer",
                "description": "Dropped because the queue was full or the circuit was open."
              },
              "failed": {
                "type": "integer",
                "description": "Given up after retries."
              },
              "retries": {
                "type": "integer"
              },
              "circuit": {
                "type": "string",
                "enum": [
                  "closed",
                  "open",
                  "half_open"
                ]
              },
              "last_error": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "http_<status>, timeout, network or destination_blocked."
              },
              "last_success_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          }
        }
      },
      "RerankRequest": {
        "type": "object",
        "required": [
          "model",
          "query",
          "documents"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "A catalogue model whose architecture.output_modalities include rerank (GET /api/v1/models?output_modalities=rerank), optionally with :nitro (fastest providers first) or :floor (cheapest first)."
          },
          "query": {
            "type": "string",
            "minLength": 1
          },
          "documents": {
            "type": "array",
            "minItems": 1,
            "maxItems": 1000,
            "items": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "object",
                  "required": [
                    "text"
                  ],
                  "properties": {
                    "text": {
                      "type": "string"
                    }
                  }
                }
              ]
            },
            "description": "Strings, or objects with a text. Sent to the provider as strings."
          },
          "top_n": {
            "type": "integer",
            "minimum": 1,
            "description": "How many results to return, best first. Default: every document."
          },
          "return_documents": {
            "type": "boolean",
            "default": false,
            "description": "Attach each result's document text (the text you sent)."
          },
          "provider": {
            "$ref": "#/components/schemas/ProviderPreferences"
          }
        }
      },
      "RerankResult": {
        "type": "object",
        "required": [
          "index",
          "relevance_score"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0,
            "description": "Position of the document in the request."
          },
          "relevance_score": {
            "type": "number",
            "description": "The provider's score. The router checks it and never makes one up."
          },
          "document": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string"
              }
            },
            "description": "Present when return_documents is true."
          }
        }
      },
      "RerankResponse": {
        "type": "object",
        "required": [
          "id",
          "model",
          "results",
          "usage",
          "cost",
          "receipt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Generation and receipt id (also X-Receipt-Id)."
          },
          "object": {
            "type": "string",
            "const": "rerank"
          },
          "model": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RerankResult"
            },
            "description": "Best first, ties by index, at most top_n."
          },
          "usage": {
            "type": "object",
            "required": [
              "total_tokens",
              "search_units",
              "cost"
            ],
            "properties": {
              "total_tokens": {
                "type": "integer"
              },
              "search_units": {
                "type": "integer",
                "description": "One query over up to 100 documents, each split into chunks of 500 tokens."
              },
              "estimated": {
                "type": "boolean",
                "description": "true when the provider did not report a quantity it is priced on and the router's estimate was billed."
              },
              "cost": {
                "type": "number"
              },
              "cost_details": {
                "type": "object"
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "billed_units": {
                "type": "object",
                "properties": {
                  "search_units": {
                    "type": "integer"
                  }
                }
              }
            },
            "description": "The billed search units where Cohere clients read them."
          },
          "cost": {
            "type": "number",
            "description": "USD charged for this call."
          },
          "receipt": {
            "$ref": "#/components/schemas/Receipt"
          }
        }
      },
      "Team": {
        "type": "object",
        "required": [
          "id",
          "name",
          "created_at",
          "owner",
          "budget_usd",
          "allocated_usd",
          "your_role",
          "members",
          "principals",
          "audit"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "owner": {
            "type": "object",
            "required": [
              "account",
              "address",
              "kind",
              "verified_at"
            ],
            "properties": {
              "account": {
                "type": "string"
              },
              "address": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The bound wallet's base58 Solana address (case-sensitive), or null for an account owner."
              },
              "kind": {
                "type": "string",
                "enum": [
                  "account",
                  "wallet",
                  "multisig"
                ],
                "description": "account: owned by the creating account; wallet: a Solana wallet that signed the challenge; multisig: reserved for vault owners (not bindable yet)."
              },
              "verified_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          },
          "budget_usd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Org budget: a cap on the sum of the limits of the team's keys."
          },
          "allocated_usd": {
            "type": "number",
            "description": "The limits of the team's enabled, unexpired keys, summed."
          },
          "your_role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "dev",
              "member",
              "viewer",
              "agent"
            ]
          },
          "members": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key_hash": {
                  "type": "string"
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "owner",
                    "admin",
                    "dev",
                    "member",
                    "viewer",
                    "agent"
                  ]
                },
                "principal": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "name": {
                  "type": "string"
                },
                "disabled": {
                  "type": "boolean"
                }
              }
            }
          },
          "principals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TeamPrincipal"
            }
          },
          "audit": {
            "type": "object",
            "properties": {
              "entries": {
                "type": "integer"
              },
              "head": {
                "type": "string",
                "description": "The chain's head hash (64 zeros when empty)."
              }
            }
          }
        }
      },
      "TeamPrincipal": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "subject",
          "role",
          "disabled",
          "created_at",
          "last_used"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "passkey",
              "wallet"
            ]
          },
          "subject": {
            "type": "string",
            "description": "A wallet address, or the first 16 characters of a passkey's credential id."
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "dev",
              "viewer"
            ]
          },
          "disabled": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "TeamInviteRequest": {
        "type": "object",
        "required": [
          "role"
        ],
        "additionalProperties": false,
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "dev",
              "viewer"
            ],
            "description": "Agents are API keys (POST /api/v1/keys with role agent), not invited people. Only the owner invites an admin."
          },
          "method": {
            "type": "string",
            "enum": [
              "passkey",
              "wallet",
              "any"
            ],
            "default": "any"
          },
          "ttl_hours": {
            "type": "integer",
            "minimum": 1,
            "maximum": 168,
            "default": 72
          }
        }
      },
      "TeamSignedIn": {
        "type": "object",
        "required": [
          "data",
          "key"
        ],
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "team": {
                "type": "string"
              },
              "principal": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "passkey",
                      "wallet"
                    ]
                  },
                  "role": {
                    "type": "string"
                  }
                }
              },
              "key": {
                "type": "object",
                "description": "The issued key (same shape as GET /api/v1/key): it expires after 12 hours and has a limit of 0."
              }
            }
          },
          "key": {
            "type": "string",
            "description": "The secret, shown once."
          }
        }
      },
      "TeamAuditEntry": {
        "type": "object",
        "required": [
          "team",
          "seq",
          "at",
          "actor",
          "action",
          "target",
          "detail",
          "prev_hash",
          "hash"
        ],
        "properties": {
          "team": {
            "type": "string"
          },
          "seq": {
            "type": "integer",
            "minimum": 1
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "actor": {
            "type": "string",
            "description": "key:<16 hex>, passkey:<member id> or wallet:<address>."
          },
          "action": {
            "type": "string",
            "enum": [
              "team.create",
              "team.rename",
              "budget.set",
              "owner.bind",
              "invite.create",
              "member.join",
              "member.role",
              "member.revoke",
              "member.restore",
              "key.create",
              "key.update",
              "key.disable",
              "preset.save",
              "preset.rollback",
              "preset.delete",
              "route.create",
              "route.update",
              "route.delete"
            ]
          },
          "target": {
            "type": "string"
          },
          "detail": {
            "type": "object",
            "description": "A few fixed fields about the change (role, limit, lane, version, hash). Never prompt text."
          },
          "prev_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "sha256(bytes(prev_hash) || utf8(canonical JSON of {team, seq, at, actor, action, target, detail})), keys sorted recursively."
          }
        }
      },
      "TeamAuditRoot": {
        "type": "object",
        "required": [
          "hour",
          "first_seq",
          "last_seq",
          "count",
          "root"
        ],
        "properties": {
          "hour": {
            "type": "string",
            "format": "date-time"
          },
          "first_seq": {
            "type": "integer"
          },
          "last_seq": {
            "type": "integer"
          },
          "count": {
            "type": "integer"
          },
          "root": {
            "type": "string",
            "description": "RFC 6962 Merkle root over the raw 32-byte entry hashes of that UTC hour."
          }
        }
      },
      "WalletChallenge": {
        "type": "object",
        "properties": {
          "challenge_id": {
            "type": "string"
          },
          "nonce": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "The exact text to sign: the wallet signs its UTF-8 bytes with its ed25519 key (solana:signMessage); send the 64-byte signature base58."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TeamChallenge": {
        "type": "object",
        "properties": {
          "challenge_id": {
            "type": "string"
          },
          "method": {
            "type": "string",
            "enum": [
              "passkey",
              "wallet"
            ]
          },
          "message": {
            "type": "string",
            "description": "Wallet: the message to sign."
          },
          "publicKey": {
            "type": "object",
            "description": "Passkey: WebAuthn options with base64url binary fields (PublicKeyCredentialCreationOptions to join, PublicKeyCredentialRequestOptions to sign in). Attestation is none; sign-in uses discoverable passkeys and lists no credentials."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "StatusIncident": {
        "type": "object",
        "required": [
          "id",
          "title",
          "status",
          "impact",
          "lanes",
          "surfaces",
          "source",
          "started_at",
          "resolved_at",
          "updated_at",
          "updates"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "suggested",
              "investigating",
              "identified",
              "monitoring",
              "resolved",
              "dismissed"
            ],
            "description": "suggested and dismissed are seen only by the operator."
          },
          "impact": {
            "type": "string",
            "enum": [
              "none",
              "minor",
              "major",
              "critical"
            ]
          },
          "lanes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "public",
                "attested",
                "unlinkable"
              ]
            },
            "minItems": 1
          },
          "surfaces": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "chat",
                "embeddings",
                "batch",
                "messages",
                "ollama",
                "rerank"
              ]
            },
            "description": "Empty for all surfaces."
          },
          "source": {
            "type": "string",
            "enum": [
              "operator",
              "auto"
            ]
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          },
          "resolved_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "updates": {
            "type": "array",
            "description": "Newest first.",
            "items": {
              "type": "object",
              "required": [
                "at",
                "status",
                "text"
              ],
              "properties": {
                "at": {
                  "type": "string",
                  "format": "date-time"
                },
                "status": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                }
              }
            }
          },
          "evidence": {
            "type": "object",
            "description": "Automatic suggestions only: lanes, surfaces, window (5m for the public lane, 1h for the private lanes), availability, target, requests and source (request-aggregates or dp-noised)."
          }
        }
      },
      "StatusSlo": {
        "type": "object",
        "required": [
          "object",
          "generated_at",
          "windows",
          "targets",
          "lanes",
          "surfaces",
          "incidents"
        ],
        "properties": {
          "object": {
            "const": "status.slo"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "cache_seconds": {
            "type": "integer"
          },
          "windows": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "1h",
                "24h",
                "7d",
                "30d"
              ]
            }
          },
          "targets": {
            "type": "object",
            "description": "Availability target per lane, as a fraction (STATUS_SLO_PUBLIC 0.995, STATUS_SLO_ATTESTED 0.99, STATUS_SLO_UNLINKABLE 0.99)."
          },
          "lanes": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "lane",
                "source",
                "target",
                "state",
                "windows",
                "latency_24h",
                "error_budget",
                "daily"
              ],
              "properties": {
                "lane": {
                  "type": "string",
                  "enum": [
                    "public",
                    "attested",
                    "unlinkable"
                  ]
                },
                "source": {
                  "type": "string",
                  "enum": [
                    "request-aggregates",
                    "dp-noised"
                  ],
                  "description": "dp-noised: every figure is summed from the differentially private hourly releases, never from per-request records."
                },
                "target": {
                  "type": "number"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "operational",
                    "degraded",
                    "outage",
                    "no_data"
                  ]
                },
                "scope": {
                  "type": "string",
                  "description": "Private lanes: attested+unlinkable, because the two lanes share one set of noisy counters."
                },
                "windows": {
                  "type": "object",
                  "description": "Per window (1h, 24h, 7d, 30d): availability (null without enough data), eligible requests (5xx and successes; 4xx and 429 are left out) and error counts by class."
                },
                "latency_24h": {
                  "type": "object",
                  "description": "p50_ms and p95_ms as the upper edge of the fixed latency bucket each falls in. Public lane: time to first token for streams, full response otherwise. Private lanes: total generation time, the only latency the noisy counters keep."
                },
                "error_budget": {
                  "type": "object",
                  "description": "Over 30 days: allowed_failures, failures, remaining (share of the budget unspent) and exhausted."
                },
                "daily": {
                  "type": "array",
                  "description": "90 UTC days, oldest first: availability (null without data) and eligible requests.",
                  "items": {
                    "type": "object"
                  }
                },
                "privacy": {
                  "type": "object",
                  "description": "Private lanes: mechanism, epsilon per hour, noise scale and the minimum noisy eligible count before a share is shown."
                }
              }
            }
          },
          "surfaces": {
            "type": "array",
            "description": "Per API surface, public lane only. rerank appears only where the router serves it.",
            "items": {
              "type": "object"
            }
          },
          "synthetic_24h": {
            "type": "object",
            "description": "Provider probes and canaries over 24 hours."
          },
          "incidents": {
            "type": "object",
            "properties": {
              "open": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/StatusIncident"
                }
              },
              "recent": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/StatusIncident"
                }
              }
            }
          }
        }
      },
      "CharacterCard": {
        "type": "object",
        "description": "A Tavern character card in its canonical form. card_hash is the SHA-256 of this object as canonical JSON.",
        "required": [
          "spec",
          "spec_version",
          "data"
        ],
        "properties": {
          "spec": {
            "type": "string",
            "enum": [
              "chara_card_v2",
              "chara_card_v3"
            ]
          },
          "spec_version": {
            "type": "string",
            "examples": [
              "2.0",
              "3.0"
            ]
          },
          "data": {
            "type": "object",
            "description": "The card's fields as the Tavern character card V2 and V3 specs define them. A V1 card (flat fields) is read as V2. Fields the router does not use are kept as they are.",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "personality": {
                "type": "string"
              },
              "scenario": {
                "type": "string"
              },
              "first_mes": {
                "type": "string",
                "description": "The first greeting (greeting index 0)."
              },
              "mes_example": {
                "type": "string"
              },
              "system_prompt": {
                "type": "string"
              },
              "post_history_instructions": {
                "type": "string"
              },
              "alternate_greetings": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Greetings 1, 2, 3 and so on."
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "creator": {
                "type": "string"
              },
              "creator_notes": {
                "type": "string"
              },
              "character_version": {
                "type": "string"
              },
              "character_book": {
                "type": "object",
                "description": "The lorebook: entries with keys and content."
              },
              "extensions": {
                "type": "object"
              }
            }
          }
        }
      },
      "Character": {
        "type": "object",
        "required": [
          "id",
          "model",
          "visibility",
          "name",
          "tags",
          "creator",
          "spec",
          "card_hash",
          "default_model",
          "owner",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^ch_[0-9a-f]{24}$"
          },
          "model": {
            "type": "string",
            "description": "The model id that calls this character: @character/<id>."
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "unlisted",
              "private"
            ],
            "description": "public: listed in discovery and readable by anyone. unlisted: readable by anyone with the id, not listed. private: sealed on the owner's device; only the owner can read it."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "null for a private card: the router never sees it."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "creator": {
            "type": [
              "string",
              "null"
            ]
          },
          "spec": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "chara_card_v2",
              "chara_card_v3",
              null
            ],
            "description": "null for a private card."
          },
          "card_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "SHA-256 of the canonical card JSON. For a private card the client computes it before sealing, and a chat call's decrypted card is checked against it."
          },
          "default_model": {
            "type": [
              "string",
              "null"
            ],
            "description": "The model that answers when a call names none (no models[0])."
          },
          "card": {
            "$ref": "#/components/schemas/CharacterCard",
            "description": "Public and unlisted cards only."
          },
          "sealed_card": {
            "type": "string",
            "description": "Private cards, to the owner only: the card encrypted on the owner's device (arm1.<iv>.<ciphertext>). The router cannot read it."
          },
          "owner": {
            "type": "boolean",
            "description": "true when the calling key owns this card."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CharacterInput": {
        "type": "object",
        "additionalProperties": false,
        "description": "Send the card as JSON (card) or as a PNG that carries it (png). A private card is sealed on the client instead: send sealed_card and card_hash, never the plaintext.",
        "properties": {
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "unlisted",
              "private"
            ],
            "default": "unlisted"
          },
          "card": {
            "type": "object",
            "description": "A Tavern character card: V1 (flat fields), V2 (chara_card_v2) or V3 (chara_card_v3) JSON."
          },
          "png": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "A PNG, base64, that carries the card in a ccv3 or chara tEXt chunk (ccv3 wins when both are present)."
          },
          "model": {
            "type": "string",
            "description": "The default model for @character/<id>."
          },
          "sealed_card": {
            "type": "string",
            "description": "Private only: the card encrypted on the client (sealCard in @trellis/client/characters). The router stores it as it is and never sees the plaintext."
          },
          "card_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "Private only: the SHA-256 of the canonical card JSON, computed before sealing."
          }
        }
      },
      "CharacterChatRequest": {
        "description": "A chat completions request plus the character options. The character's prompt is built by the router from the card; lanes, budgets and receipts apply as on /chat/completions. model, when set, is the model that answers; otherwise models[0], then the card's default model.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ChatRequest"
          },
          {
            "type": "object",
            "properties": {
              "session_id": {
                "type": "string",
                "description": "Your own id for a conversation, so regenerate knows which turn to redo."
              },
              "greeting": {
                "type": "integer",
                "minimum": 0,
                "description": "Which greeting opens the chat: 0 is first_mes, 1 and up are alternate_greetings."
              },
              "regenerate": {
                "type": "boolean",
                "description": "Answer the last user turn again."
              },
              "user_name": {
                "type": "string",
                "description": "Replaces {{user}} in the card."
              },
              "memory": {
                "type": "object",
                "description": "Memory the client decrypted from its ledger. Used for this call, in memory only, and never stored.",
                "properties": {
                  "summary": {
                    "type": "string"
                  },
                  "facts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              },
              "card": {
                "type": "object",
                "description": "Private cards only: the card decrypted on the client. It must hash to the character's card_hash, or the call is refused."
              }
            }
          }
        ]
      },
      "CharacterUsage": {
        "type": "object",
        "required": [
          "period",
          "calls",
          "cost_usd"
        ],
        "properties": {
          "period": {
            "type": "string",
            "format": "date",
            "description": "YYYY-MM-DD"
          },
          "calls": {
            "type": "integer"
          },
          "cost_usd": {
            "type": "number"
          }
        }
      },
      "CharacterGroupNextRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "members",
          "messages"
        ],
        "properties": {
          "members": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "pattern": "^ch_[0-9a-f]{24}$"
            },
            "description": "The characters in the group chat, in order."
          },
          "mode": {
            "type": "string",
            "enum": [
              "round_robin",
              "named"
            ],
            "default": "round_robin",
            "description": "round_robin: the next member after the last speaker. named: the member the last message names, else round robin."
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "The chat so far, as chat completions messages; an assistant message's name is the character that spoke."
          }
        }
      },
      "MemoryInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "scope",
          "kind",
          "sealed",
          "key_id"
        ],
        "properties": {
          "scope": {
            "type": "string",
            "pattern": "^[0-9a-f]{16,128}$",
            "description": "Derived on the client: an HMAC of the character id under the viewing key, so the router cannot tell which character a memory belongs to."
          },
          "kind": {
            "type": "string",
            "enum": [
              "summary",
              "fact",
              "lorebook",
              "state"
            ]
          },
          "sealed": {
            "type": "string",
            "pattern": "^arm1\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$",
            "description": "arm1.<base64url iv>.<base64url ciphertext>, encrypted on the client. The router stores only this."
          },
          "key_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{16}$",
            "description": "Which of the client's keys sealed it."
          },
          "embedding": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Stored only with embedding_opt_in: true."
          },
          "embedding_opt_in": {
            "const": true,
            "description": "Store the embedding for POST /api/v1/memory/search. Off by default: a vector is derived from the memory's text and can leak its topic."
          }
        }
      },
      "MemoryEntry": {
        "type": "object",
        "required": [
          "id",
          "scope",
          "kind",
          "key_id",
          "bytes",
          "has_embedding",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "summary",
              "fact",
              "lorebook",
              "state"
            ]
          },
          "key_id": {
            "type": "string"
          },
          "bytes": {
            "type": "integer",
            "description": "Size of the sealed value."
          },
          "has_embedding": {
            "type": "boolean"
          },
          "dims": {
            "type": [
              "integer",
              "null"
            ]
          },
          "sealed": {
            "type": "string",
            "description": "Only when one entry is read (GET /api/v1/memory/{id})."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MemorySearchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "scope",
          "embedding"
        ],
        "properties": {
          "scope": {
            "type": "string"
          },
          "embedding": {
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "k": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 5
          }
        }
      },
      "SkillFinding": {
        "type": "object",
        "required": [
          "rule",
          "file",
          "line",
          "excerpt",
          "severity",
          "message"
        ],
        "properties": {
          "rule": {
            "type": "string",
            "description": "Rule id, e.g. exfil.env_to_network, injection.override, obfuscation.base64_blob, shell.rm_root, deps.untrusted_index, binary.executable."
          },
          "file": {
            "type": "string"
          },
          "line": {
            "type": [
              "integer",
              "null"
            ]
          },
          "excerpt": {
            "type": "string",
            "description": "Up to 160 characters of the line, with hidden characters shown escaped."
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "low",
              "medium",
              "high",
              "critical"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "SkillScanReport": {
        "type": "object",
        "required": [
          "scanner",
          "score",
          "level",
          "summary",
          "findings",
          "note"
        ],
        "properties": {
          "scanner": {
            "type": "string",
            "example": "skillscan/1"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "100 minus a weight per distinct rule and file: low 3, medium 10, high 25, critical 50."
          },
          "level": {
            "type": "string",
            "enum": [
              "trusted",
              "caution",
              "dangerous"
            ],
            "description": "dangerous with any high or critical finding or a score under 40; caution with any medium finding or a score under 90; trusted otherwise."
          },
          "summary": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SkillFinding"
            }
          },
          "truncated": {
            "type": "boolean"
          },
          "files_scanned": {
            "type": "integer"
          },
          "bytes_scanned": {
            "type": "integer"
          },
          "note": {
            "type": "string",
            "description": "Scanned, not guaranteed."
          }
        }
      },
      "SkillSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "author": {
            "type": "string"
          },
          "content_hash": {
            "type": "string",
            "description": "sha256 (hex) of the canonical tar of the skill's files."
          },
          "level": {
            "type": "string",
            "enum": [
              "trusted",
              "caution",
              "dangerous"
            ]
          },
          "score": {
            "type": "integer"
          },
          "findings": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "price_usd": {
            "type": "number"
          },
          "files": {
            "type": "integer"
          },
          "size": {
            "type": "integer"
          },
          "source": {
            "type": "string",
            "enum": [
              "upload",
              "git",
              "mirror"
            ]
          },
          "revoked": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Skill": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SkillSummary"
          },
          {
            "type": "object",
            "properties": {
              "manifest": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "author": {
                    "type": "string"
                  }
                }
              },
              "files": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "file",
                        "symlink"
                      ]
                    },
                    "mode": {
                      "type": "integer"
                    },
                    "size": {
                      "type": "integer"
                    },
                    "sha256": {
                      "type": "string"
                    }
                  }
                }
              },
              "source": {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "upload",
                      "git",
                      "mirror"
                    ]
                  },
                  "repo": {
                    "type": "string"
                  },
                  "ref": {
                    "type": "string"
                  },
                  "commit": {
                    "type": "string"
                  },
                  "path": {
                    "type": "string"
                  },
                  "registry": {
                    "type": "string"
                  }
                }
              },
              "scan": {
                "$ref": "#/components/schemas/SkillScanReport"
              },
              "downloadable": {
                "type": "boolean"
              },
              "revoked_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "revoked_reason": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "installs": {
                "type": "integer"
              },
              "chain": {
                "type": "object",
                "description": "Arguments for SkillRegistry.publish(skillHash, author, priceUSDC, trustLevel, uri).",
                "properties": {
                  "skill_hash": {
                    "type": "string"
                  },
                  "trust_level": {
                    "type": "integer",
                    "enum": [
                      1,
                      2,
                      3
                    ]
                  },
                  "price_usdc": {
                    "type": "string"
                  },
                  "uri": {
                    "type": "string"
                  }
                }
              }
            }
          }
        ]
      },
      "SkillInstall": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "skill_id": {
            "type": "string"
          },
          "price_usd": {
            "type": "number"
          },
          "author_usd": {
            "type": "number"
          },
          "fee_usd": {
            "type": "number"
          },
          "download_url": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "receipt": {
            "type": "object",
            "description": "Ed25519 signature (receipt key) over the canonical JSON of payload.",
            "properties": {
              "payload": {
                "type": "object"
              },
              "signature": {
                "type": "object",
                "properties": {
                  "alg": {
                    "type": "string",
                    "enum": [
                      "Ed25519"
                    ]
                  },
                  "key_id": {
                    "type": "string"
                  },
                  "sig": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "HostPolicy": {
        "type": "object",
        "properties": {
          "version": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 2147483647
          },
          "issued_at": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
          },
          "tee_kinds": {
            "minItems": 1,
            "maxItems": 3,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "tdx",
                "snp",
                "nvidia-cc"
              ]
            }
          },
          "sidecar": {
            "type": "object",
            "properties": {
              "image_digests": {
                "minItems": 1,
                "maxItems": 128,
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^sha256:[0-9a-f]{64}$"
                }
              },
              "source_hashes": {
                "minItems": 1,
                "maxItems": 128,
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^sha256:[0-9a-f]{64}$"
                }
              }
            },
            "required": [
              "image_digests",
              "source_hashes"
            ],
            "additionalProperties": false
          },
          "engines": {
            "minItems": 1,
            "maxItems": 128,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160,
                  "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$"
                },
                "image_digest": {
                  "type": "string",
                  "pattern": "^sha256:[0-9a-f]{64}$"
                }
              },
              "required": [
                "name",
                "image_digest"
              ],
              "additionalProperties": false
            }
          },
          "models": {
            "minItems": 1,
            "maxItems": 128,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160,
                  "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$"
                },
                "model_digest": {
                  "type": "string",
                  "pattern": "^sha256:[0-9a-f]{64}$"
                },
                "offer": {
                  "$ref": "#/components/schemas/HostPolicyOffer"
                },
                "min_gpu_cc": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "model_digest",
                "min_gpu_cc"
              ],
              "additionalProperties": false
            }
          },
          "rules": {
            "type": "object",
            "properties": {
              "require_gpu_cc_for": {
                "maxItems": 128,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160,
                  "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$"
                }
              },
              "allow_dev": {
                "type": "boolean",
                "const": false
              }
            },
            "required": [
              "require_gpu_cc_for",
              "allow_dev"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "version",
          "issued_at",
          "tee_kinds",
          "sidecar",
          "engines",
          "models",
          "rules"
        ],
        "additionalProperties": false
      },
      "HostPolicyOffer": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "slug",
          "name",
          "context_length",
          "max_completion_tokens",
          "pricing"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "pattern": "^[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "hugging_face_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$"
          },
          "context_length": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647
          },
          "max_completion_tokens": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647
          },
          "quantization": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32,
            "pattern": "^[A-Za-z0-9._+-]+$"
          },
          "pricing": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "prompt",
              "completion"
            ],
            "properties": {
              "prompt": {
                "type": "string",
                "minLength": 1,
                "maxLength": 32,
                "pattern": "^[0-9]+(\\.[0-9]+)?$",
                "description": "Positive decimal USD per token, at most 1000000."
              },
              "completion": {
                "type": "string",
                "minLength": 1,
                "maxLength": 32,
                "pattern": "^[0-9]+(\\.[0-9]+)?$",
                "description": "Positive decimal USD per token, at most 1000000."
              }
            }
          }
        }
      },
      "HostPolicyPublication": {
        "type": "object",
        "required": [
          "policy",
          "canonical",
          "sha256",
          "signature",
          "transparency_log"
        ],
        "properties": {
          "policy": {
            "$ref": "#/components/schemas/HostPolicy"
          },
          "canonical": {
            "type": "string",
            "description": "Exact UTF-8 canonical policy bytes: sorted object keys, retained array order, no whitespace or trailing newline."
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "signature": {
            "type": "object",
            "required": [
              "alg",
              "value",
              "verifier_key"
            ],
            "properties": {
              "alg": {
                "const": "Ed25519"
              },
              "value": {
                "type": "string",
                "description": "Base64 detached Ed25519 signature over canonical UTF-8 bytes."
              },
              "verifier_key": {
                "type": "string",
                "description": "C2SP signed-note verifier key. Pin independently; this response alone does not authenticate the operator."
              }
            }
          },
          "transparency_log": {
            "type": "object",
            "required": [
              "kind",
              "proof_url"
            ],
            "properties": {
              "kind": {
                "const": "host_policy"
              },
              "proof_url": {
                "type": "string",
                "description": "Inclusion proof under a signed checkpoint; independent checkpoint checks are separate."
              }
            }
          }
        }
      },
      "AgentRecordClaims": {
        "type": "array",
        "minItems": 1,
        "maxItems": 16,
        "uniqueItems": true,
        "items": {
          "type": "string",
          "pattern": "^(requests_at_least|active_days_at_least|no_denials_days|no_kills_days):[1-9][0-9]{0,14}$"
        },
        "description": "Positive integer thresholds. Absence windows are at most 90 days and require an unchanged effective rulebook for the full interval. Counts use the calling key’s retained completed non-cancelled generations; active days are distinct UTC dates. No autonomy rung claim is available."
      },
      "AgentRecordCertificate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "payload",
          "key_id",
          "signature"
        ],
        "properties": {
          "key_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{16}$"
          },
          "signature": {
            "type": "string",
            "pattern": "^[A-Za-z0-9+/]{86}==$"
          },
          "payload": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "version",
              "type",
              "pseudonym",
              "claims",
              "issued_at",
              "expires_at",
              "notice"
            ],
            "properties": {
              "version": {
                "const": 1
              },
              "type": {
                "const": "trellis.agent.record-certificate"
              },
              "pseudonym": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              "claims": {
                "$ref": "#/components/schemas/AgentRecordClaims"
              },
              "issued_at": {
                "type": "string",
                "format": "date-time"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "description": "Exactly seven days after issuance."
              },
              "notice": {
                "const": "Signed by Trellis's router, which sees the agent's activity; not a zero-knowledge proof."
              }
            }
          }
        }
      },
      "ToolCallRequest": {
        "type": "object",
        "required": [
          "resource",
          "max_price"
        ],
        "additionalProperties": false,
        "properties": {
          "resource": {
            "type": "string",
            "maxLength": 2048,
            "description": "The tool's https address, with its query arguments. Only the origin and path are stored."
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST"
            ],
            "default": "GET"
          },
          "body": {
            "description": "JSON sent to the tool as a POST body, at most 64 KiB."
          },
          "max_price": {
            "oneOf": [
              {
                "type": "number",
                "exclusiveMinimum": 0
              },
              {
                "type": "string",
                "pattern": "^[0-9]{1,7}(\\.[0-9]{1,12})?$"
              }
            ],
            "description": "The most this call may charge the key in USD: the seller's price plus the router's take."
          },
          "then": {
            "type": "object",
            "required": [
              "model"
            ],
            "additionalProperties": false,
            "description": "Hand the answer to a model in the same call; needs tools.pass_to_models.",
            "properties": {
              "model": {
                "type": "string"
              },
              "prompt": {
                "type": "string",
                "maxLength": 4000
              },
              "max_tokens": {
                "type": "integer",
                "minimum": 1,
                "maximum": 8192
              }
            }
          }
        }
      },
      "ToolCall": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "resource": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "seller": {
            "type": "object",
            "properties": {
              "pay_to": {
                "type": "string"
              },
              "seller_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "network": {
                "type": "string"
              }
            }
          },
          "x402_version": {
            "type": "integer",
            "enum": [
              1,
              2
            ]
          },
          "price_usd": {
            "type": "number"
          },
          "take_usd": {
            "type": "number"
          },
          "charged_usd": {
            "type": "number"
          },
          "settle": {
            "type": "object",
            "properties": {
              "tx": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "network": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "response": {
            "type": "object",
            "description": "The tool's answer, untrusted: json or text, with status, content_type, bytes and sha256.",
            "properties": {
              "status": {
                "type": "integer"
              },
              "content_type": {
                "type": "string"
              },
              "bytes": {
                "type": "integer"
              },
              "sha256": {
                "type": "string"
              },
              "untrusted": {
                "type": "boolean"
              },
              "json": {},
              "text": {
                "type": "string"
              }
            }
          },
          "receipt": {
            "type": "object",
            "description": "kind tool.call: COSE_Sign1 (base64) under the receipt key, key_id, leaf and the signed claims.",
            "properties": {
              "id": {
                "type": "string"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "tool.call"
                ]
              },
              "key_id": {
                "type": "string"
              },
              "cose": {
                "type": "string"
              },
              "leaf": {
                "type": "string"
              },
              "claims": {
                "type": "object"
              }
            }
          },
          "model": {
            "type": "object",
            "description": "Present when then was set."
          }
        }
      },
      "ToolListing": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "resource": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "price_usd": {
            "type": [
              "number",
              "null"
            ]
          },
          "price_units": {
            "type": [
              "string",
              "null"
            ]
          },
          "pay_to": {
            "type": [
              "string",
              "null"
            ]
          },
          "network": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "listing",
              "skill",
              "facilitator",
              "public_catalog"
            ]
          },
          "skill_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "quality": {
            "type": "object",
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "passing",
                  "failing",
                  "delisted",
                  "unchecked"
                ]
              },
              "consecutive_failures": {
                "type": "integer"
              },
              "checked_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "delisted_at": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      },
      "ToolListingRequest": {
        "type": "object",
        "required": [
          "name",
          "summary",
          "resource",
          "canary"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "summary": {
            "type": "string",
            "maxLength": 280
          },
          "resource": {
            "type": "string",
            "description": "https address without a query string."
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST"
            ],
            "default": "GET"
          },
          "skill_id": {
            "type": "string",
            "pattern": "^sk_[0-9a-f]{24}$"
          },
          "canary": {
            "type": "object",
            "required": [
              "expect"
            ],
            "additionalProperties": false,
            "properties": {
              "query": {
                "type": "string"
              },
              "body": {},
              "expect": {
                "type": "object",
                "description": "Exactly one of contains or sha256.",
                "properties": {
                  "contains": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "sha256": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{64}$"
                  }
                }
              }
            }
          }
        }
      },
      "CommerceStats": {
        "type": "object",
        "required": [
          "as_of",
          "cache_seconds",
          "currency",
          "kinds",
          "filters",
          "windows",
          "methodology_url",
          "dune_query"
        ],
        "properties": {
          "as_of": {
            "type": "string",
            "format": "date-time"
          },
          "cache_seconds": {
            "type": "integer",
            "const": 60
          },
          "currency": {
            "type": "object",
            "properties": {
              "asset": {
                "type": "string",
                "const": "USDC"
              },
              "decimals": {
                "type": "integer",
                "const": 6
              },
              "units": {
                "type": "string"
              }
            }
          },
          "kinds": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "kind",
                "label",
                "wired"
              ],
              "properties": {
                "kind": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "wired": {
                  "type": "boolean",
                  "description": "Whether anything reports settlements of this kind to the ledger"
                }
              }
            }
          },
          "filters": {
            "type": "object",
            "properties": {
              "anchored_only": {
                "type": "boolean",
                "const": true
              },
              "same_owner": {
                "type": "boolean",
                "const": true
              },
              "round_trip_hours": {
                "type": "integer",
                "const": 24
              },
              "funding": {
                "type": "object",
                "required": [
                  "available",
                  "hops",
                  "min_units",
                  "hub_fanout",
                  "from_block",
                  "indexed_block",
                  "indexed_at"
                ],
                "properties": {
                  "available": {
                    "type": "boolean"
                  },
                  "hops": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 3
                  },
                  "min_units": {
                    "type": "string",
                    "pattern": "^[0-9]+$"
                  },
                  "hub_fanout": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "from_block": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "pattern": "^[0-9]+$"
                  },
                  "indexed_block": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "pattern": "^[0-9]+$"
                  },
                  "indexed_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  }
                }
              }
            }
          },
          "windows": {
            "type": "object",
            "required": [
              "24h",
              "7d",
              "30d"
            ],
            "properties": {
              "24h": {
                "$ref": "#/components/schemas/CommerceWindow"
              },
              "7d": {
                "$ref": "#/components/schemas/CommerceWindow"
              },
              "30d": {
                "$ref": "#/components/schemas/CommerceWindow"
              }
            }
          },
          "methodology_url": {
            "type": "string"
          },
          "dune_query": {
            "type": "string"
          }
        }
      },
      "CommerceWindow": {
        "type": "object",
        "required": [
          "from",
          "to",
          "total",
          "kinds"
        ],
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          },
          "total": {
            "$ref": "#/components/schemas/CommerceBlock"
          },
          "kinds": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/CommerceBlock"
            }
          }
        }
      },
      "CommerceBlock": {
        "type": "object",
        "required": [
          "gross",
          "filtered",
          "excluded"
        ],
        "properties": {
          "gross": {
            "$ref": "#/components/schemas/CommerceFigures"
          },
          "filtered": {
            "$ref": "#/components/schemas/CommerceFigures"
          },
          "excluded": {
            "type": "object",
            "required": [
              "unanchored",
              "same_owner",
              "round_trip",
              "funding_link"
            ],
            "properties": {
              "unanchored": {
                "type": "integer",
                "minimum": 0
              },
              "same_owner": {
                "type": "integer",
                "minimum": 0
              },
              "round_trip": {
                "type": "integer",
                "minimum": 0
              },
              "funding_link": {
                "type": "integer",
                "minimum": 0
              }
            },
            "description": "Each excluded settlement is counted once, under the first rule it fails"
          }
        }
      },
      "CommerceFigures": {
        "type": "object",
        "required": [
          "settlements",
          "payers",
          "payees",
          "volume_usdc",
          "median_price_usdc",
          "refunds",
          "refund_rate"
        ],
        "properties": {
          "settlements": {
            "type": "integer",
            "minimum": 0
          },
          "payers": {
            "type": "integer",
            "minimum": 0
          },
          "payees": {
            "type": "integer",
            "minimum": 0
          },
          "volume_usdc": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "median_price_usdc": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[0-9]+$",
            "description": "The middle amount, or the floor of the mean of the two middle amounts; null when there are none"
          },
          "refunds": {
            "type": "integer",
            "minimum": 0
          },
          "refund_rate": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 1,
            "description": "Refunded over settlements, to four decimals; null when there are none"
          }
        }
      },
      "DataToolCharge": {
        "type": "object",
        "required": [
          "usd",
          "paid_with",
          "payment_tx"
        ],
        "properties": {
          "usd": {
            "type": "string",
            "description": "What this call was charged, in USD (DATA_TOOLS_PRICE_USD, default 0.001)."
          },
          "paid_with": {
            "type": "string",
            "enum": [
              "key",
              "per_call"
            ]
          },
          "payment_tx": {
            "type": [
              "string",
              "null"
            ],
            "description": "The settling transaction of a per-call payment; null for a key."
          }
        }
      },
      "DataToolsIndex": {
        "type": "object",
        "properties": {
          "price_usd": {
            "type": "number"
          },
          "payment": {
            "type": "object",
            "properties": {
              "prepaid_key": {
                "type": "boolean"
              },
              "x402": {
                "type": "boolean"
              },
              "callpay": {
                "type": "boolean"
              }
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "path": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "symbols": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "ipx_classes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "note": {
            "type": "string"
          }
        }
      },
      "DataStockPrice": {
        "type": "object",
        "required": [
          "object",
          "symbol",
          "token",
          "price_usd",
          "price_e18",
          "source",
          "multiplier",
          "status",
          "read_at"
        ],
        "properties": {
          "object": {
            "type": "string",
            "const": "data.stock_price"
          },
          "symbol": {
            "type": "string"
          },
          "token": {
            "type": "string"
          },
          "chain_id": {
            "type": "integer"
          },
          "price_usd": {
            "type": "string",
            "description": "USD per whole Stock Token, decimal string."
          },
          "price_e18": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "source": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "const": "chainlink"
              },
              "feed": {
                "type": "string"
              },
              "decimals": {
                "type": "integer"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              },
              "age_seconds": {
                "type": "integer"
              },
              "max_age_seconds": {
                "type": "integer"
              }
            }
          },
          "multiplier": {
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "ui_multiplier": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Decimal, 18 decimals of precision."
                  },
                  "ui_multiplier_raw": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "scheduled": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "ui_multiplier": {
                        "type": "string"
                      },
                      "ui_multiplier_raw": {
                        "type": "string"
                      },
                      "effective_at": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "in_effect": {
                        "type": "boolean"
                      }
                    }
                  },
                  "pending_change": {
                    "type": "boolean"
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "included_in_price": {
                    "type": "boolean",
                    "const": true
                  }
                }
              }
            ]
          },
          "status": {
            "type": "object",
            "properties": {
              "paused": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "oracle_paused": {
                "type": [
                  "boolean",
                  "null"
                ]
              }
            }
          },
          "read_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DataStockActions": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "ui_multiplier": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Decimal, 18 decimals of precision."
              },
              "ui_multiplier_raw": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "scheduled": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "ui_multiplier": {
                    "type": "string"
                  },
                  "ui_multiplier_raw": {
                    "type": "string"
                  },
                  "effective_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "in_effect": {
                    "type": "boolean"
                  }
                }
              },
              "pending_change": {
                "type": "boolean"
              }
            }
          },
          {
            "type": "object",
            "properties": {
              "object": {
                "type": "string",
                "const": "data.stock_actions"
              },
              "symbol": {
                "type": "string"
              },
              "token": {
                "type": "string"
              },
              "chain_id": {
                "type": "integer"
              },
              "price_feed_includes_multiplier": {
                "type": "boolean"
              },
              "status": {
                "type": "object",
                "properties": {
                  "paused": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "oracle_paused": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "price_served": {
                    "type": "boolean"
                  }
                }
              },
              "note": {
                "type": "string"
              },
              "read_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        ]
      },
      "DataIpx": {
        "type": "object",
        "description": "The IPX snapshot of GET /api/v1/ipx/{class} with object data.ipx.",
        "properties": {
          "object": {
            "type": "string",
            "const": "data.ipx"
          },
          "class": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "decimals": {
            "type": "integer"
          },
          "price": {
            "type": "string"
          },
          "price_e8": {
            "type": "string"
          },
          "as_of": {
            "type": "string",
            "format": "date-time"
          },
          "thin": {
            "type": "boolean"
          },
          "volume_usdc_24h": {
            "type": "string"
          },
          "fills_24h": {
            "type": "integer"
          },
          "receipt_root": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      },
      "X402Requirement": {
        "type": "object",
        "properties": {
          "scheme": {
            "type": "string",
            "const": "exact"
          },
          "network": {
            "type": "string",
            "description": "CAIP-2 Solana network; mainnet is solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp.",
            "example": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
          },
          "maxAmountRequired": {
            "type": "string",
            "description": "Price in USDC base units (6 decimals), as a decimal string.",
            "example": "12500"
          },
          "resource": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": "string"
          },
          "mimeType": {
            "type": "string",
            "const": "application/json"
          },
          "payTo": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The router's wallet. The transfer's destination is this wallet's USDC associated token account, not the wallet itself."
          },
          "maxTimeoutSeconds": {
            "type": "integer"
          },
          "asset": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The USDC mint.",
            "example": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
          },
          "extra": {
            "type": "object",
            "properties": {
              "feePayer": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The account that co-signs and pays the transaction fee (the router or facilitator relay key); null when an external facilitator settles and the payer must pay the fee."
              },
              "decimals": {
                "type": "integer",
                "const": 6
              }
            }
          }
        },
        "required": [
          "scheme",
          "network",
          "maxAmountRequired",
          "resource",
          "payTo",
          "maxTimeoutSeconds",
          "asset",
          "extra"
        ],
        "description": "One way to pay a call: the x402 exact scheme on Solana. The payer builds one SPL TransferChecked of maxAmountRequired USDC to payTo's associated token account, sets extra.feePayer as fee payer, signs, and sends the base64 transaction in X-PAYMENT."
      },
      "X402PaymentRequired": {
        "type": "object",
        "properties": {
          "x402Version": {
            "type": "integer",
            "const": 1
          },
          "error": {
            "type": "string"
          },
          "accepts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/X402Requirement"
            }
          },
          "price_usdc": {
            "type": "string",
            "description": "The quoted price in USDC, as a decimal string."
          },
          "model": {
            "type": "string"
          },
          "payment_error": {
            "type": "string",
            "description": "Why a presented payment was rejected (an x402 error reason such as invalid_exact_svm_payload_transaction_fee_payer or payment_already_claimed)."
          }
        },
        "required": [
          "x402Version",
          "error",
          "accepts"
        ],
        "description": "The 402 body when a per-call x402 payment is required: the x402 v1 PaymentRequirementsResponse with the router's price fields beside it."
      },
      "X402PaymentPayload": {
        "type": "object",
        "properties": {
          "x402Version": {
            "type": "integer",
            "enum": [
              1,
              2
            ]
          },
          "scheme": {
            "type": "string",
            "const": "exact",
            "description": "v1: at the top level. v2 carries scheme and network inside accepted."
          },
          "network": {
            "type": "string",
            "example": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
          },
          "accepted": {
            "type": "object",
            "properties": {
              "scheme": {
                "type": "string"
              },
              "network": {
                "type": "string"
              }
            },
            "description": "v2 only: the requirement the payer chose."
          },
          "payload": {
            "type": "object",
            "properties": {
              "transaction": {
                "type": "string",
                "description": "Base64 Solana transaction: fee payer first (extra.feePayer, unsigned) and named by no instruction, the payer as the one other required signer and already signed, no address lookup tables, at most one SetComputeUnitLimit (<= 200,000) and one SetComputeUnitPrice (<= 5,000,000 micro-lamports; priority fee <= 10,000 lamports), at most one idempotent associated-token-account creation for the destination funded by the payer, and exactly one SPL TransferChecked (Token or Token-2022; data [12, amount u64 LE, decimals 6]) of USDC to payTo's associated token account. Nothing else."
              }
            },
            "required": [
              "transaction"
            ]
          }
        },
        "required": [
          "x402Version",
          "payload"
        ],
        "description": "What X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2) carries, base64-encoded."
      },
      "TabVoucher": {
        "type": "object",
        "properties": {
          "tab": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The Tab account."
          },
          "cumulative_used": {
            "type": "string",
            "pattern": "^\\d{1,20}$",
            "description": "USDC base units authorized so far; never decreases."
          },
          "seq": {
            "type": "string",
            "pattern": "^\\d{1,20}$",
            "description": "Strictly increasing per tab."
          },
          "signature": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{64,88}$",
            "description": "Base58 ed25519 signature (64 bytes) by the tab's session key over the 110-byte voucher message: \"trellis:tab:voucher:v1\" (22 ASCII bytes) || the tab program id (32 bytes) || tab (32 bytes) || Tab.created_at i64 little-endian || cumulative_used u64 little-endian || seq u64 little-endian. The facilitator rebuilds the message from its own tab program id and the Tab account it reads; nothing in the request says which program or which opening the voucher is for."
          },
          "session_key": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "Optional: the session key, for the reader's convenience; the Tab account is authoritative."
          }
        },
        "required": [
          "tab",
          "cumulative_used",
          "seq",
          "signature"
        ],
        "description": "A tab voucher as the facilitator takes it (paymentPayload.payload for scheme tab). On a request to the router the same voucher travels as X-Trellis-Tab and X-Trellis-Tab-Voucher."
      },
      "DepositInfo": {
        "type": "object",
        "properties": {
          "key_hash": {
            "type": "string",
            "description": "The key's on-chain hash (32 bytes, hex) the deposit is credited under."
          },
          "network": {
            "type": "string",
            "example": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
          },
          "usdc_mint": {
            "type": "string",
            "example": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
          },
          "program": {
            "type": "string",
            "description": "The trellis_credits program id."
          },
          "vault": {
            "type": "string",
            "description": "The program's USDC vault token account."
          },
          "vault_authority": {
            "type": "string",
            "description": "Owner of the vault token account (for a Solana Pay code)."
          },
          "how": {
            "type": "string",
            "description": "Plain-language instructions."
          },
          "cap_usdc": {
            "type": "string",
            "description": "Per-key balance cap while the programs are pre-audit."
          },
          "spend_only": {
            "type": "boolean",
            "const": true
          }
        },
        "description": "How to fund this key. Credits are spend-only; the only customer-initiated outflow is an account closure refund."
      },
      "DepositTransaction": {
        "type": "object",
        "properties": {
          "transaction": {
            "type": "string",
            "description": "Base64 unsigned legacy transaction (Solana Pay transaction-request shape) with the payer as fee payer: trellis_credits::deposit(key_hash, amount), moving USDC from the payer's token account into the program vault. The wallet signs and sends it."
          },
          "message": {
            "type": "string",
            "description": "Human-readable label for the wallet prompt."
          },
          "network": {
            "type": "string",
            "example": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
          },
          "amount_usdc": {
            "type": "string",
            "example": "12.50"
          },
          "amount_units": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "The same amount in base units."
          },
          "accounts": {
            "type": "object",
            "description": "The accounts the instruction names: credit (the key's credit account), vault, depositorToken (the payer's USDC token account) and share (the on-chain record of what this wallet has put into this key, which is what a closure refund is measured against)."
          },
          "refund_to": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The token account a closure refund of this deposit returns to: the one it is paid from (accounts.depositorToken). Only the paying wallet can change it, with POST /api/v1/credits/refund-destination-tx; the API key cannot.",
            "example": "2ynX92NNnMitvdyFgkE1PW4Wa7nTirUHuMEapMS82ZWJ"
          },
          "expires_at_block_height": {
            "type": "integer",
            "description": "The last block height at which the transaction's blockhash is valid; ask again after it."
          },
          "key_hash": {
            "type": "string"
          },
          "note": {
            "type": "string",
            "description": "The same statement in words."
          }
        },
        "required": [
          "transaction",
          "network",
          "amount_usdc",
          "amount_units",
          "expires_at_block_height",
          "key_hash"
        ]
      },
      "CreditClosure": {
        "type": "object",
        "description": "One closure of the key's credits, as listed.",
        "properties": {
          "id": {
            "type": "string",
            "example": "close_..."
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "registered",
              "paid",
              "refused",
              "failed",
              "cancelled"
            ],
            "description": "queued: closure requested, the transaction (signed by the key) has not landed yet and the key keeps working; registered: the on-chain refund request exists and the key is frozen; paid: every planned payment was sent; cancelled: the closure was taken back before anything was paid and the key is open again."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "A fixed code. On an open closure it says what it is waiting for: key_disabled (the key was disabled, so the closure is held until an owner or admin releases it), refund_rate_limited (paid in parts under the hourly limit), refund_destination_unavailable (a depositor's token account cannot receive right now), depositors_unknown, refund_work_capped (one run pays at most 16 depositors of a closure; the rest follow on the next), request_gone_refund_debited (the on-chain request is gone and the reversal is waiting on a chain read), submission_failed (retried). cancelled_on_chain and sanctioned_address are final.",
            "examples": [
              "key_disabled",
              "refund_rate_limited",
              "refund_destination_unavailable",
              "depositors_unknown",
              "cancelled_on_chain"
            ]
          },
          "refund_to": {
            "type": [
              "string",
              "null"
            ],
            "description": "The wallets paid so far, comma-separated (the owners of the token accounts paid); null until something is paid. Never an address the key chose."
          },
          "refunds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ClosureRefundPayment"
            },
            "description": "The payment plan once it exists: one row per wallet that deposited. Empty before the delay has passed."
          },
          "amount_units": {
            "type": [
              "string",
              "null"
            ],
            "description": "The unspent balance being refunded, in USDC base units; null until it is fixed at payment time."
          },
          "requested_at": {
            "type": "string",
            "format": "date-time"
          },
          "payable_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the refund may be paid: the on-chain request time plus the program's closure delay (72 hours at launch)."
          },
          "paid_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "register_tx": {
            "type": [
              "string",
              "null"
            ],
            "description": "The close_account transaction signature."
          },
          "pay_tx": {
            "type": [
              "string",
              "null"
            ],
            "description": "The latest pay_refund transaction signature."
          },
          "cancel_tx": {
            "type": [
              "string",
              "null"
            ],
            "description": "The cancel_close transaction signature, when the closure was taken back."
          },
          "released_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When an owner or admin released a closure that was held because its key was disabled."
          }
        },
        "required": [
          "id",
          "status",
          "reason",
          "refund_to",
          "refunds",
          "amount_units",
          "requested_at",
          "payable_at",
          "paid_at",
          "register_tx",
          "pay_tx",
          "cancel_tx",
          "released_at"
        ]
      },
      "HvxPoint": {
        "type": "object",
        "properties": {
          "grade": {
            "type": "string",
            "enum": [
              "G-S",
              "G-M",
              "G-L"
            ]
          },
          "hour": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the hour, UTC."
          },
          "usd_per_mtoken": {
            "type": [
              "number",
              "null"
            ],
            "description": "Volume-weighted USD per million output-equivalent tokens; null when the hour had no kept receipts."
          },
          "thin": {
            "type": "boolean",
            "description": "True when the trailing daily volume is below thin_below_daily_usd: a thin index is published but should not be relied on."
          },
          "sample_count": {
            "type": "integer"
          },
          "excluded_count": {
            "type": "integer",
            "description": "Receipts dropped as self-dealing, circular, below the minimum or without a grade."
          },
          "tokens": {
            "type": "string",
            "description": "Output-equivalent tokens in the hour, as a decimal string."
          },
          "volume_usd": {
            "type": "string"
          },
          "daily_volume_usd": {
            "type": "string"
          },
          "published_tx": {
            "type": [
              "string",
              "null"
            ],
            "description": "The base58 signature of the on-chain publication, when posted."
          }
        },
        "required": [
          "grade",
          "hour",
          "usd_per_mtoken",
          "thin",
          "sample_count",
          "excluded_count",
          "tokens",
          "volume_usd",
          "daily_volume_usd"
        ]
      },
      "HvxView": {
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "description": "The index format version."
          },
          "unit": {
            "type": "string",
            "const": "usd_per_mtoken"
          },
          "grades": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "thin_below_daily_usd": {
            "type": "number"
          },
          "latest": {
            "type": "object",
            "properties": {
              "G-S": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/HvxPoint"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "G-M": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/HvxPoint"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "G-L": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/HvxPoint"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "description": "The latest completed hour per grade; the current hour is still filling and only appears in series."
          },
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HvxPoint"
            },
            "description": "The last 24 hours of points, oldest first."
          }
        },
        "required": [
          "format",
          "unit",
          "grades",
          "thin_below_daily_usd",
          "latest",
          "series"
        ]
      },
      "HolderTiers": {
        "type": "object",
        "required": [
          "enabled",
          "token",
          "tiers",
          "cache_s"
        ],
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "Whether holder tiers run on this router. When false, show \"Holder tiers are not switched on yet\"."
          },
          "token": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "address",
              "symbol",
              "program"
            ],
            "properties": {
              "address": {
                "type": "string",
                "description": "The token mint (base58)."
              },
              "symbol": {
                "type": "string"
              },
              "program": {
                "type": "string",
                "description": "The token program of the mint, for example token-2022."
              }
            }
          },
          "tiers": {
            "type": "array",
            "description": "Lowest threshold first. Empty when no thresholds are set.",
            "items": {
              "$ref": "#/components/schemas/HolderTier"
            }
          },
          "cache_s": {
            "type": "integer",
            "description": "Seconds a wallet's balance read is cached; a change in balance can take this long to show."
          }
        }
      },
      "HolderPoll": {
        "type": "object",
        "description": "An advisory poll and its public tally. Results inform a decision and never carry it out. Who voted is not shown.",
        "required": [
          "id",
          "kind",
          "title",
          "options",
          "status",
          "created_at",
          "closes_at",
          "closed_at",
          "advisory",
          "results"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^poll_[A-Za-z0-9_-]{1,64}$"
          },
          "kind": {
            "type": "string",
            "enum": [
              "model_listing",
              "slash_schedule"
            ],
            "description": "model_listing: the options are candidate model ids. slash_schedule: the options are the slashing rules on offer."
          },
          "title": {
            "type": "string",
            "maxLength": 200
          },
          "options": {
            "type": "array",
            "minItems": 2,
            "maxItems": 20,
            "items": {
              "type": "string",
              "maxLength": 200
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "closed"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "closes_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Votes are refused from this time on."
          },
          "closed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "advisory": {
            "const": true
          },
          "results": {
            "type": "object",
            "required": [
              "options",
              "total_votes",
              "total_weight",
              "final"
            ],
            "properties": {
              "options": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "option",
                    "votes",
                    "weight"
                  ],
                  "properties": {
                    "option": {
                      "type": "string"
                    },
                    "votes": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "weight": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                }
              },
              "total_votes": {
                "type": "integer",
                "minimum": 0
              },
              "total_weight": {
                "type": "integer",
                "minimum": 0
              },
              "final": {
                "type": "boolean",
                "description": "True once the poll is closed. At close every voter's balance is read again, and a wallet that dropped below the tier it voted with counts with the weight of the tier it holds then."
              }
            }
          }
        }
      },
      "HolderVoteRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "poll_id",
          "option"
        ],
        "properties": {
          "poll_id": {
            "type": "string",
            "maxLength": 80,
            "description": "The poll in the path. It is in the signed body so a signature cannot be used on another poll."
          },
          "option": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "One of the poll's options, exactly as listed."
          }
        }
      },
      "HolderVote": {
        "type": "object",
        "required": [
          "poll_id",
          "option",
          "tier",
          "weight",
          "voted_at"
        ],
        "properties": {
          "poll_id": {
            "type": "string"
          },
          "option": {
            "type": "string"
          },
          "tier": {
            "type": "string",
            "description": "The tier the wallet voted with."
          },
          "weight": {
            "type": "integer",
            "minimum": 1,
            "description": "That tier's fixed vote weight."
          },
          "voted_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EarlyAccess": {
        "type": [
          "object",
          "null"
        ],
        "description": "Set while the model's early-access window runs; null otherwise. Early access decides when a model may be used, never what it costs.",
        "required": [
          "until",
          "your_access_at"
        ],
        "properties": {
          "until": {
            "type": "string",
            "format": "date-time",
            "description": "When the model opens to everyone."
          },
          "your_access_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it opens to the caller: earlier than `until` for a key whose wallet holds a tier with early_access_hours, the same as `until` otherwise."
          }
        }
      },
      "WalletSignInChallenge": {
        "type": "object",
        "description": "A wallet sign-in challenge (trellis:wallet:v2). The wallet signs the UTF-8 bytes of message exactly as returned.",
        "properties": {
          "nonce": {
            "type": "string",
            "pattern": "^[0-9a-f]{48}$"
          },
          "message": {
            "type": "string",
            "description": "The exact text to sign, ready to pass to the wallet (solana:signMessage). Lines: \"<domain> wants you to sign in with your Solana account:\", the address, an empty line, the statement, an empty line, then \"URI: …\", \"Version: 1\", \"Chain ID: …\", \"Nonce: …\", \"Issued At: …\", \"Expiration Time: …\". No trailing newline.",
            "example": "trellis.example wants you to sign in with your Solana account:\nCZ8YUVdk7znjrUmnb5n7kgySk9yRAsQDYmyCxzfSky9t\n\nSign in to Trellis with this wallet. Signing proves you hold the address: it sends no transaction and costs nothing.\n\nURI: https://trellis.example\nVersion: 1\nChain ID: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp\nNonce: 5f1c0d9a7b3e42618c0a9d4e7f2b6a1c3d5e8f0a1b2c3d4e\nIssued At: 2026-10-12T12:00:00.000Z\nExpiration Time: 2026-10-12T12:05:00.000Z"
          },
          "domain": {
            "type": "string",
            "description": "The host (and port) of the router being signed in to: the first thing the wallet shows.",
            "example": "trellis.example"
          },
          "uri": {
            "type": "string",
            "format": "uri",
            "description": "The router's origin.",
            "example": "https://trellis.example"
          },
          "chain_id": {
            "type": "string",
            "description": "The network (CAIP-2).",
            "example": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
          },
          "issued_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": "string",
            "const": "trellis:wallet:v2"
          }
        },
        "required": [
          "nonce",
          "message",
          "domain",
          "uri",
          "chain_id",
          "issued_at",
          "expires_at",
          "version"
        ]
      },
      "ClosureRefund": {
        "type": "object",
        "description": "One wallet that deposited to the key, and where its share of a closure refund goes. The list is read from the chain; nobody holding the API key can add a row or change one.",
        "properties": {
          "depositor": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "A wallet that deposited to the key."
          },
          "refund_to": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The USDC token account that wallet's share is paid to: by default the one it paid from, or the one it named itself with set_refund_destination."
          },
          "deposited_units": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "What that wallet has put into the key, in USDC base units. It is refunded at most this much."
          },
          "refunded_units": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "What it has already been refunded from this key."
          }
        },
        "required": [
          "depositor",
          "refund_to",
          "deposited_units",
          "refunded_units"
        ]
      },
      "ClosureRefundPayment": {
        "type": "object",
        "description": "One planned or sent payment of a closure refund: back to one wallet that deposited to the key.",
        "properties": {
          "depositor": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The wallet that deposited."
          },
          "refund_to": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The USDC token account paid."
          },
          "owner": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The wallet that owns refund_to. It differs from depositor only when the depositor moved its own destination."
          },
          "amount_units": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "This depositor's share of the refund, in USDC base units."
          },
          "status": {
            "type": "string",
            "enum": [
              "planned",
              "paid",
              "refused",
              "reversed"
            ],
            "description": "planned, paid, refused (sanctions), or reversed: the closure was cancelled on chain after this payment had been planned and debited, and the debit was put back."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why a payment is waiting or was refused, for example refund_rate_limited, refund_destination_unavailable or sanctioned_address."
          },
          "tx": {
            "type": [
              "string",
              "null"
            ],
            "description": "The pay_refund transaction signature, once sent."
          }
        },
        "required": [
          "depositor",
          "refund_to",
          "owner",
          "amount_units",
          "status",
          "reason",
          "tx"
        ]
      },
      "CreditClosureRequest": {
        "type": "object",
        "description": "The answer to a closure request. There is no destination in it to choose: refunds says where the money goes.",
        "properties": {
          "id": {
            "type": "string",
            "example": "close_..."
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "registered"
            ]
          },
          "payer": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The fee payer of transaction: the wallet that still has to sign. It is not the destination of the refund."
          },
          "authority": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "deprecated": true,
            "description": "Same value as payer (the field's earlier name)."
          },
          "payable_at": {
            "type": "string",
            "format": "date-time"
          },
          "transaction": {
            "type": [
              "string",
              "null"
            ],
            "description": "Base64 legacy transaction holding one close_account instruction, already signed by the key. The payer adds its signature (slot 0, the fee payer) and sends it; every other byte stays as issued. null when the closure is already registered on chain."
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "description": "A line a wallet can show for the transaction (Solana Pay transaction-request message)."
          },
          "accounts": {
            "type": [
              "object",
              "null"
            ],
            "description": "refundRequest: the on-chain refund request.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "expires_at_block_height": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The transaction's blockhash is valid up to this block height (about a minute)."
          },
          "signed_by_key": {
            "type": "boolean",
            "description": "true when transaction carries the key's signature."
          },
          "refunds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ClosureRefund"
            },
            "description": "Who is paid back: the wallets that deposited to this key, each to the token account it named. Empty when the router could not read them just now; nothing is paid to anyone else."
          },
          "note": {
            "type": "string"
          },
          "requested_by": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "key",
              "owner",
              null
            ],
            "description": "Who the returned transaction asks as: the key (signed here as the key) or the key's registered owner wallet (as_owner; unsigned). null when no transaction is returned. A closure asked for by the owner cannot be cancelled with the API key."
          },
          "owner": {
            "type": [
              "string",
              "null"
            ],
            "description": "The key's registered owner wallet (POST /api/v1/credits/owner-tx), or null when none is registered."
          }
        },
        "required": [
          "id",
          "status",
          "payer",
          "payable_at",
          "transaction",
          "refunds"
        ]
      },
      "CreditClosureCancel": {
        "type": "object",
        "properties": {
          "transaction": {
            "type": "string",
            "description": "Base64 legacy transaction holding one cancel_close instruction, already signed by the key. The payer adds its signature (slot 0, the fee payer) and sends it; every other byte stays as issued."
          },
          "message": {
            "type": "string"
          },
          "accounts": {
            "type": "object",
            "description": "refundRequest: the on-chain refund request being closed.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "payer": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The fee payer of transaction."
          },
          "expires_at_block_height": {
            "type": "integer"
          },
          "signed_by_key": {
            "type": "boolean"
          },
          "note": {
            "type": "string"
          }
        },
        "required": [
          "transaction",
          "payer",
          "expires_at_block_height",
          "signed_by_key"
        ]
      },
      "CreditClosureRelease": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "close_..."
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "registered"
            ]
          },
          "released": {
            "type": "boolean"
          },
          "payable_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "status",
          "released",
          "payable_at"
        ]
      },
      "RefundDestinationTransaction": {
        "type": "object",
        "properties": {
          "transaction": {
            "type": "string",
            "description": "Base64 UNSIGNED legacy transaction with the depositor as fee payer and only signer: it creates refund_to's USDC token account if needed (paid by the depositor) and calls set_refund_destination. The API key is not in it."
          },
          "message": {
            "type": "string"
          },
          "accounts": {
            "type": "object",
            "description": "share: the depositor's record for this key; refundToToken: the USDC token account its refunds go to from now on.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "depositor": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The wallet that deposited and must sign."
          },
          "refund_to": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The wallet whose USDC token account receives this depositor's refunds from now on."
          },
          "current_refund_to": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The token account they go to today."
          },
          "expires_at_block_height": {
            "type": "integer"
          },
          "note": {
            "type": "string"
          }
        },
        "required": [
          "transaction",
          "depositor",
          "refund_to",
          "current_refund_to",
          "expires_at_block_height"
        ]
      },
      "ClosureHeld": {
        "type": "object",
        "description": "A closure the disabled key had started. It is not paid while the key is disabled.",
        "properties": {
          "id": {
            "type": "string",
            "example": "close_..."
          },
          "reason": {
            "type": "string",
            "const": "key_disabled"
          },
          "release": {
            "type": "string",
            "description": "The route an owner or admin calls to let it go ahead.",
            "example": "POST /api/v1/credits/close/release"
          }
        },
        "required": [
          "id",
          "reason",
          "release"
        ]
      }
    }
  },
  "x-launch-surface": {
    "default": "core",
    "values": {
      "core": "Only the operations marked `x-launch-surface: core` exist. Request fields, headers and key settings that select another feature (`guardrails`, `transforms`, `cache`, `verify`, `@route/`, `@preset/`, `@character/` models, `X-Pay-With`, tab headers, `Authorization: PrivateToken`) are answered 404 `not_enabled` on the core operations too.",
      "all": "Every operation of this document whose feature is switched on. In production it needs LAUNCH_SURFACE_ACK."
    },
    "status_field": "data.launch_surface",
    "not_enabled_response": "#/components/responses/NotEnabled"
  }
}
