{
  "openapi": "3.1.0",
  "info": {
    "title": "Anyray Gateway API",
    "version": "1.10.353",
    "summary": "OpenAI-compatible inference gateway that cuts the AI-inference spend your employees generate.",
    "description": "OpenAI-compatible inference API plus the coding-tool `/connect/*` API and the admin-gated console API (`/admin/*`) served by the Anyray gateway. Content-free by invariant: spend and request logs carry metadata only (user, team, model, provider, tokens, cost, latency, decision) — never prompt/response bodies. Opaque passthrough routes (the `/v1/*` proxy catch-alls, `/v1/copilot/*`, `/v1/proxy/*`) and the `/v1/realtime` WebSocket upgrade are intentionally omitted — a fixed schema would misrepresent them. Because of those catch-alls, an unrecognized `/v1/<anything>` is not a 404: it is proxied upstream as an inference request and typically fails `500`. Two surfaces sit OUTSIDE the three prefixes and are documented here: `POST /mcp` (the gateway as a remote MCP server) and the device page. Every `/admin/*` operation carries `x-required-capability`: the single capability its caller must hold, generated from the gateway's route table (`null` = authenticated but ungated). Roles grant capabilities cumulatively (viewer, auditor, operator, security_admin), and `owner` — the break-glass admin token — holds all of them.",
    "contact": {
      "name": "Anyray",
      "url": "https://docs.anyray.ai"
    },
    "license": {
      "name": "Documentation",
      "url": "https://docs.anyray.ai"
    }
  },
  "externalDocs": {
    "description": "Anyray documentation",
    "url": "https://docs.anyray.ai/developers/api-reference"
  },
  "servers": [
    {
      "url": "https://{gatewayHost}",
      "description": "Your self-hosted Anyray gateway",
      "variables": {
        "gatewayHost": {
          "default": "localhost:8787",
          "description": "Host:port where your Anyray gateway is reachable. Defaults to :8787; put it behind TLS for any networked deployment."
        }
      }
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "AnyrayApiKey": []
    }
  ],
  "tags": [
    {
      "name": "Chat",
      "description": "OpenAI-compatible chat and text completions."
    },
    {
      "name": "Embeddings",
      "description": "OpenAI-compatible embeddings."
    },
    {
      "name": "Messages",
      "description": "Anthropic-native Messages API."
    },
    {
      "name": "Models",
      "description": "List the models the gateway can route to."
    },
    {
      "name": "Me",
      "description": "Self-service identity, usage, and limits for the verified `ark_` / `ark_svc_` key holder. No admin credential involved."
    },
    {
      "name": "Audio",
      "description": "OpenAI-compatible speech, transcription, and translation."
    },
    {
      "name": "Images",
      "description": "OpenAI-compatible image generation and edits."
    },
    {
      "name": "Files",
      "description": "OpenAI-compatible file upload/retrieval for batch/fine-tune jobs."
    },
    {
      "name": "Batches",
      "description": "OpenAI-compatible batch job lifecycle."
    },
    {
      "name": "Responses",
      "description": "OpenAI-compatible Responses API."
    },
    {
      "name": "Admin · Spend & governance",
      "description": "Content-free spend visibility and per-user token caps. Metadata only — never prompt/response content."
    },
    {
      "name": "Admin · Health & settings",
      "description": "Liveness, runtime settings, self-updater, and the console auth handshake."
    },
    {
      "name": "Admin · Optimizer, pricing & routing",
      "description": "Optimizer pipeline, price table, model aliases, routing, and the playground."
    },
    {
      "name": "Admin · Providers",
      "description": "Server-held provider API keys (values never returned)."
    },
    {
      "name": "Admin · Access, SSO & enrollment",
      "description": "SSO/IdP config, console login, client keys, enrollment links, provisioning tokens."
    },
    {
      "name": "Admin · Privacy, support & observability",
      "description": "GDPR export/erase, support bundles, trace reads, onboarding."
    },
    {
      "name": "Connect · Coding-tool integration",
      "description": "Endpoints the `anyray-connect` CLI and its PostToolUse hook call: team policy, per-developer savings, source-side output optimization, CCR retrieval, semantic recall, and dev-cert verification. Content-free — metadata and content-free handles only."
    },
    {
      "name": "Connect · SSO enrollment",
      "description": "Pre-key browser SSO handshake used by `anyray-connect login`. Start is IP rate-limited; poll is authorized by a separate high-entropy secret stored only as a salted hash."
    },
    {
      "name": "Management API v1 · Me",
      "description": "`/admin/v1/me` — scopes `me:read` / `me:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Keys",
      "description": "`/admin/v1/keys` — scopes `keys:read` / `keys:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Admin keys",
      "description": "`/admin/v1/admin-keys` — scopes `admin-keys:read` / `admin-keys:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Users",
      "description": "`/admin/v1/users` — scopes `users:read` / `users:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Spend",
      "description": "`/admin/v1/spend` — scopes `spend:read` / `spend:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Providers",
      "description": "`/admin/v1/providers` — scopes `providers:read` / `providers:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Routing",
      "description": "`/admin/v1/routing` — scopes `routing:read` / `routing:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Optimizer",
      "description": "`/admin/v1/optimizer` — scopes `optimizer:read` / `optimizer:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Policies",
      "description": "`/admin/v1/policies` — scopes `policies:read` / `policies:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Desktop plugins",
      "description": "`/admin/v1/desktop-plugins` — scopes `desktop-plugins:read` / `desktop-plugins:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Settings",
      "description": "`/admin/v1/settings` — scopes `settings:read` / `settings:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Sso",
      "description": "`/admin/v1/sso` — scopes `sso:read` / `sso:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Enrollment",
      "description": "`/admin/v1/enrollment` — scopes `enrollment:read` / `enrollment:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Provisioning",
      "description": "`/admin/v1/provisioning` — scopes `provisioning:read` / `provisioning:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Fleet",
      "description": "`/admin/v1/fleet` — scopes `fleet:read` / `fleet:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Traces",
      "description": "`/admin/v1/traces` — scopes `traces:read` / `traces:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Audit",
      "description": "`/admin/v1/audit` — scopes `audit:read` / `audit:write` plus the named exceptions declared per operation."
    },
    {
      "name": "Management API v1 · Playground",
      "description": "`/admin/v1/playground` — scopes `playground:read` / `playground:write` plus the named exceptions declared per operation."
    }
  ],
  "paths": {
    "/admin/endpoint-fleet/status": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "End-point fleet status summary",
        "description": "Read-only, content-free summary of the org's end-point fleet, cached in-process for 15s. A stored Fleet config takes precedence; otherwise a portal-connected gateway relays through Billing to its tenant-paired endpoint-control org. Never returns credentials, policy queries, or resolutions. An unreachable upstream answers `{configured: true, reachable: false}` rather than an error. Requires the `observability:read` capability.",
        "operationId": "adminGetEndpointFleetStatus",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "observability:read"
      }
    },
    "/admin/endpoint-fleet/mdm-servers": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Read registered MDM server URLs",
        "description": "Returns the normalized MDM server URLs used to verify managed devices. Requires the `config:read` capability and deployment-owner access.",
        "operationId": "adminGetEndpointFleetMdmServers",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "serverUrls",
                    "updatedAt"
                  ],
                  "properties": {
                    "serverUrls": {
                      "type": "array",
                      "maxItems": 20,
                      "items": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 512
                      }
                    },
                    "updatedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Replace registered MDM server URLs",
        "description": "Validates and stores up to 20 HTTPS MDM server URLs, then best-effort converges the local endpoint-control policy and legacy Fleet pack. The audit entry records only the URL count. Requires the `provisioning:manage` capability and deployment-owner access.",
        "operationId": "adminPutEndpointFleetMdmServers",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "serverUrls"
                ],
                "properties": {
                  "serverUrls": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "type": "string",
                      "format": "uri",
                      "maxLength": 512
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored and convergence attempted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "serverUrls"
                  ],
                  "properties": {
                    "serverUrls": {
                      "type": "array",
                      "maxItems": 20,
                      "items": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 512
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid list; an invalid entry is identified by index without echoing its value"
          },
          "403": {
            "description": "Missing capability or deployment-owner access"
          },
          "503": {
            "description": "The durable MDM server config store is unavailable"
          }
        },
        "x-required-capability": "provisioning:manage"
      }
    },
    "/admin/endpoint-fleet": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Read endpoint-fleet config",
        "description": "The org's Fleet server connection driving the end-point self-healing loop: server URL, the policy → remediation-script map, and cooldown. Credentials are never returned — presence booleans only. Requires the `config:read` capability.",
        "operationId": "adminGetEndpointFleet",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Update endpoint-fleet config",
        "description": "Replace the endpoint-fleet config. Validates everything before applying anything — a 400 means nothing changed. When no `webhookSecret` is provided one is generated server-side and returned exactly once in this response. Requires the `provisioning:manage` capability.",
        "operationId": "adminPutEndpointFleet",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "provisioning:manage"
      },
      "delete": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Retire endpoint-fleet config",
        "description": "Delete the stored self-hosted Fleet connection (the 0054 row). The stored config has unconditional lane precedence, so retiring it is how a deployment cuts over to the in-deployment endpoint-control service or the Portal relay: the next status read follows the normal lane precedence. Idempotent — deleting when nothing is configured answers 200 with `deleted:false`. Audited; enrolled hosts are not touched. Requires the `provisioning:manage` capability.",
        "operationId": "adminDeleteEndpointFleet",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "provisioning:manage"
      }
    },
    "/connect/fleet-policy-webhook": {
      "post": {
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Fleet failed-policy webhook",
        "description": "Receiver for the org's Anyray-hosted Fleet server's failing-policies webhook (the end-point self-healing loop). Verified timing-safe against the stored webhook secret (bearer header or `?token=`); a mapped policy triggers the remediation script per failing host via the Fleet server's run-script API, with a per-host cooldown. Fails closed: an absent or unreadable config rejects with 503 and never remediates. Response is content-free counts.",
        "operationId": "connectFleetPolicyWebhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "tags": [
          "Chat"
        ],
        "summary": "Create a chat completion",
        "description": "OpenAI-compatible chat completion. The gateway selects the upstream provider (from the `x-anyray-provider` header, the request's routing config, or the configured default), injects the server-held provider key, runs the optimizer as a fail-open before-request hook, calls the provider, and meters the result content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          },
          {
            "$ref": "#/components/parameters/ConfigHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A chat completion. When `stream` is `true`, the body is a `text/event-stream` of `chat.completion.chunk` events terminated by `data: [DONE]`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/ServiceKeyBudgetExceeded"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/extensions/vscode/optimize": {
      "post": {
        "operationId": "optimizeVscodeLanguageModelRequest",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Optimize a VS Code language-model request",
        "description": "Authenticated pre-call hook for the official Anyray VS Code language-model provider. It applies the fail-open optimizer to the request and returns the resulting request to the extension, which then invokes the developer's selected VS Code/Copilot subscription model locally. The gateway does not choose or call an upstream provider, cannot short-circuit the request, and does not accept client-authored usage or cost. Prompt content is handled under the deployment's `ANYRAY_CONTENT_MODE`; spend and request logs remain metadata-only.",
        "parameters": [
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "request": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The VS Code language-model request to optimize."
                  }
                },
                "required": [
                  "request"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The request to pass to the selected VS Code model plus a bounded, content-free optimization summary.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "request": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "optimization": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "optimizationId": {
                          "type": "string",
                          "pattern": "^[A-Za-z0-9_-]{1,128}$"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "applied",
                            "skipped",
                            "disabled",
                            "timeout",
                            "error"
                          ]
                        },
                        "latencyMs": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 2000000000
                        },
                        "decisions": {
                          "type": "array",
                          "maxItems": 64,
                          "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "kind": {
                                "type": "string",
                                "pattern": "^[a-z0-9_-]{1,64}$"
                              },
                              "estimatedTokensSaved": {
                                "type": "integer",
                                "minimum": 0,
                                "maximum": 2000000000
                              }
                            },
                            "required": [
                              "kind"
                            ]
                          }
                        },
                        "estimatedTokensSaved": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 2000000000
                        }
                      }
                    }
                  },
                  "required": [
                    "request",
                    "optimization"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/v1/completions": {
      "post": {
        "operationId": "createCompletion",
        "tags": [
          "Chat"
        ],
        "summary": "Create a (legacy) text completion",
        "description": "OpenAI-compatible legacy text completion. Prefer `/v1/chat/completions` for new work.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "prompt"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Model id or alias."
                  },
                  "prompt": {
                    "description": "The prompt(s) to complete.",
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    ]
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "temperature": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 2
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A text completion.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/ServiceKeyBudgetExceeded"
          }
        }
      }
    },
    "/v1/embeddings": {
      "post": {
        "operationId": "createEmbedding",
        "tags": [
          "Embeddings"
        ],
        "summary": "Create embeddings",
        "description": "OpenAI-compatible embeddings. Returns a vector per input.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The embedding vectors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmbeddingResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/ServiceKeyBudgetExceeded"
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "operationId": "createMessage",
        "tags": [
          "Messages"
        ],
        "summary": "Create a message (Anthropic-native)",
        "description": "Anthropic-native Messages API. Point the Anthropic SDK's base URL at the gateway and it routes Claude requests through the same governance and optimization pipeline as the OpenAI-compatible endpoints.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessagesRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A message. When `stream` is `true`, the body is a `text/event-stream` of Anthropic message events.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessagesResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/ServiceKeyBudgetExceeded"
          }
        }
      }
    },
    "/v1/messages/count_tokens": {
      "post": {
        "operationId": "countMessageTokens",
        "tags": [
          "Messages"
        ],
        "summary": "Count tokens for a Messages request",
        "description": "Returns the input token count for an Anthropic-native Messages request without running inference.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessagesRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The input token count.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "input_tokens": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "tags": [
          "Models"
        ],
        "summary": "List models",
        "description": "Lists the models the gateway can route to, in the OpenAI `list` envelope.",
        "responses": {
          "200": {
            "description": "The available models.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Model"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/admin/spend/usage": {
      "get": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Per-user usage detail",
        "description": "Per-user usage over a window with per-model and per-UTC-day breakdowns, each capped user's gauge, and an org-wide per-model rollup. Content-free.",
        "operationId": "adminSpendUsage",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "mtd",
                "prev-month",
                "24h",
                "7d",
                "30d",
                "90d"
              ],
              "default": "mtd"
            },
            "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2000,
              "default": 200
            },
            "description": "Max users returned, heaviest first. `truncated` in the response flags when users were dropped."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendUsage"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/spend/usage/properties": {
      "get": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Spend grouped by a custom attribution dimension",
        "description": "Groups content-free spend over a window by one caller-supplied custom attribution dimension (sent as an `x-anyray-property-<name>` request header, stored under `attribution.properties`). Returns per-value request, token, and cost totals. Content-free: attribution ids, counts, and USD only.",
        "operationId": "adminSpendUsageProperties",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$"
            },
            "description": "The custom dimension name to group by (e.g. `feature`). Must match the bounded attribution-property charset."
          },
          {
            "name": "window",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "mtd",
                "prev-month",
                "24h",
                "7d",
                "30d",
                "90d"
              ],
              "default": "mtd"
            },
            "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "property": {
                      "type": "string"
                    },
                    "window": {
                      "type": "string"
                    },
                    "from": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "to": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "values": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string"
                          },
                          "requests": {
                            "type": "number"
                          },
                          "totalTokens": {
                            "type": "number"
                          },
                          "costUsd": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/spend-connectors": {
      "get": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Read external spend connectors",
        "description": "Returns redacted configuration and optional poll status for the official Cursor, Devin, and GitHub Copilot usage connectors. Credentials are write-only and never appear in this response. Requires the `config:read` capability and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.",
        "operationId": "adminGetSpendConnectors",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Redacted connector configuration. An unconfigured deployment returns an empty object.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendConnectorsRead"
                }
              }
            }
          },
          "401": {
            "description": "Admin authentication is required."
          },
          "403": {
            "description": "The principal lacks `config:read` or is not the deployment owner."
          },
          "500": {
            "description": "Connector state could not be read. The response does not expose credentials, ciphertext, or database details."
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Set external spend connectors",
        "description": "Partially configure, rotate, or remove official vendor usage connectors. Omitted connectors stay unchanged; a connector object replaces that connector; `null` or `{}` removes it. Credential fields are write-only, encrypted at rest, never returned, and never audit-logged. Requires `providerkeys:manage` and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.",
        "operationId": "adminPutSpendConnectors",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpendConnectorsPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The resulting redacted connector configuration. Credential values are never echoed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendConnectorsRead"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON or connector configuration."
          },
          "401": {
            "description": "Admin authentication is required."
          },
          "403": {
            "description": "The principal lacks `providerkeys:manage` or is not the deployment owner."
          },
          "500": {
            "description": "The encrypted configuration could not be persisted. The response does not expose credential or storage details."
          }
        },
        "x-required-capability": "providerkeys:manage"
      }
    },
    "/admin/spend-connectors/sync": {
      "post": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Synchronize external spend connectors",
        "description": "Requests a fleet-safe sync of every configured vendor connector. A durable lease prevents duplicate polling across replicas. Per-connector failures are isolated and represented only as `failed: true`; vendor bodies, signed report URLs, and credential-bearing errors are never returned. Requires `providerkeys:manage` and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.",
        "operationId": "adminSyncSpendConnectors",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Safe, content-free result for each configured connector.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendConnectorSyncResponse"
                }
              }
            }
          },
          "401": {
            "description": "Admin authentication is required."
          },
          "403": {
            "description": "The principal lacks `providerkeys:manage` or is not the deployment owner."
          },
          "502": {
            "description": "The sync could not be started. The response contains only the fixed safe error message."
          }
        },
        "x-required-capability": "providerkeys:manage"
      }
    },
    "/admin/spend-connectors/usage": {
      "get": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Read external subscription usage",
        "description": "Aggregates imported, content-free usage while preserving vendor-native units: Cursor token/cost events, Devin ACUs, and GitHub Copilot credits/activity plus real CLI tokens. Copilot's published $0.01-per-credit list value is reported separately and is not an invoice total; ACUs and credits are never fabricated as tokens. Requires `config:read` and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.",
        "operationId": "adminGetSpendConnectorUsage",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90,
              "default": 30
            },
            "description": "Rolling lookback in days. Missing, non-integer, or out-of-range values use 30 days."
          }
        ],
        "responses": {
          "200": {
            "description": "Vendor-native usage totals over the requested window.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendConnectorUsage"
                }
              }
            }
          },
          "401": {
            "description": "Admin authentication is required."
          },
          "403": {
            "description": "The principal lacks `config:read` or is not the deployment owner."
          },
          "500": {
            "description": "Usage could not be read. The response does not expose database details."
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/auth-events": {
      "get": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Auth rejection diagnostics",
        "description": "Customer-local, content-free auth rejection events with machine-readable reason codes and remediation hints.",
        "operationId": "adminAuthEvents",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "user",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "description": "Optional customer-local user id filter."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            },
            "description": "Max events returned, newest first. Values above 200 are clamped."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthEvents"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/metering/last-report": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Read the last metering report",
        "description": "Returns the exact final payload from this process's last successful, verified metering round, plus the active diagnostics tier and metering state. Requires the `config:read` capability.",
        "operationId": "adminLastMeterReport",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/user-caps": {
      "get": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Get per-user caps + monthly usage",
        "description": "Caps, the org-wide cap-alert posture (webhook URL never returned — only whether configured), and current-month tokens per user.",
        "operationId": "adminGetUserCaps",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserCapsGet"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Set per-user caps + alert settings",
        "description": "Replace the caps map and (optionally) the cap-alert settings. Requires the `usercaps:write` capability. Webhook URL merge: absent=keep, null=clear, string=set.",
        "operationId": "adminSetUserCaps",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserCapsPut"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserCapsGet"
                }
              }
            }
          },
          "400": {
            "description": "Invalid body (Zod validation)."
          }
        },
        "x-required-capability": "usercaps:write"
      }
    },
    "/admin/spend": {
      "get": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Spend summary (byUser)",
        "description": "In-memory content-free summary: requests + tokens per attributed user.",
        "operationId": "adminSpendSummary",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/spend/dashboard": {
      "get": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Windowed spend dashboard",
        "description": "Money/usage split by billing class, per-day trend, top token-saving strategies, latency, and prompt-cache economics. Content-free.",
        "operationId": "adminSpendDashboard",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "mtd",
                "prev-month",
                "24h",
                "7d",
                "30d",
                "90d"
              ],
              "default": "mtd"
            },
            "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/spend/quality-parity": {
      "get": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Holdout quality and gross-cost objective",
        "description": "Quality proxies and measured list-price provider cost per observed session in the selected window compared holdout vs treated, with 95% CIs and proof status for the quality-gated 30% gross-cost reduction objective.",
        "operationId": "adminQualityParity",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "mtd",
                "prev-month",
                "24h",
                "7d",
                "30d",
                "90d"
              ],
              "default": "mtd"
            },
            "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/health": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Health & schema version",
        "description": "Liveness, spend-store ping, and the applied vs expected DB schema version. Requires the `config:read` capability.",
        "operationId": "adminHealth",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/me": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Caller identity",
        "description": "The authenticated caller's identity and whether it may access deployment-global configuration. No capability required (any valid admin session). In fleet mode, `deploymentOwner` is false for every tenant-bound SSO principal regardless of tenant role.",
        "operationId": "adminMe",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "role": {
                      "type": "string",
                      "enum": [
                        "viewer",
                        "auditor",
                        "operator",
                        "security_admin",
                        "owner"
                      ]
                    },
                    "sub": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "token",
                        "local",
                        "sso"
                      ]
                    },
                    "tenantId": {
                      "type": "string"
                    },
                    "deploymentOwner": {
                      "type": "boolean",
                      "description": "Whether this principal may access deployment-global connector configuration."
                    }
                  },
                  "required": [
                    "role",
                    "sub",
                    "kind",
                    "deploymentOwner"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Admin authentication is required."
          }
        },
        "x-required-capability": null
      }
    },
    "/admin/settings": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Read runtime settings",
        "description": "Content mode, feature flags, and other runtime-mutable settings. Requires the `config:read` capability.",
        "operationId": "adminGetSettings",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Update runtime settings",
        "description": "Update runtime-mutable settings. Requires the `content:manage` capability.",
        "operationId": "adminPutSettings",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "content:manage"
      }
    },
    "/admin/settings/identity": {
      "put": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Set the identity mode",
        "description": "Switch how `/v1/*` establishes who is calling (RFC 0019). `enrolled` (the default) requires every request to present a minted client key. `network-trusted` lifts that requirement for a network-isolated deployment, taking the developer's identity from the request instead — which turns off SCIM offboarding enforcement and leaves the server-held provider keys reachable by anything on that network. A presented key is still verified and still binds an authoritative identity in both modes, and only the ABSENCE of a key is forgiven — an expired, revoked, or deactivated key still returns 401. The relaxation covers INFERENCE paths only, never content retrieval (`/v1/files/{id}/content`, `/v1/batches/*/output`, `/v1/responses/{id}/input_items` stay key-gated in every mode). **Single-tenant self-hosted only:** a fleet deployment (`ANYRAY_MULTI_TENANT=true`) resolves identity through the control plane, which never consults this setting — a key-less `/v1/*` request there still returns `401 missing_key` whatever the mode says. Separate from `PUT /admin/settings` because it requires the distinct `identity:manage` capability.",
        "operationId": "adminPutIdentitySettings",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "identityMode"
                ],
                "properties": {
                  "identityMode": {
                    "type": "string",
                    "enum": [
                      "enrolled",
                      "network-trusted"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid identityMode"
          }
        },
        "x-required-capability": "identity:manage"
      }
    },
    "/admin/update-status": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Self-updater status",
        "description": "Available image tag vs the running version, the locally evaluated release preflight, the computed update class (`soft` = image-only, self-applies on Compose installs when the policy is on; `hard` = operator infra action required, never applied unattended), the `autoSoftUpdates` policy, and the last unattended apply attempt. Requires the `config:read` capability.",
        "operationId": "adminUpdateStatus",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "preflight": {
                      "type": "object",
                      "required": [
                        "target",
                        "status",
                        "missingEnv",
                        "removedEnvSet",
                        "breaking"
                      ],
                      "properties": {
                        "target": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "pattern": "^v?\\d+\\.\\d+\\.\\d+$"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "blocked",
                            "unknown"
                          ]
                        },
                        "missingEnv": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "name"
                            ],
                            "properties": {
                              "name": {
                                "type": "string",
                                "pattern": "^ANYRAY_[A-Z0-9_]{1,60}$"
                              },
                              "summary": {
                                "type": "string",
                                "maxLength": 200
                              },
                              "composeDefault": {
                                "type": "boolean"
                              }
                            }
                          }
                        },
                        "removedEnvSet": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "pattern": "^ANYRAY_[A-Z0-9_]{1,60}$"
                          }
                        },
                        "breaking": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "maxLength": 300
                          }
                        }
                      }
                    },
                    "updateClass": {
                      "type": "string",
                      "enum": [
                        "soft",
                        "hard",
                        "unknown"
                      ]
                    },
                    "autoSoftUpdates": {
                      "type": "boolean",
                      "description": "Whether soft (image-only) updates apply unattended. Default true."
                    },
                    "autoUpdate": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Last unattended apply attempt (in-memory; resets on gateway restart).",
                      "properties": {
                        "target": {
                          "type": "string"
                        },
                        "at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "result": {
                          "type": "string",
                          "enum": [
                            "triggered",
                            "unreachable",
                            "rejected"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/auth": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Auth-mode probe",
        "description": "Pre-session probe: reports whether console SSO is required. Unauthenticated.",
        "operationId": "adminAuthProbe",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": null
      }
    },
    "/admin/auth/update": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Trigger self-update",
        "description": "Run a self-update check/apply. Requires the `update:run` capability.",
        "operationId": "adminAuthUpdate",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "update:run"
      }
    },
    "/admin/optimizer/settings": {
      "get": {
        "tags": [
          "Admin · Optimizer, pricing & routing"
        ],
        "summary": "Read optimizer config",
        "description": "The optimizer pipeline configuration (strategies + params). Requires the `config:read` capability.",
        "operationId": "adminGetOptimizer",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Optimizer, pricing & routing"
        ],
        "summary": "Update optimizer config",
        "description": "Update the optimizer pipeline configuration. Requires the `optimizer:write` capability.",
        "operationId": "adminPutOptimizer",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "optimizer:write"
      }
    },
    "/admin/optimizer/purge": {
      "post": {
        "tags": [
          "Admin · Optimizer, pricing & routing"
        ],
        "summary": "Purge optimizer state",
        "description": "Purge optimizer caches / session state. Requires the `optimizer:purge` capability.",
        "operationId": "adminOptimizerPurge",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "optimizer:purge"
      }
    },
    "/admin/pricing": {
      "get": {
        "tags": [
          "Admin · Optimizer, pricing & routing"
        ],
        "summary": "Official price table",
        "description": "The read-only official model price table. Requires the `config:read` capability.",
        "operationId": "adminPricing",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/model-aliases": {
      "get": {
        "tags": [
          "Admin · Optimizer, pricing & routing"
        ],
        "summary": "Read model aliases",
        "description": "Model-alias → target mappings. Requires the `config:read` capability.",
        "operationId": "adminGetAliases",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Optimizer, pricing & routing"
        ],
        "summary": "Update model aliases",
        "description": "Replace model-alias mappings. Requires the `modelaliases:write` capability.",
        "operationId": "adminPutAliases",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "modelaliases:write"
      }
    },
    "/admin/routing-config": {
      "get": {
        "tags": [
          "Admin · Optimizer, pricing & routing"
        ],
        "summary": "Read routing config",
        "description": "Routing strategy (single / loadbalance / fallback / conditional) and targets. Requires the `config:read` capability.",
        "operationId": "adminGetRouting",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Optimizer, pricing & routing"
        ],
        "summary": "Update routing config",
        "description": "Update routing strategy and targets. See the Configure docs for the body shape. Requires the `routing:write` capability.",
        "operationId": "adminPutRouting",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "routing:write"
      }
    },
    "/admin/test-request": {
      "post": {
        "tags": [
          "Admin · Optimizer, pricing & routing"
        ],
        "summary": "Playground test request",
        "description": "Send a test request through the gateway (console playground). Requires the `playground:run` capability.",
        "operationId": "adminTestRequest",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "playground:run"
      }
    },
    "/admin/claude-desktop-policy": {
      "get": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Read Claude Desktop organization policy",
        "description": "Read the secret-free managed policy and resolved deployment fields. Requires `config:read` and the deployment owner.",
        "operationId": "adminGetClaudeDesktopPolicy",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current policy and deployment metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaudeDesktopPolicyResponse"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Replace Claude Desktop organization policy",
        "description": "Replace the secret-free managed policy. Rejects credential-shaped string values at every depth, server-owned inference/bootstrap fields, unknown keys, and documents over 128 KiB. Available in headless deployments; requires `desktopconfig:write` and the deployment owner.",
        "operationId": "adminPutClaudeDesktopPolicy",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClaudeDesktopPolicyInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved policy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaudeDesktopPolicyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or credential-bearing policy"
          }
        },
        "x-required-capability": "desktopconfig:write"
      }
    },
    "/admin/claude-desktop-plugins": {
      "get": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "List organization Skills and Guidance",
        "description": "List the Skills and Guidance distributed to managed Claude Desktop clients. Requires `config:read` and the deployment owner.",
        "operationId": "adminListClaudeDesktopSkills",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current Skills and Guidance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "items"
                  ],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ClaudeDesktopOrgSkill"
                      }
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "Skills and Guidance store unavailable"
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Create or update an organization Skill or Guidance item",
        "description": "Save one credential-free Skill or Guidance item. Each item is limited to 256 KiB of file content and the organization total is limited to 2 MiB. Requires `desktopconfig:write` and the deployment owner.",
        "operationId": "adminPutClaudeDesktopSkill",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClaudeDesktopOrgSkillInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved Skill or Guidance item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "item"
                  ],
                  "properties": {
                    "item": {
                      "$ref": "#/components/schemas/ClaudeDesktopOrgSkill"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid or credential-bearing Skill or Guidance item"
          },
          "413": {
            "description": "Per-item or organization size limit exceeded"
          },
          "503": {
            "description": "Skills and Guidance store unavailable"
          }
        },
        "x-required-capability": "desktopconfig:write"
      }
    },
    "/admin/claude-desktop-plugins/{id}": {
      "delete": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Remove an organization Skill or Guidance item",
        "description": "Remove one Skill or Guidance item by id. Requires `desktopconfig:write` and the deployment owner.",
        "operationId": "adminDeleteClaudeDesktopSkill",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removal result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "deleted"
                  ],
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid item id"
          },
          "503": {
            "description": "Skills and Guidance store unavailable"
          }
        },
        "x-required-capability": "desktopconfig:write"
      }
    },
    "/admin/claude-desktop-policy/mobileconfig": {
      "get": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Download Claude Desktop MDM trust profile",
        "description": "Download a stable, credential-free macOS profile carrying the bootstrap URL and MDM-only helper path. Requires `config:read` and the deployment owner.",
        "operationId": "adminGetClaudeDesktopMobileconfig",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Apple configuration profile",
            "content": {
              "application/x-apple-aspen-config": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "409": {
            "description": "Policy is disabled"
          },
          "503": {
            "description": "Public HTTPS gateway URL or durable store unavailable"
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/provider-keys": {
      "get": {
        "tags": [
          "Admin · Providers"
        ],
        "summary": "List provider slugs",
        "description": "Configured providers, including per-provider named-key metadata (`capabilities.keyIds`: id/label/isDefault — key values are returned only in `config`; the metadata itself is content-free). A provider entry is a bare credential or a multi-key set `{ keys: [{id, label?, credential}], defaultKeyId }`. Requires the `providerkeys:manage` capability.",
        "operationId": "adminGetProviderKeys",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "providerkeys:manage"
      },
      "put": {
        "tags": [
          "Admin · Providers"
        ],
        "summary": "Set provider keys",
        "description": "Set server-held provider API keys. Accepts a partial patch per slug: a credential (string or field bag) replaces the provider's DEFAULT key; '' clears the whole provider; the per-key form `{ keys: { [id]: credential | {label?, credential} | '' | null }, defaultKeyId? }` adds/replaces/removes named keys and reassigns the default. Named keys are pinned from routing configs via `provider_key_id`. Callers authenticate with a separate, minted Anyray client key and never receive the stored provider secret. Requires the `providerkeys:manage` capability.",
        "operationId": "adminPutProviderKeys",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "providerkeys:manage"
      }
    },
    "/admin/spend/connectors": {
      "get": {
        "tags": [
          "Admin · Providers"
        ],
        "summary": "List seat-spend connectors (legacy path)",
        "description": "Compatibility facade for the previously released slash-separated connector path. It reads the same canonical encrypted connector store and returns a redacted legacy view for Cursor, Devin, and GitHub Copilot. Prefer `/admin/spend-connectors`. Preserves the released `providerkeys:manage` capability requirement and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.",
        "operationId": "adminGetLegacySpendConnectors",
        "deprecated": true,
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Redacted legacy connector configuration. Credential values never appear.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacySpendConnectorsRead"
                }
              }
            }
          },
          "401": {
            "description": "Admin authentication is required."
          },
          "403": {
            "description": "The principal lacks `providerkeys:manage` or is not the deployment owner."
          },
          "500": {
            "description": "Connector state could not be read. The response does not expose credentials or storage details."
          }
        },
        "x-required-capability": "providerkeys:manage"
      },
      "put": {
        "tags": [
          "Admin · Providers"
        ],
        "summary": "Set seat-spend connectors (legacy path)",
        "description": "Compatibility facade for legacy token-shaped Cursor, Devin, and GitHub Copilot writes. It transforms the old request shape and updates the same canonical encrypted connector store. Omitted sources stay unchanged; an empty string, empty or tokenless object, or `null` removes that source. An unscoped Copilot token is retained disabled. Prefer `/admin/spend-connectors`. Requires `providerkeys:manage` and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.",
        "operationId": "adminPutLegacySpendConnectors",
        "deprecated": true,
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LegacySpendConnectorsPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The resulting redacted legacy connector configuration. Credential values are never echoed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacySpendConnectorsRead"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, unsupported connector name, or invalid connector configuration."
          },
          "401": {
            "description": "Admin authentication is required."
          },
          "403": {
            "description": "The principal lacks `providerkeys:manage` or is not the deployment owner."
          },
          "500": {
            "description": "The encrypted configuration could not be persisted. The response does not expose credentials or storage details."
          }
        },
        "x-required-capability": "providerkeys:manage"
      }
    },
    "/admin/scim/settings": {
      "get": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Read inbound SCIM settings",
        "description": "Return whether inbound SCIM is configured plus the admin group and group-to-team map. The bearer and its hash are never returned. Requires `config:read` and deployment-owner access.",
        "operationId": "adminGetScimSettings",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Redacted inbound SCIM settings.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "configured",
                    "adminGroup",
                    "groupTeamMap",
                    "updatedAt"
                  ],
                  "properties": {
                    "configured": {
                      "type": "boolean"
                    },
                    "adminGroup": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "groupTeamMap": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "updatedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Admin authentication is required."
          },
          "403": {
            "description": "The principal lacks `config:read` or is not the deployment owner."
          },
          "503": {
            "description": "The shared SCIM settings store is unavailable."
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Configure inbound SCIM",
        "description": "Set or rotate the static SCIM bearer and update the admin group or group-to-team map. Omit `bearerToken` to preserve an existing credential. Requires `idp:manage` and deployment-owner access.",
        "operationId": "adminPutScimSettings",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bearerToken": {
                    "type": "string",
                    "minLength": 32,
                    "maxLength": 1024,
                    "writeOnly": true
                  },
                  "adminGroup": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 256
                  },
                  "groupTeamMap": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 256
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The resulting redacted inbound SCIM settings."
          },
          "400": {
            "description": "Invalid settings, or the first configuration omitted `bearerToken`."
          },
          "401": {
            "description": "Admin authentication is required."
          },
          "403": {
            "description": "The principal lacks `idp:manage` or is not the deployment owner."
          },
          "503": {
            "description": "The shared SCIM settings store is unavailable."
          }
        },
        "x-required-capability": "idp:manage"
      }
    },
    "/admin/idp-config": {
      "get": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Read SSO/IdP config",
        "description": "The SSO / IdP configuration. Requires the `config:read` capability.",
        "operationId": "adminGetIdp",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Configure SSO/IdP",
        "description": "Set the SSO / IdP configuration. Requires the `idp:manage` capability.",
        "operationId": "adminPutIdp",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "idp:manage"
      },
      "delete": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Remove SSO/IdP config",
        "description": "Remove the SSO / IdP configuration. Requires the `idp:manage` capability.",
        "operationId": "adminDeleteIdp",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "x-required-capability": "idp:manage"
      }
    },
    "/admin/connect-health": {
      "get": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Per-seat connect-health rollup",
        "description": "Per-seat connect-health over the gateway's rolling 24h window (RFC 0010 P3): each seat's pseudonymous `userHash`, last-seen instant, connect version (when reported), per-check statuses (`gateway_reachable`, `enrollment_cert`, per-tool `routing`, …), and a 0–100 `complianceScore` weighted against the fleet tool policy's `tools.enabled`. Content-free — opaque hashes, enum tokens, counts, and timestamps only; never a name or email. Requires the `observability:read` capability plus deployment owner.",
        "operationId": "adminGetConnectHealth",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 200
            },
            "description": "Maximum seats returned (worst compliance first)."
          },
          {
            "name": "user",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{20,64}$"
            },
            "description": "Narrow to one seat by its pseudonymous `userHash`."
          }
        ],
        "responses": {
          "200": {
            "description": "The per-seat rollup: `windowHours`, `generatedAt`, `policyEnabledTools`, `userCount`, `users[]` (each with `userHash`, `lastSeen`, `connectVersion`, `complianceScore`, `failingChecks`, `checks[]`), and the deployment-wide `versions` mix.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "observability:read"
      }
    },
    "/admin/connect/directives": {
      "get": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "List connect remediation directives",
        "description": "Directive history (every status, acked included), newest first — the console coverage page's read counterpart of the queue POST. Optional `user` filters to one pseudonymous `userHash`; `limit` (default 200, max 1000) bounds the page. Requires the `observability:read` capability plus the deployment owner. Content-free: userHash, enums, and timestamps only.",
        "operationId": "adminListConnectDirectives",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "user",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{20,64}$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "directives"
                  ],
                  "properties": {
                    "directives": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "userHash",
                          "kind",
                          "status",
                          "queuedBy",
                          "createdAt"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "userHash": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "reapply_config",
                              "remint",
                              "revert"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "delivered",
                              "acked"
                            ]
                          },
                          "queuedBy": {
                            "type": "string"
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "deliveredAt": {
                            "type": "string"
                          },
                          "ackedAt": {
                            "type": "string"
                          },
                          "ackResult": {
                            "type": "string",
                            "enum": [
                              "ok",
                              "failed"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-required-capability": "observability:read"
      },
      "post": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Queue a connect remediation directive",
        "description": "Queue a per-user remediation directive (RFC 0009 §4.3) for a developer identified by their pseudonymous `userHash` (from the per-user connect-health view). The developer's machine picks it up on its next `/connect/verify` and applies it — pull-only, never pushed. `kind` is one of `reapply_config` (re-apply the tool config), `remint`, or `revert`. Requires the `idp:manage` capability. `kind` is `reapply_config`, `remint`, `revert`, or `revert_tool`; `revert_tool` additionally requires `tool` (a lowercase adapter slug) and un-routes only that tool, leaving the seat enrolled for the rest.",
        "operationId": "adminQueueConnectDirective",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userHash",
                  "kind"
                ],
                "properties": {
                  "userHash": {
                    "type": "string",
                    "description": "Pseudonymous developer id (HMAC-SHA256, base64url) from the per-user connect-health view."
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "reapply_config",
                      "remint",
                      "revert"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The queued directive.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "idp:manage"
      }
    },
    "/admin/revoked-users": {
      "get": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "List revoked developers",
        "description": "The tenant's SSO developer-revocation set (offboarded emails and when each was revoked). Requires the `config:read` capability.",
        "operationId": "adminListRevokedUsers",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "post": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Revoke a developer",
        "description": "Offboard an SSO developer by email so the gateway refuses to re-mint their key (within one lease heartbeat). This is the offboarding path for orgs without WorkOS Directory Sync. Requires the `idp:manage` capability.",
        "operationId": "adminRevokeUser",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "x-required-capability": "idp:manage"
      }
    },
    "/admin/revoked-users/{email}": {
      "delete": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Reinstate a developer",
        "description": "Undo a revocation (IdP re-activation) for the given developer email. Requires the `idp:manage` capability.",
        "operationId": "adminReinstateUser",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "parameters": [
          {
            "name": "email",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "x-required-capability": "idp:manage"
      }
    },
    "/admin/workos-portal-link": {
      "post": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "WorkOS admin-portal link",
        "description": "Mint a WorkOS admin-portal link. Requires the `idp:manage` capability.",
        "operationId": "adminWorkosPortal",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "idp:manage"
      }
    },
    "/admin/sso/start": {
      "get": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Begin SSO login",
        "description": "Start the console SSO login handshake. Pre-session (redirects).",
        "operationId": "adminSsoStart",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "302": {
            "description": "Redirect to the IdP."
          }
        },
        "x-required-capability": null
      }
    },
    "/admin/sso/callback": {
      "get": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "SSO callback",
        "description": "SSO redirect callback. Pre-session.",
        "operationId": "adminSsoCallback",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "302": {
            "description": "Redirect back to the console."
          }
        },
        "x-required-capability": null
      }
    },
    "/admin/sso/logout": {
      "post": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "End SSO session",
        "description": "End the console SSO session.",
        "operationId": "adminSsoLogout",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "x-required-capability": null
      }
    },
    "/admin/client-keys": {
      "get": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "List client keys",
        "description": "Minted client keys (enrolled users). Requires the `config:read` capability.",
        "operationId": "adminGetClientKeys",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "post": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Mint a client key",
        "description": "Mint a client key for an enrolled user. Requires the `clientkeys:manage` capability.",
        "operationId": "adminMintClientKey",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "clientkeys:manage"
      }
    },
    "/admin/client-keys/{id}": {
      "delete": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Revoke a client key",
        "description": "Revoke a minted client key. Requires the `clientkeys:manage` capability.",
        "operationId": "adminRevokeClientKey",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "x-required-capability": "clientkeys:manage"
      }
    },
    "/admin/service-keys": {
      "get": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "List service keys",
        "description": "List non-human service keys as metadata only. Raw tokens and hashes are never returned. Requires the `config:read` capability.",
        "operationId": "adminGetServiceKeys",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Service-key roster",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceKeyListResponse"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "post": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Mint a service key",
        "description": "Mint a revocable `ark_svc_` key for an AI agent, CI job, or SDK script, optionally capped by successful request cost per UTC calendar month. The raw token is returned exactly once. Requires the `clientkeys:manage` capability.",
        "operationId": "adminMintServiceKey",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ServiceKeyCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Service key minted; save the raw key now because it cannot be recovered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceKeyMintResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "x-required-capability": "clientkeys:manage"
      }
    },
    "/admin/service-keys/{id}": {
      "delete": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Revoke a service key",
        "description": "Revoke a service key by its opaque record id. Requires the `clientkeys:manage` capability.",
        "operationId": "adminRevokeServiceKey",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Service key revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown service-key id"
          }
        },
        "x-required-capability": "clientkeys:manage"
      }
    },
    "/admin/enrollment-links": {
      "get": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "List enrollment links",
        "description": "Enrollment / setup links. Requires the `config:read` capability.",
        "operationId": "adminGetEnrollLinks",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "post": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Create enrollment link",
        "description": "Create an enrollment / setup link. Requires the `enrollment:manage` capability.",
        "operationId": "adminCreateEnrollLink",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "enrollment:manage"
      }
    },
    "/admin/enrollment-links/{id}": {
      "delete": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Disable enrollment link",
        "description": "Disable an enrollment link. Requires the `enrollment:manage` capability.",
        "operationId": "adminDisableEnrollLink",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "x-required-capability": "enrollment:manage"
      }
    },
    "/admin/enrollment-links/{id}/hard": {
      "delete": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Hard-delete enrollment link",
        "description": "Permanently delete an enrollment link. Requires the `enrollment:manage` capability.",
        "operationId": "adminHardDeleteEnrollLink",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "x-required-capability": "enrollment:manage"
      }
    },
    "/admin/provisioning-tokens": {
      "get": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "List provisioning tokens",
        "description": "Deployment provisioning tokens. Requires the `config:read` capability.",
        "operationId": "adminGetProvTokens",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "post": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Mint provisioning token",
        "description": "Mint a deployment provisioning token. Requires the `provisioning:manage` capability.",
        "operationId": "adminMintProvToken",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "provisioning:manage"
      }
    },
    "/admin/provisioning-tokens/{id}": {
      "delete": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Revoke provisioning token",
        "description": "Revoke a provisioning token. Requires the `provisioning:manage` capability.",
        "operationId": "adminRevokeProvToken",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "x-required-capability": "provisioning:manage"
      }
    },
    "/admin/provisioning-tokens/{id}/rotate": {
      "post": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Rotate provisioning token",
        "description": "Rotate a provisioning token. Requires the `provisioning:manage` capability.",
        "operationId": "adminRotateProvToken",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "provisioning:manage"
      }
    },
    "/admin/gdpr/users/{user}/export": {
      "get": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Export a user's records",
        "description": "Export a user's content-free spend, connector-observation, and client-key records (GDPR). Deployment-owner requests include deployment-global connector observations; tenant-scoped SSO requests return an empty `connectorRecords` array. Requires the `gdpr:manage` capability.",
        "operationId": "adminGdprExport",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "description": "Attributed user id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "user",
                    "generatedAt",
                    "spendRecords",
                    "connectorRecords",
                    "clientKeys"
                  ],
                  "properties": {
                    "user": {
                      "type": "string"
                    },
                    "generatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "spendRecords": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "connectorRecords": {
                      "type": "array",
                      "description": "Content-free vendor connector observations. Empty for tenant-scoped SSO requests.",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "clientKeys": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-required-capability": "gdpr:manage"
      }
    },
    "/admin/gdpr/users/{user}": {
      "delete": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Erase a user's records",
        "description": "Erase a user's spend, client-key, trace, and eligible connector-observation records (GDPR). Only deployment-owner requests erase deployment-global connector observations; tenant-scoped SSO requests report `erasedConnectorRecords: 0`. Requires the `gdpr:manage` capability.",
        "operationId": "adminGdprErase",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "description": "Attributed user id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "user",
                    "erasedSpendRecords",
                    "erasedConnectorRecords",
                    "erasedClientKeys",
                    "erasedTraces"
                  ],
                  "properties": {
                    "user": {
                      "type": "string"
                    },
                    "erasedSpendRecords": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "erasedConnectorRecords": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Always 0 for tenant-scoped SSO requests."
                    },
                    "erasedClientKeys": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "erasedTraces": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                }
              }
            }
          }
        },
        "x-required-capability": "gdpr:manage"
      }
    },
    "/admin/support/bundle": {
      "get": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Support bundle",
        "description": "Generate a content-free support bundle for remote debugging. Requires the `config:read` capability.",
        "operationId": "adminSupportBundle",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/support/bundle/share": {
      "post": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Share a support bundle",
        "description": "Generate, redact, and explicitly send a content-free support bundle to the Anyray Billing app. Requires the `content:manage` capability; the send is recorded in the deployment audit log.",
        "operationId": "adminShareSupportBundle",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Bundle accepted; returns the support receipt id and metadata-only manifest summary.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated role lacks the `content:manage` capability."
          },
          "409": {
            "description": "Deployment is not connected to the Anyray Billing app."
          },
          "502": {
            "description": "The Billing app did not accept the bundle."
          }
        },
        "x-required-capability": "content:manage"
      }
    },
    "/admin/observability/traces/{id}": {
      "get": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Read a trace",
        "description": "Fetch one trace. Content is redacted unless the caller has `observability:read-content`. Other `/admin/observability/*` read paths proxy to the observability API. Requires the `observability:read` capability.",
        "operationId": "adminGetTrace",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "observability:read"
      }
    },
    "/admin/team-skills": {
      "get": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Read team skills",
        "description": "The stored team policy: shared skills, the fleet tool set (`tools.enabled` + per-tool `tools.tiers`), and the Connect update posture (`updates.mode`: `auto` | `directed` | `off`; `auto` is stored as absent). When no tool policy has ever been saved, `tools` is absent and a read-only `toolsDefault` lists what the deployment enrols instead; neither is returned when the policy store could not be read. Requires the `config:read` capability.",
        "operationId": "adminGetTeamSkills",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      },
      "put": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Update team skills",
        "description": "Replace the team policy (skills use replace semantics; a legacy skills-only write preserves the stored `tools`, `lanes` and `updates` fields, including per-tool tiers). `updates.mode` sets the fleet Connect update posture: `auto` (machines self-update), `directed` (nothing downloads unattended; an admin queues each update), `off` (no binary is fetched at all). Requires the `teamskills:write` capability.",
        "operationId": "adminPutTeamSkills",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "teamskills:write"
      }
    },
    "/admin/wizard-status": {
      "get": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Onboarding wizard status",
        "description": "Onboarding wizard progress. Requires the `config:read` capability.",
        "operationId": "adminWizardStatus",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/wizard-confirm": {
      "put": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Confirm wizard step",
        "description": "Confirm an onboarding wizard step. Requires the `wizard:write` capability.",
        "operationId": "adminWizardConfirm",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "wizard:write"
      }
    },
    "/connect/claude-desktop/bootstrap": {
      "get": {
        "operationId": "getClaudeDesktopBootstrapPolicy",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Get the effective Claude Desktop managed policy",
        "description": "Secret-free effective policy for managed Claude Desktop clients. Injects the Anyray gateway route, the helper credential mode, and the per-OS `inferenceCredentialHelper` path; never returns a key or the MDM-only `bootstrapHeadersHelper` path. Current Claude Desktop sends the enrolled user's client key as a bearer through the MDM-pinned bootstrap-headers helper: a presented bearer is verified, an absent one is still served.",
        "security": [],
        "parameters": [
          {
            "name": "os",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "macos",
                "windows",
                "linux"
              ],
              "default": "macos"
            },
            "description": "Selects the `inferenceCredentialHelper` path for the client OS; the MDM artifact pins it."
          }
        ],
        "responses": {
          "200": {
            "description": "Effective Claude Desktop policy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Unsupported `os` value"
          },
          "401": {
            "description": "A bearer was presented and is not a valid Anyray client key"
          },
          "404": {
            "description": "Organization policy is disabled"
          },
          "503": {
            "description": "Policy store or public gateway URL unavailable"
          }
        }
      }
    },
    "/connect/policy": {
      "get": {
        "operationId": "getConnectPolicy",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Get the team optimization policy",
        "description": "Returns the org-wide optimization policy the connect hook applies locally (which strategies are enabled and their surface). Resolved from the team-skills config; content-free.",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Versioned, content-free fleet policy document. Absent optional fields are treated as unset by older/newer clients alike (backward-compatible).",
                  "properties": {
                    "version": {
                      "type": "integer",
                      "description": "Policy document schema version (1). A document with no version is treated as a legacy skills-only document."
                    },
                    "skills": {
                      "type": "array",
                      "description": "Enabled team skills (content-free descriptors).",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "updatedAt": {
                      "type": "string",
                      "description": "ISO-8601 timestamp of the last policy change."
                    },
                    "routing": {
                      "type": "object",
                      "description": "Gateway routing origin the client reconciles toward. Omitted when unset.",
                      "properties": {
                        "origin": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "origin"
                      ]
                    },
                    "team": {
                      "type": "string",
                      "description": "Team attribution bound to the caller's key. Omitted when the key carries no team."
                    },
                    "tools": {
                      "type": "object",
                      "description": "Server-owned fleet tool set. Reconcile drift-corrects already-managed tools and freshly enrolls a never-enrolled enabled id per its tier; an intentional local revert is tombstoned and only the `locked` tier overrides it. An id with no `tiers` entry is `required`.",
                      "properties": {
                        "enabled": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "tiers": {
                          "type": "object",
                          "description": "Per-tool policy tier (RFC 0010): how strongly the fleet holds an enabled tool.",
                          "additionalProperties": {
                            "type": "string",
                            "enum": [
                              "locked",
                              "required",
                              "recommended",
                              "optional"
                            ]
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "skills",
                    "updatedAt"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/connect/endpoint-enrollment": {
      "post": {
        "operationId": "getConnectEndpointEnrollment",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Get the organization's end-point enrollment configuration",
        "description": "Returns the organization's fleet URL and enroll secret so an authenticated seat can configure the shared, credential-free end-point agent. The response contains a live credential and must not be logged or rendered.",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The organization's current end-point enrollment configuration",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "fleetUrl",
                    "enrollSecret"
                  ],
                  "properties": {
                    "fleetUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "The organization's end-point fleet server URL."
                    },
                    "enrollSecret": {
                      "type": "string",
                      "minLength": 1,
                      "description": "The organization's live Fleet enroll secret."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/connect/savings": {
      "get": {
        "operationId": "getConnectSavings",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Get this developer's savings summary",
        "description": "Content-free savings rollup for the key's attributed user over the current billing period — token counts and USD savings only, no prompt/response content.",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "type": "string",
                      "description": "Attributed user id."
                    },
                    "team": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Attributed team id, if any."
                    },
                    "grossSavingsUsd": {
                      "type": "number",
                      "description": "Pre-scaling savings (value delivered)."
                    },
                    "savingsUsd": {
                      "type": "number",
                      "description": "Billed savings for the period."
                    },
                    "totalTokens": {
                      "type": "integer",
                      "description": "Total attributed tokens."
                    },
                    "savedTokens": {
                      "type": "integer",
                      "description": "Tokens saved by the optimizer."
                    }
                  },
                  "required": [
                    "user"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/connect/device-token": {
      "delete": {
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Revoke the seat's device token",
        "description": "Revoke the calling seat's device token — the disconnect counterpart of the register POST, called by a full `anyray-connect --revert` before the enrollment is cleared. Idempotent: 200 whether or not a live token existed. Requires the same minted client key as the POST; 503 when the shared token or pseudonym-secret store is unavailable.",
        "operationId": "revokeConnectDeviceToken",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid client key"
          },
          "503": {
            "description": "Device-token or pseudonym-secret store unavailable"
          }
        }
      },
      "post": {
        "operationId": "registerConnectDeviceToken",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Register a short-lived device-page token",
        "description": "Connect mints a random 256-bit token and registers it here. The device-url command creates a replacement on demand, and scheduled renewal also replaces it. The gateway stores only the token's sha256, keyed to the caller's pseudonymous seat hash, and a new registration revokes the seat's previous token. The raw token is never stored or logged. Requires a minted client key; 503 with a static message on a deployment without the shared Postgres store (device tokens are access state and never fall back to a per-pod store).",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{43}$",
                    "description": "The raw device token: 32 random bytes, base64url (43 chars)."
                  },
                  "ttlSeconds": {
                    "type": "number",
                    "description": "Requested lifetime; clamped server-side to 300–3900 seconds."
                  }
                },
                "required": [
                  "token",
                  "ttlSeconds"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "expiresAt": {
                      "type": "string",
                      "description": "ISO-8601 instant the token stops verifying."
                    }
                  },
                  "required": [
                    "status",
                    "expiresAt"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "description": "No shared Postgres store on this deployment — the device page is unavailable."
          }
        }
      }
    },
    "/device": {
      "get": {
        "operationId": "getDevicePage",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "The developer's device page (HTML shell)",
        "description": "The static, self-contained device-page shell (RFC 0010) that the tray's \"Open my device page\" and `anyray-connect device-url` open. Reads `dt` from the query string in the browser and fetches /device/health with it; the page itself is served unauthenticated because it contains no data — all data rides the token-gated fetch.",
        "parameters": [
          {
            "name": "dt",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{43}$"
            },
            "description": "The rotating device token; consumed client-side by the page's fetch."
          }
        ],
        "responses": {
          "200": {
            "description": "The device-page shell.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/device/health": {
      "get": {
        "operationId": "getDeviceHealth",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "One seat's connect-health rollup (device-token gated)",
        "description": "Backs the device page. Gated by the rotating device token alone — no admin capability, no client key: the token is verified by hash against the shared store and fails closed (unknown, expired, malformed, or off-Postgres all return the same static 401). Returns exactly the verified seat's content-free rollup — opaque userHash, per-check statuses, window counts, and the compliance score — the same fields as one /admin/connect-health row.",
        "parameters": [
          {
            "name": "dt",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{43}$"
            },
            "description": "The live short-lived device token minted by Connect."
          }
        ],
        "responses": {
          "200": {
            "description": "The seat's rollup.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "userHash": {
                      "type": "string",
                      "description": "Opaque pseudonymous seat hash (HMAC — never a name or email)."
                    },
                    "generatedAt": {
                      "type": "string"
                    },
                    "windowHours": {
                      "type": "integer",
                      "enum": [
                        24
                      ]
                    },
                    "policyEnabledTools": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "complianceScore": {
                      "type": "integer",
                      "description": "0–100 against the fleet tool policy (the /admin/connect-health formula)."
                    },
                    "failingChecks": {
                      "type": "integer"
                    },
                    "checks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "connectVersion": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "lastSeen": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "userHash",
                    "generatedAt",
                    "windowHours",
                    "policyEnabledTools",
                    "complianceScore",
                    "failingChecks",
                    "checks",
                    "connectVersion",
                    "lastSeen"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Invalid or expired device token (static message; fail closed)."
          }
        }
      }
    },
    "/connect/health": {
      "post": {
        "operationId": "recordConnectHealth",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Report connect-health check results",
        "description": "Best-effort, content-free rollup of `anyray-connect doctor` results (gateway reachability, retrieval loop, per-tool MCP registration, enrollment, connect run). The gateway folds these into a rolling 24h window forwarded to the Billing app on the next meter round, so the vendor fleet view can see client-side problems. Metadata only — closed-charset tokens and counts, never content. Accepts an unattributed report and always returns 200.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "events": {
                    "type": "array",
                    "maxItems": 512,
                    "items": {
                      "type": "object",
                      "properties": {
                        "tool": {
                          "type": "string",
                          "pattern": "^[a-z0-9_-]{1,64}$",
                          "description": "Client/tool id (e.g. opencode, claude-code)."
                        },
                        "checkId": {
                          "type": "string",
                          "pattern": "^[a-z0-9_]{1,64}$",
                          "description": "Doctor check id (e.g. gateway_reachable)."
                        },
                        "status": {
                          "type": "string",
                          "pattern": "^[a-z0-9_]{1,32}$",
                          "description": "Check result token (e.g. ok, unreachable)."
                        },
                        "errorClass": {
                          "type": "string",
                          "pattern": "^[A-Za-z0-9_$.-]{1,64}$",
                          "description": "Classified failure reason — a class name, never a message."
                        }
                      },
                      "required": [
                        "tool",
                        "checkId",
                        "status"
                      ]
                    }
                  }
                },
                "required": [
                  "events"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "recorded": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Number of valid events recorded."
                    }
                  },
                  "required": [
                    "status",
                    "recorded"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/connect/hook-savings": {
      "post": {
        "operationId": "recordHookSavings",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Record source-side hook savings",
        "description": "Best-effort beacon from the connect PostToolUse hook reporting tokens it trimmed from a tool output before it entered the transcript. Metadata only (a token count) — no content. Always returns 200.",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "estTokensSaved": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Estimated tokens trimmed at the source by the hook."
                  }
                },
                "required": [
                  "estTokensSaved"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "recorded": {
                      "type": "boolean",
                      "description": "Whether the beacon was attributed to a user."
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/connect/optimize-output": {
      "post": {
        "operationId": "optimizeHookOutput",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Optimize a tool output at the source",
        "description": "The connect PostToolUse hook posts a raw tool output; the gateway proxies it to the optimizer's output-trim pass and returns the (possibly trimmed) text plus a content-free retrieval handle for the stashed original. Trimming at the source keeps the transcript cache-safe by construction.",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "output": {
                    "type": "string",
                    "description": "Raw tool output to trim."
                  },
                  "tool": {
                    "type": "string",
                    "description": "Originating tool name (routing hint)."
                  },
                  "context": {
                    "type": "object",
                    "description": "Optional content-free hints (e.g. estimated size).",
                    "additionalProperties": true
                  }
                },
                "required": [
                  "output"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "output": {
                      "type": "string",
                      "description": "Trimmed output to write into the transcript."
                    },
                    "optimized": {
                      "type": "boolean",
                      "description": "Whether any trim was applied."
                    },
                    "handle": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Content-free retrieval handle for the stashed original, or null when nothing was stashed. Retrieve with POST /connect/retrieve."
                    },
                    "savedTokens": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Tokens trimmed, if any."
                    }
                  },
                  "required": [
                    "output"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/connect/mcp-oauth/authorize": {
      "post": {
        "operationId": "connectAuthorizeMcpOauth",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Start a personal OAuth grant for an MCP connector",
        "description": "Start the vendor OAuth flow for a connector. The returned URL contains no connector token; its callback stages a userless authorization until the browser-displayed claim code is redeemed by a verified client-key user.",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160,
                    "description": "The saved OAuth connector name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The HTTPS vendor authorization URL; it contains no connector token.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "authorizationUrl"
                  ],
                  "properties": {
                    "authorizationUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON body or connector name"
          },
          "401": {
            "description": "Missing or invalid client key"
          },
          "409": {
            "description": "Connector is not ready for OAuth authorization"
          },
          "502": {
            "description": "Could not start connector authorization"
          },
          "503": {
            "description": "OAuth connector authorization unavailable"
          }
        }
      }
    },
    "/connect/mcp-oauth/complete": {
      "post": {
        "operationId": "connectCompleteMcpOauth",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Claim a personal MCP OAuth grant",
        "description": "Binds the vendor-approved credential staged by the OAuth callback to the verified client-key principal redeeming the browser-displayed single-use claim code. The initiator is not trusted as the recipient. This confirmation returns no connector credential.",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "claimCode"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160,
                    "description": "The saved OAuth connector name."
                  },
                  "claimCode": {
                    "type": "string",
                    "minLength": 12,
                    "maxLength": 12,
                    "pattern": "^[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{12}$",
                    "description": "The single-use claim code displayed only in the consenting browser."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The credential is active for the verified client-key user named in the response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "user"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "user": {
                      "type": "string",
                      "description": "The verified client-key account that now holds this connector grant."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON body or connector name"
          },
          "401": {
            "description": "Missing or invalid client key"
          },
          "409": {
            "description": "No staged authorization is ready for confirmation"
          },
          "502": {
            "description": "Could not complete connector authorization"
          },
          "503": {
            "description": "OAuth connector authorization unavailable"
          }
        }
      }
    },
    "/connect/mcp-heartbeat": {
      "post": {
        "operationId": "connectMcpHeartbeat",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "MCP server session-start heartbeat",
        "description": "Called by the anyray-connect MCP server while a coding session is active. A client-key-verified call renews the durable retrieval lease used to guard handle-producing strategies. Empty body; the lease expires after 6 hours without authenticated activity, and heartbeat writes are debounced to five minutes.",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "responses": {
          "204": {
            "description": "Live retrieval lease renewed (no body)."
          },
          "401": {
            "description": "Missing or invalid client key."
          }
        }
      }
    },
    "/.well-known/oauth-protected-resource": {
      "get": {
        "operationId": "getMcpProtectedResourceMetadata",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Discover OAuth for the organization MCP resource",
        "description": "Public RFC 9728-style metadata for `/mcp/org`. The exact gateway resource URL is paired with the deployment's WorkOS AuthKit issuer. No scopes are invented; the resource audience is the authorization boundary.",
        "security": [],
        "responses": {
          "200": {
            "description": "Protected resource metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "resource",
                    "authorization_servers",
                    "bearer_methods_supported"
                  ],
                  "properties": {
                    "resource": {
                      "type": "string",
                      "format": "uri"
                    },
                    "authorization_servers": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uri"
                      }
                    },
                    "bearer_methods_supported": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "header"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Public OAuth discovery is rate limited. Honor `Retry-After`."
          },
          "503": {
            "description": "AuthKit or Billing configuration is unavailable."
          }
        }
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "operationId": "getMcpAuthorizationServerMetadata",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Discover AuthKit authorization-server endpoints",
        "description": "Compatibility proxy for older MCP clients that request RFC 8414 metadata from the MCP server origin. The validated response comes from the configured WorkOS AuthKit issuer.",
        "security": [],
        "responses": {
          "200": {
            "description": "AuthKit authorization-server metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "Public OAuth discovery is rate limited. Honor `Retry-After`."
          },
          "503": {
            "description": "AuthKit or Billing configuration is unavailable."
          }
        }
      }
    },
    "/mcp/org": {
      "post": {
        "operationId": "mcpOrgStreamableHttp",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Organization-managed MCP connectors",
        "description": "Relays one streamable-HTTP MCP request to the organization's managed connector set. Existing `x-anyray-api-key` and `Authorization: Bearer ark_…` credentials remain supported and take precedence. Other bearer tokens must be WorkOS AuthKit JWTs whose scalar `aud` exactly equals this gateway's `/mcp/org` URL; Billing then requires an activated, currently connected enterprise SSO configuration and verifies the subject's live organization membership, allowed domain, team, and revocation state. Tool arguments and results transit without being logged or persisted.",
        "security": [
          {
            "ConnectKey": []
          },
          {
            "AuthKitBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "A streamable-HTTP MCP JSON-RPC message.",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The MCP response relayed from the managed hub or a directly authorized connector.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid. OAuth-capable clients receive `WWW-Authenticate` with `resource_metadata`."
          },
          "404": {
            "description": "The organization MCP hub is not configured."
          },
          "429": {
            "description": "OAuth authentication or identity resolution is rate limited. Honor `Retry-After`."
          },
          "502": {
            "description": "The managed hub or direct connector is unreachable."
          },
          "503": {
            "description": "OAuth identity resolution or the organization MCP hub is unavailable."
          }
        }
      },
      "delete": {
        "operationId": "deleteMcpOrgSession",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Close an organization MCP session",
        "description": "Relays a streamable-HTTP session close using the same client-key or AuthKit authentication as POST.",
        "security": [
          {
            "ConnectKey": []
          },
          {
            "AuthKitBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Upstream close response."
          },
          "401": {
            "description": "Authentication is missing or invalid. OAuth-capable clients receive the discovery challenge."
          },
          "429": {
            "description": "OAuth authentication or identity resolution is rate limited. Honor `Retry-After`."
          },
          "503": {
            "description": "OAuth identity resolution or the organization MCP hub is unavailable."
          }
        }
      },
      "get": {
        "operationId": "mcpOrgStreamableHttpStream",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Refuse the authenticated server-initiated MCP stream",
        "description": "Unauthenticated requests receive the OAuth discovery challenge. An authenticated request receives `405` with `Allow: POST, DELETE` because the organization resource does not expose a server-initiated GET stream.",
        "security": [
          {
            "ConnectKey": []
          },
          {
            "AuthKitBearer": []
          }
        ],
        "responses": {
          "401": {
            "description": "Authentication is missing or invalid. OAuth-capable clients receive the discovery challenge."
          },
          "405": {
            "description": "Authenticated, but no server-initiated stream is available."
          },
          "429": {
            "description": "OAuth authentication or identity resolution is rate limited. Honor `Retry-After`."
          },
          "503": {
            "description": "OAuth identity resolution is unavailable."
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcpStreamableHttp",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "The gateway as a remote MCP server (streamable HTTP)",
        "description": "Serves `anyray_retrieve` + `anyray_recall` over the MCP streamable-HTTP transport, so any MCP-capable agent runtime closes the retrieval loop with no `anyray-connect` install and no code. Point the runtime at this URL with the client key it already holds (`{ \"url\": \"https://<gateway>/mcp\", \"headers\": { \"x-anyray-api-key\": \"<client key>\" } }`). Scope is the retrieval pair only: the stdio server's other tools act on a local workspace a remote endpoint does not have.\n\nStateless transport (spec revisions `2025-06-18` and `2025-03-26`): one JSON-RPC message per POST, no `Mcp-Session-Id` (every call is independently authenticated by the client key), batch arrays rejected with `-32600`, and a notification (no `id`) answered `202` with no body. Methods: `initialize`, `ping`, `tools/list`, `tools/call`.\n\nAn `initialize` here latches retrieve capability exactly like `/connect/mcp-heartbeat`: the host that sent it is the process exposing tools to the model. Send `x-anyray-retrieve-probe: 1` on a human/diagnostic call so it does not latch.\n\nA `tools/call` result returns CONTENT to the caller, so a verified identity is mandatory and a placeholder is refused. Tool-level failures come back in-band as a `200` with `isError: true`, not as a JSON-RPC error, so the model can read the failure and adapt.",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "A single JSON-RPC 2.0 message. Batch arrays are rejected.",
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "const": "2.0"
                  },
                  "id": {
                    "type": [
                      "string",
                      "number"
                    ],
                    "description": "Omit for a notification, which is acknowledged with `202` and no body."
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "initialize",
                      "ping",
                      "tools/list",
                      "tools/call"
                    ]
                  },
                  "params": {
                    "type": "object",
                    "additionalProperties": true
                  }
                },
                "required": [
                  "jsonrpc",
                  "method"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The JSON-RPC response. A failed tool call is a success here with `result.isError: true`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string",
                      "const": "2.0"
                    },
                    "id": {
                      "type": [
                        "string",
                        "number",
                        "null"
                      ]
                    },
                    "result": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "error": {
                      "type": "object",
                      "description": "Protocol-level error only: parse error, malformed message, unknown method, or unknown tool. Never quotes the request body.",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "required": [
                    "jsonrpc"
                  ]
                }
              }
            }
          },
          "202": {
            "description": "A notification (no `id`) was accepted. No body: this server holds no per-session state to advance."
          },
          "401": {
            "description": "Missing or invalid client key. This route returns content, so an unverified identity is refused rather than resolved to a placeholder."
          }
        }
      },
      "get": {
        "operationId": "mcpStreamableHttpStream",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Refuse the server-initiated MCP stream",
        "description": "Always `405` with `Allow: POST`. The streamable-HTTP spec lets a stateless server decline the GET stream, and answering so is how a client learns not to wait for server-initiated messages. Unauthenticated: the refusal is the whole response, so there is nothing to gate.",
        "responses": {
          "405": {
            "description": "No server-initiated stream. `Allow: POST`."
          }
        }
      }
    },
    "/connect/retrieve": {
      "post": {
        "operationId": "retrieveConnectHandle",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Retrieve a stashed original by handle",
        "description": "Fetches the full original content stashed by a prior optimize-output/CCR trim, keyed by its content-free handle. Proxies the optimizer's `/v1/retrieve`. Returns the content to the client that owns the handle only.",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "handle": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Content-free handle returned by optimize-output."
                  }
                },
                "required": [
                  "handle"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "handle": {
                      "type": "string",
                      "description": "The requested handle."
                    },
                    "content": {
                      "type": "string",
                      "description": "The stashed original content."
                    },
                    "found": {
                      "type": "boolean",
                      "description": "Whether the handle resolved."
                    }
                  },
                  "required": [
                    "handle"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Handle not found or expired."
          }
        }
      }
    },
    "/connect/recall": {
      "post": {
        "operationId": "recallConnectContext",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Semantic recall over stashed context",
        "description": "Ranks previously-stashed context against a query and returns the best content-free match handles (with a relevance score and a short preview). The client fetches full content via POST /connect/retrieve. Proxies the optimizer recall pass.",
        "security": [
          {
            "ConnectKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Query to rank stashed context against."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Max matches to return."
                  }
                },
                "required": [
                  "query"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok",
                        "unavailable"
                      ]
                    },
                    "matches": {
                      "type": "array",
                      "description": "Ranked content-free matches (empty when unavailable).",
                      "items": {
                        "type": "object",
                        "properties": {
                          "handle": {
                            "type": "string",
                            "description": "Retrieval handle for POST /connect/retrieve."
                          },
                          "score": {
                            "type": "number",
                            "description": "Relevance score."
                          },
                          "preview": {
                            "type": "string",
                            "description": "Short preview snippet of the match."
                          }
                        },
                        "required": [
                          "handle",
                          "score",
                          "preview"
                        ]
                      }
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/sso/cli/start": {
      "post": {
        "operationId": "startCliSsoLogin",
        "tags": [
          "Connect · SSO enrollment"
        ],
        "summary": "Start a self-service CLI SSO login",
        "description": "Creates a durable ten-minute gateway session and a deployment-authenticated Billing app identity grant. Returns the browser URL, human confirmation code, and a separate poll capability. The endpoint is unauthenticated and rate-limited by source IP.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SSO login started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "browser_url",
                    "user_code",
                    "poll_secret",
                    "interval",
                    "expires_in"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "browser_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "user_code": {
                      "type": "string",
                      "pattern": "^[A-Z2-9]{4}-[A-Z2-9]{4}$"
                    },
                    "poll_secret": {
                      "type": "string",
                      "description": "High-entropy poll capability returned once; never put it in a URL or log."
                    },
                    "interval": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "expires_in": {
                      "type": "integer",
                      "minimum": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "description": "Source-IP start rate limit exceeded."
          },
          "503": {
            "description": "The identity authority or durable session store is unavailable."
          }
        }
      }
    },
    "/sso/cli/poll/{id}": {
      "get": {
        "operationId": "pollCliSsoLogin",
        "tags": [
          "Connect · SSO enrollment"
        ],
        "summary": "Poll SSO completion and mint the selected team key",
        "description": "Returns pending until WorkOS verifies the identity, then returns the governed team list. Send one eligible team in `x-anyray-team` to atomically mint and receive the personal key once.",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-anyray-poll-secret",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Separate high-entropy poll capability from the start response."
          },
          {
            "name": "x-anyray-team",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "One team from the verified team-selection response."
          }
        ],
        "responses": {
          "200": {
            "description": "Team selection is available, or the selected team key was minted and returned once."
          },
          "202": {
            "description": "Browser SSO is still pending."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "Another request is minting the key."
          },
          "410": {
            "description": "The login expired or was already consumed."
          },
          "503": {
            "description": "The identity authority, key store, or durable session store is unavailable."
          }
        }
      }
    },
    "/connect/verify": {
      "post": {
        "operationId": "verifyConnectDevCert",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Verify a dev cert and mint a connect key",
        "description": "Unauthenticated (rate-limited) enrollment endpoint. The client presents a signed dev-cert proof (`cert` + `challenge` + `sig`); on success the gateway verifies the signature offline and mints an `ark_` connect key bound to the cert's user/team, persisted in the shared spend DB. This is how a developer obtains the ConnectKey the other `/connect/*` routes require.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Dev-cert proof. Content-free — identity material only.",
                "properties": {
                  "cert": {
                    "type": "object",
                    "description": "The signed dev cert (user/team, issuer, expiry, public key).",
                    "additionalProperties": true
                  },
                  "challenge": {
                    "type": "object",
                    "additionalProperties": true,
                    "properties": {
                      "deploymentId": {
                        "type": "string"
                      },
                      "issuedAt": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "nonce": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "deploymentId",
                      "issuedAt",
                      "nonce"
                    ],
                    "description": "Fresh deployment-bound challenge the client signed."
                  },
                  "sig": {
                    "type": "string",
                    "description": "Signature over the challenge, verifiable against the cert."
                  }
                },
                "required": [
                  "cert",
                  "challenge",
                  "sig"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified — key minted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string",
                      "description": "The minted `ark_` connect key."
                    },
                    "user": {
                      "type": "string",
                      "description": "Attributed user id from the cert."
                    },
                    "team": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Attributed team id, if the cert carried one."
                    },
                    "expiresAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Key expiry (ISO-8601), or null if non-expiring.",
                      "format": "date-time"
                    },
                    "capabilities": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Additive gateway capabilities. Current gateways include `stable-key-heartbeat-v1`."
                    }
                  },
                  "required": [
                    "key",
                    "user",
                    "capabilities"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Proof invalid, expired, or signature verification failed."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/connect/key/heartbeat": {
      "post": {
        "operationId": "heartbeatConnectClientKey",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Extend the current connect key",
        "description": "Extends the expiry of the same enrollment-minted `ark_` key. The bearer alone is insufficient: the request must also carry a fresh, purpose-bound proof from the device key bound into the signed DevCert (legacy Ed25519, or P-256 when `devKeyAlg` is `ES256`). The endpoint can recover a just-expired key, but refuses unknown, revoked, admin-minted, identity-mismatched, or deactivated-user keys. It never creates or returns a replacement raw key.",
        "security": [],
        "parameters": [
          {
            "name": "x-anyray-api-key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^ark_"
            },
            "description": "The existing personal client key whose expiry will be extended."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "cert": {
                    "type": "object",
                    "description": "The control-plane-signed DevCert binding the user/team and device public key.",
                    "additionalProperties": true
                  },
                  "challenge": {
                    "type": "object",
                    "additionalProperties": true,
                    "properties": {
                      "deploymentId": {
                        "type": "string"
                      },
                      "issuedAt": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "nonce": {
                        "type": "string"
                      },
                      "purpose": {
                        "type": "string",
                        "const": "key-heartbeat"
                      }
                    },
                    "required": [
                      "deploymentId",
                      "issuedAt",
                      "nonce",
                      "purpose"
                    ]
                  },
                  "sig": {
                    "type": "string",
                    "description": "Signature over the canonical heartbeat challenge, using the DevCert payload's proof-key algorithm."
                  }
                },
                "required": [
                  "cert",
                  "challenge",
                  "sig"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The existing key was extended. No replacement key is returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "credentialMode": {
                      "type": "string",
                      "const": "stable-key-heartbeat-v1"
                    }
                  },
                  "required": [
                    "expiresAt",
                    "credentialMode"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "The existing client-key header is missing."
          },
          "403": {
            "description": "The proof, certificate, entitlement, revocation state, or durable key binding was rejected."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/audio/speech": {
      "post": {
        "operationId": "createSpeech",
        "tags": [
          "Audio"
        ],
        "summary": "Create speech (text-to-speech)",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "TTS model id."
                  },
                  "input": {
                    "type": "string",
                    "description": "Text to synthesize."
                  },
                  "voice": {
                    "type": "string",
                    "description": "Voice id."
                  },
                  "response_format": {
                    "type": "string",
                    "description": "Audio container (e.g. `mp3`, `wav`, `opus`)."
                  },
                  "speed": {
                    "type": "number",
                    "description": "Playback speed multiplier."
                  }
                },
                "required": [
                  "model",
                  "input",
                  "voice"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Synthesized audio stream.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/v1/audio/transcriptions": {
      "post": {
        "operationId": "createTranscription",
        "tags": [
          "Audio"
        ],
        "summary": "Transcribe audio",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Audio file to transcribe."
                  },
                  "model": {
                    "type": "string",
                    "description": "Transcription model id."
                  },
                  "language": {
                    "type": "string",
                    "description": "Optional ISO-639-1 language hint."
                  },
                  "prompt": {
                    "type": "string",
                    "description": "Optional decoding prompt."
                  },
                  "response_format": {
                    "type": "string",
                    "description": "Output format (`json`, `text`, `srt`, `verbose_json`, `vtt`)."
                  }
                },
                "required": [
                  "file",
                  "model"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI-compatible provider response, relayed verbatim.",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/v1/audio/translations": {
      "post": {
        "operationId": "createTranslation",
        "tags": [
          "Audio"
        ],
        "summary": "Translate audio to English",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Audio file to translate."
                  },
                  "model": {
                    "type": "string",
                    "description": "Translation model id."
                  },
                  "prompt": {
                    "type": "string",
                    "description": "Optional decoding prompt."
                  },
                  "response_format": {
                    "type": "string",
                    "description": "Output format (`json`, `text`, `srt`, `verbose_json`, `vtt`)."
                  }
                },
                "required": [
                  "file",
                  "model"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI-compatible provider response, relayed verbatim.",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/v1/images/generations": {
      "post": {
        "operationId": "createImage",
        "tags": [
          "Images"
        ],
        "summary": "Generate images",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "Image model id."
                  },
                  "prompt": {
                    "type": "string",
                    "description": "Text prompt describing the image."
                  },
                  "n": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Number of images to generate."
                  },
                  "size": {
                    "type": "string",
                    "description": "Image dimensions (e.g. `1024x1024`)."
                  },
                  "response_format": {
                    "type": "string",
                    "description": "`url` or `b64_json`."
                  },
                  "quality": {
                    "type": "string",
                    "description": "Rendering quality."
                  },
                  "style": {
                    "type": "string",
                    "description": "Rendering style."
                  }
                },
                "required": [
                  "prompt"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI-compatible provider response, relayed verbatim.",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/v1/images/edits": {
      "post": {
        "operationId": "createImageEdit",
        "tags": [
          "Images"
        ],
        "summary": "Edit an image",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "image": {
                    "type": "string",
                    "format": "binary",
                    "description": "Source image to edit."
                  },
                  "prompt": {
                    "type": "string",
                    "description": "Instruction describing the edit."
                  },
                  "mask": {
                    "type": "string",
                    "format": "binary",
                    "description": "Optional mask marking the region to edit."
                  },
                  "model": {
                    "type": "string",
                    "description": "Image model id."
                  },
                  "n": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Number of edits to generate."
                  },
                  "size": {
                    "type": "string",
                    "description": "Output dimensions."
                  },
                  "response_format": {
                    "type": "string",
                    "description": "`url` or `b64_json`."
                  }
                },
                "required": [
                  "image",
                  "prompt"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI-compatible provider response, relayed verbatim.",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/v1/files": {
      "get": {
        "operationId": "listFiles",
        "tags": [
          "Files"
        ],
        "summary": "List uploaded files",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A file object.",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      },
      "post": {
        "operationId": "uploadFile",
        "tags": [
          "Files"
        ],
        "summary": "Upload a file",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "File contents to upload."
                  },
                  "purpose": {
                    "type": "string",
                    "description": "Intended purpose (e.g. `batch`, `fine-tune`, `assistants`)."
                  }
                },
                "required": [
                  "file",
                  "purpose"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI-compatible provider response, relayed verbatim.",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/v1/files/{id}": {
      "get": {
        "operationId": "retrieveFile",
        "tags": [
          "Files"
        ],
        "summary": "Retrieve a file's metadata",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "File id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI-compatible provider response, relayed verbatim.",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "404": {
            "description": "File not found."
          }
        }
      },
      "delete": {
        "operationId": "deleteFile",
        "tags": [
          "Files"
        ],
        "summary": "Delete a file",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "File id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "object": {
                      "type": "string"
                    },
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "404": {
            "description": "File not found."
          }
        }
      }
    },
    "/v1/files/{id}/content": {
      "get": {
        "operationId": "retrieveFileContent",
        "tags": [
          "Files"
        ],
        "summary": "Download a file's content",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "File id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Raw file content.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "404": {
            "description": "File not found."
          }
        }
      }
    },
    "/v1/batches": {
      "get": {
        "operationId": "listBatches",
        "tags": [
          "Batches"
        ],
        "summary": "List batches",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A batch object.",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      },
      "post": {
        "operationId": "createBatch",
        "tags": [
          "Batches"
        ],
        "summary": "Create a batch",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "input_file_id": {
                    "type": "string",
                    "description": "Id of the uploaded JSONL input file."
                  },
                  "endpoint": {
                    "type": "string",
                    "description": "Target endpoint (e.g. `/v1/chat/completions`)."
                  },
                  "completion_window": {
                    "type": "string",
                    "description": "Completion window (e.g. `24h`)."
                  }
                },
                "required": [
                  "input_file_id",
                  "endpoint",
                  "completion_window"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI-compatible provider response, relayed verbatim.",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/v1/batches/{id}": {
      "get": {
        "operationId": "retrieveBatch",
        "tags": [
          "Batches"
        ],
        "summary": "Retrieve a batch",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Batch id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI-compatible provider response, relayed verbatim.",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "404": {
            "description": "Batch not found."
          }
        }
      }
    },
    "/v1/batches/{id}/cancel": {
      "post": {
        "operationId": "cancelBatch",
        "tags": [
          "Batches"
        ],
        "summary": "Cancel a batch",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Batch id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI-compatible provider response, relayed verbatim.",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "404": {
            "description": "Batch not found."
          }
        }
      }
    },
    "/v1/responses": {
      "post": {
        "operationId": "createResponse",
        "tags": [
          "Responses"
        ],
        "summary": "Create a model response",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "Model id."
                  },
                  "input": {
                    "description": "Input text or structured input items (provider-defined shape)."
                  }
                },
                "required": [
                  "model",
                  "input"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI-compatible provider response, relayed verbatim.",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/ServiceKeyBudgetExceeded"
          }
        }
      }
    },
    "/v1/responses/{id}": {
      "get": {
        "operationId": "retrieveResponse",
        "tags": [
          "Responses"
        ],
        "summary": "Retrieve a model response",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Response id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI-compatible provider response, relayed verbatim.",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "404": {
            "description": "Response not found."
          }
        }
      },
      "delete": {
        "operationId": "deleteResponse",
        "tags": [
          "Responses"
        ],
        "summary": "Delete a model response",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Response id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "object": {
                      "type": "string"
                    },
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "404": {
            "description": "Response not found."
          }
        }
      }
    },
    "/v1/responses/{id}/input_items": {
      "get": {
        "operationId": "listResponseInputItems",
        "tags": [
          "Responses"
        ],
        "summary": "List a response's input items",
        "description": "OpenAI-compatible request; forwarded to the selected upstream provider with the server-held provider key injected. The response shape is the provider's, relayed verbatim; the gateway meters it content-free.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderHeader"
          },
          {
            "$ref": "#/components/parameters/MetadataHeader"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Response id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "An input item.",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          },
          "404": {
            "description": "Response not found."
          }
        }
      }
    },
    "/admin/update/settings": {
      "put": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Update policy",
        "description": "Set whether soft (image-only, preflight-green) updates apply unattended (Compose installs; other platforms are always notify-only). Default on. Hard updates are never applied unattended regardless of this setting. Requires the `update:run` capability.",
        "operationId": "adminUpdateSettings",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "autoSoftUpdates"
                ],
                "properties": {
                  "autoSoftUpdates": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "autoSoftUpdates": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid autoSoftUpdates value"
          }
        },
        "x-required-capability": "update:run"
      }
    },
    "/connect/machine": {
      "post": {
        "operationId": "reportConnectMachine",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Report the machine↔seat join",
        "description": "The refresh loop reports which machine this seat runs on (the endpoint lane’s machine↔seat join). Gated like the key heartbeat: the current `ark_` key plus a fresh device possession proof; `machineUuid` rides as a sibling of the proof. Only sha256 hashes are stored — never the raw UUID, a hostname, or a username. Off-Postgres the join lane is inert (`recorded: false`).",
        "responses": {
          "200": {
            "description": "`{status:\"ok\", recorded}` — recorded is false when the join store is unavailable."
          },
          "400": {
            "description": "Malformed proof or machineUuid."
          },
          "401": {
            "description": "Missing/invalid key or proof."
          }
        }
      }
    },
    "/connect/directive": {
      "get": {
        "operationId": "pullConnectDirective",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Pull the next remediation directive",
        "description": "Pull the seat's next remediation directive (`{directive:{id,kind,tool?}}` or `{}`). Key-gated and scoped to the caller's own pseudonymous seat; a directive re-delivers until acked. `tool` is present only for `revert_tool`. The client declares the kinds it can execute in `x-anyray-directive-kinds` (a comma list; absent means the three original kinds). A kind it did not advertise is SKIPPED rather than delivered: an unrecognized directive is never acked, so handing one over would park it at the head of that seat's queue and swallow every later directive.",
        "responses": {
          "200": {
            "description": "`{directive:{id,kind}}` or `{}`."
          },
          "401": {
            "description": "Missing/invalid client key."
          }
        }
      }
    },
    "/connect/directive/ack": {
      "post": {
        "operationId": "ackConnectDirective",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Acknowledge an applied directive",
        "description": "Closes the loop on a pulled directive (`{id, result:\"ok\"|\"failed\"}`). Scoped to the caller’s own seat — a leaked id cannot close another developer’s directive. Best-effort: an unacked directive simply re-delivers.",
        "responses": {
          "200": {
            "description": "`{status:\"ok\"}`."
          },
          "400": {
            "description": "Malformed id or result."
          },
          "401": {
            "description": "Missing/invalid client key."
          }
        }
      }
    },
    "/connect/offboard": {
      "post": {
        "operationId": "offboardConnectSeat",
        "tags": [
          "Connect · Coding-tool integration"
        ],
        "summary": "Announce that this seat has been reverted off Anyray",
        "description": "The last call a full `anyray-connect --revert` makes before it deletes the credential that authenticates it. Scoped to the caller’s own verified seat; the body carries nothing. Marks the seat `offboarded` so the console can tell a deliberate disconnect from a machine that simply stopped reporting, and so the fleet stops scoring it as failing. Reporting again (re-enrolling) clears the mark. Content-free: what is stored is the opaque `userHash` and an instant.",
        "responses": {
          "200": {
            "description": "`{status:\"ok\", recorded:<bool>}`. `recorded:false` when the durable store could not hold it — the developer’s revert never depends on this call, so it is never an error."
          },
          "401": {
            "description": "Missing/invalid client key."
          }
        }
      }
    },
    "/admin/endpoint-fleet/hosts/{id}": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "End-point fleet host detail",
        "description": "Content-free per-host detail from the selected Fleet or endpoint-control lane: hostname, status, evidence source, policy results, and script-run metadata. Not configured returns `{configured:false}`; an unavailable upstream returns `{reachable:false}`. Requires the `observability:read` capability.",
        "operationId": "adminGetEndpointFleetHost",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "observability:read"
      }
    },
    "/admin/endpoint-fleet/hosts/{id}/run-script": {
      "post": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Run a remediation script on a host",
        "description": "Run a mapped remediation script on one enrolled host (console button). The Fleet compatibility lane is cooldown-guarded; endpoint-control queues the execution server-side. Customer-managed evidence hosts return `409 monitor_only`. Audited and content-free. Requires the `provisioning:manage` capability.",
        "operationId": "adminRunEndpointFleetScript",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "provisioning:manage"
      }
    },
    "/admin/endpoint-fleet/pack": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "End-point policy pack version",
        "description": "Bundled vs. applied org policy-pack version (drift indicator). Requires the `config:read` capability.",
        "operationId": "adminGetEndpointFleetPack",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "config:read"
      }
    },
    "/admin/endpoint-fleet/sync": {
      "post": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Sync the org policy pack to Fleet",
        "description": "Apply the bundled org policy pack (policies, scripts, failing-policies webhook) to the configured Fleet server. Idempotent and non-destructive. Requires the `provisioning:manage` capability.",
        "operationId": "adminSyncEndpointFleetPack",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "provisioning:manage"
      }
    },
    "/admin/endpoint-fleet/enroll-secret": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Read the Fleet enroll secret",
        "description": "Read the org's Fleet enroll secret, live from the Fleet server (never stored in Anyray). Credential-grade — requires the `enrollment:manage` capability.",
        "operationId": "adminGetEndpointFleetEnrollSecret",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "enrollment:manage"
      }
    },
    "/admin/endpoint-fleet/enroll-secret/rotate": {
      "post": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Rotate the Fleet enroll secret",
        "description": "Rotate the enroll secret. Already-enrolled hosts are unaffected (they hold node keys); new installers must be regenerated. Requires the `enrollment:manage` capability.",
        "operationId": "adminRotateEndpointFleetEnrollSecret",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "enrollment:manage"
      }
    },
    "/admin/endpoint-fleet/installers": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "List end-point installers",
        "description": "List the stored per-OS fleetd installer artifacts and the pack version each was built with. Credential-grade (installers bake the enroll secret) — requires the `enrollment:manage` capability.",
        "operationId": "adminListEndpointFleetInstallers",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "enrollment:manage"
      }
    },
    "/admin/endpoint-fleet/installers/{os}": {
      "get": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Download an end-point installer",
        "description": "Download the stored fleetd installer for an OS (pkg/msi/deb/rpm). Bakes the enroll secret — requires the `enrollment:manage` capability.",
        "operationId": "adminGetEndpointFleetInstaller",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "enrollment:manage"
      },
      "put": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Upload an end-point installer",
        "description": "Upload a pre-built fleetd installer for an OS (provisioning lane / CI). Requires the `provisioning:manage` capability.",
        "operationId": "adminPutEndpointFleetInstaller",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "provisioning:manage"
      }
    },
    "/admin/endpoint-fleet/mdm-profile": {
      "post": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Download the end-point MDM enrollment profile",
        "description": "Build this deployment's macOS enrollment profile (`.mobileconfig`) from the stored end-point control-server address and the organization's enroll secret. The profile is the per-organization half of the shared, credential-free agent installer and uses payload type `com.fleetdm.fleetd.config`. Repeated downloads contain the same current enrollment configuration and do not rotate the secret. The response body is a live credential and must not be logged or rendered. Requires the `enrollment:manage` capability and the deployment owner; proxied to Anyray Portal with this deployment's token.",
        "operationId": "adminMintEndpointFleetMdmProfile",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The organization's current enrollment profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "No end-point fleet is provisioned for this deployment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Deployment not connected to Anyray Portal, or the end-point platform is not enabled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "enrollment:manage"
      }
    },
    "/admin/endpoint-fleet/user-machines": {
      "post": {
        "tags": [
          "Admin · Health & settings"
        ],
        "summary": "Per-user end-point machine compliance",
        "description": "Resolve which end-point machines each supplied roster identity's enrolled seat runs on, with each machine's compliance state. The gateway resolves identity → pseudonym → machine-seat rows → the end-point host with the same hardware-UUID hash entirely server-side; the pseudonym secret never leaves the deployment and no hash is mapped back to an identity the caller did not supply. A machine that joins to no end-point host record carries no compliance claim. Read-only despite the POST (the roster does not fit a query string). Requires the `observability:read` capability.",
        "operationId": "adminGetEndpointFleetUserMachines",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "users"
                ],
                "properties": {
                  "users": {
                    "type": "array",
                    "description": "Roster identities to resolve (1–200).",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "x-required-capability": "observability:read"
      }
    },
    "/admin/api-keys": {
      "get": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "List scoped admin API keys",
        "description": "List `aak_…` admin API keys as metadata only. Raw tokens and hashes are never returned. Requires the `config:read` capability and the deployment owner.",
        "operationId": "adminListAdminApiKeys",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Admin API key roster",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminApiKeyListResponse"
                }
              }
            }
          },
          "503": {
            "description": "Key store unreachable (`admin_key_store_unavailable`); fail-closed infrastructure fault, not a credential problem."
          }
        },
        "x-required-capability": "config:read"
      },
      "post": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Mint a scoped admin API key",
        "description": "Mint an `aak_…` automation credential with exactly one grant shape: a subset of the admin capabilities or native Management API v1 scopes. The grant must be held by the minter and exclude the un-scopeable set; a key can never mint keys. Scope-minted keys are v1-only and cannot call legacy `/admin/*` capability-gated routes. The raw token is returned exactly once. Requires the `adminkeys:manage` capability and the deployment owner.",
        "operationId": "adminMintAdminApiKey",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminApiKeyCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key minted; save the raw key now because it cannot be recovered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminApiKeyMintResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing, conflicting, empty, or unknown capability/scope ids, or an invalid expiry."
          },
          "403": {
            "description": "An un-scopeable capability or scope, a grant exceeding the minter's own, or an API-key principal attempting to mint."
          },
          "503": {
            "description": "Key store unreachable (`admin_key_store_unavailable`)."
          }
        },
        "x-required-capability": "adminkeys:manage"
      }
    },
    "/admin/api-keys/{id}": {
      "delete": {
        "tags": [
          "Admin · Access, SSO & enrollment"
        ],
        "summary": "Revoke a scoped admin API key",
        "description": "Revoke the key (idempotent; it stays listed, marked revoked, and stops working on the next request on every replica). A key can never revoke keys. Requires the `adminkeys:manage` capability and the deployment owner.",
        "operationId": "adminRevokeAdminApiKey",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown key id."
          },
          "503": {
            "description": "Key store unreachable (`admin_key_store_unavailable`)."
          }
        },
        "x-required-capability": "adminkeys:manage"
      }
    },
    "/admin/user-caps/{user}": {
      "patch": {
        "tags": [
          "Admin · Spend & governance"
        ],
        "summary": "Patch one user's caps/budget",
        "description": "Merge a partial edit into a single user's cap entry (omit = keep, null = clear; clearing every field removes the entry). The automation lane for scoped admin API keys: a budget bot needs only `config:read` + `usercaps:write`. Never touches alert settings. Requires the `usercaps:write` capability.",
        "operationId": "adminPatchUserCap",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[\\w.@+:-]{1,128}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserCapPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK; same shape as GET /admin/user-caps.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserCapsGet"
                }
              }
            }
          },
          "400": {
            "description": "Unknown field or invalid value."
          },
          "409": {
            "description": "Stale expectedRevision; re-read and reapply."
          }
        },
        "x-required-capability": "usercaps:write"
      }
    },
    "/v1/me": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "The verified identity behind this key",
        "description": "Who am I: the user/team attribution the gateway binds from the VERIFIED client key (never from headers), plus this key's own metadata. `key` is null for a synthetic principal (the admin playground). Content-free; the token itself is never returned.",
        "operationId": "v1_get_me",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The verified identity behind this key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "user",
                    "tenant",
                    "key"
                  ],
                  "properties": {
                    "user": {
                      "type": "string"
                    },
                    "team": {
                      "type": "string"
                    },
                    "tenant": {
                      "type": "string"
                    },
                    "key": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "user",
                            "service"
                          ]
                        },
                        "label": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "monthlyBudgetUsd": {
                          "type": "number"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/v1/me/usage": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "This identity's own consumption",
        "description": "Current-month token total plus the optimizer and hook savings the deployment tracks for this user — the same counters the connect CLI's savings view reads. Counts and dollars only, never content.",
        "operationId": "v1_get_me_usage",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "This identity's own consumption",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "period",
                    "totalTokens",
                    "savings",
                    "hook"
                  ],
                  "properties": {
                    "period": {
                      "type": "string",
                      "description": "UTC month key, e.g. `2026-08`."
                    },
                    "totalTokens": {
                      "type": "integer"
                    },
                    "savings": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "hook": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/v1/me/limits": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "The ceilings that would 402 this identity",
        "description": "The monthly token cap, USD budget, and service-key budget that apply to this identity, each with what is used against it — so a script can slow down before the terminal 402 instead of discovering the limit by hitting it. A null section means no such ceiling is configured; `spentUsd: null` means the counter store was briefly unreadable (unknown, not zero).",
        "operationId": "v1_get_me_limits",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "AnyrayApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The ceilings that would 402 this identity",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "monthlyTokens",
                    "budgetUsd",
                    "serviceKeyBudget"
                  ],
                  "properties": {
                    "monthlyTokens": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "cap": {
                          "type": "integer"
                        },
                        "used": {
                          "type": "integer"
                        },
                        "period": {
                          "type": "string"
                        }
                      }
                    },
                    "budgetUsd": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "maxUsd": {
                          "type": "number"
                        },
                        "softUsd": {
                          "type": "number"
                        },
                        "spentUsd": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "period": {
                          "type": "string"
                        }
                      }
                    },
                    "serviceKeyBudget": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "monthlyBudgetUsd": {
                          "type": "number"
                        },
                        "spentUsd": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "description": "Spend this period against the counter enforcement reads; null = counter briefly unreadable."
                        },
                        "period": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ClientKeyUnauthorized"
          }
        }
      }
    },
    "/admin/claude-desktop-policy/connectors/probe": {
      "post": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Probe a remote MCP server before adding it as a connector",
        "description": "Ask an MCP endpoint for its own name and tool list, so a connector can be added from its URL alone. HTTPS only, SSRF-guarded, and never persisted; requires `desktopconfig:write` and the deployment owner.",
        "operationId": "adminProbeClaudeDesktopConnector",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The server's HTTPS MCP endpoint."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "What the server answered, including the states in which it cannot be reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpProbeResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON body"
          }
        },
        "x-required-capability": "desktopconfig:write"
      }
    },
    "/admin/claude-desktop-policy/connectors/sync": {
      "post": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Run the organization MCP hub connector mirror now",
        "description": "Wait for one connector-mirror round, then return its content-free status, counts, and recent timing summary. Tool arguments, results, connector credentials, OAuth tokens, upstream bodies, and raw errors are never returned. Requires `desktopconfig:write` and the deployment owner.",
        "operationId": "adminSyncClaudeDesktopConnectors",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The hub summary after the requested round finishes or a newer queued round starts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpHubSyncResponse"
                }
              }
            }
          },
          "409": {
            "description": "The organization MCP hub is not configured."
          }
        },
        "x-required-capability": "desktopconfig:write"
      }
    },
    "/admin/claude-desktop-policy/connectors/authorize": {
      "post": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Start a personal OAuth flow for an MCP connector",
        "description": "Start the vendor authorization flow for an OAuth connector. The returned URL contains no token. After consent, the callback returns a short claim code; a personal gateway grant is created only when a verified client-key user redeems that code, and belongs to that user. Requires `desktopconfig:write` and the deployment owner.",
        "operationId": "adminAuthorizeClaudeDesktopConnector",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160,
                    "description": "The saved connector name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The HTTPS vendor authorization URL; it contains no connector token.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "authorizationUrl"
                  ],
                  "properties": {
                    "authorizationUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON body or connector name"
          },
          "409": {
            "description": "Connector is not ready for OAuth authorization"
          },
          "502": {
            "description": "Could not start connector authorization"
          },
          "503": {
            "description": "OAuth connector authorization unavailable"
          }
        },
        "x-required-capability": "desktopconfig:write"
      }
    },
    "/admin/claude-desktop-policy/connectors/revoke": {
      "post": {
        "tags": [
          "Admin · Privacy, support & observability"
        ],
        "summary": "Remove the hub-held OAuth grant for an MCP connector",
        "description": "Remove the encrypted OAuth grant stored by the org MCP hub, then return the connector to authorization-required. The pinned hub has no vendor-side revocation endpoint, so this does not claim to revoke a provider session. Requires `desktopconfig:write` and the deployment owner.",
        "operationId": "adminRevokeClaudeDesktopConnector",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160,
                    "description": "The saved connector name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The hub-held grant was removed; the provider session may remain active.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "state",
                    "outcome"
                  ],
                  "properties": {
                    "state": {
                      "type": "string",
                      "enum": [
                        "needs-auth"
                      ]
                    },
                    "outcome": {
                      "type": "string",
                      "enum": [
                        "hub-grant-removed"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON body or connector name"
          },
          "409": {
            "description": "Connector does not have a revocable OAuth grant"
          },
          "502": {
            "description": "Could not remove the hub-held connector grant"
          },
          "503": {
            "description": "Organization MCP hub unavailable"
          }
        },
        "x-required-capability": "desktopconfig:write"
      }
    },
    "/admin/v1/me": {
      "get": {
        "tags": [
          "Management API v1 · Me"
        ],
        "summary": "Who am I: principal, role, and effective scopes",
        "description": "Native management API operation.\n\nAuthentication only — any admin principal, including a scoped key.",
        "operationId": "v1_get_me",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The authenticated principal and every scope it holds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sub",
                    "role",
                    "kind",
                    "deploymentOwner",
                    "scopes"
                  ],
                  "properties": {
                    "sub": {
                      "type": "string"
                    },
                    "role": {
                      "type": "string",
                      "enum": [
                        "viewer",
                        "auditor",
                        "operator",
                        "security_admin",
                        "owner"
                      ]
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "token",
                        "local",
                        "sso",
                        "apikey"
                      ]
                    },
                    "tenantId": {
                      "type": "string"
                    },
                    "deploymentOwner": {
                      "type": "boolean",
                      "description": "Whether this principal may touch `x-scope: deployment` resources."
                    },
                    "scopes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Answered by the real route gate, so an operation not covered here is one v1 refuses."
                    },
                    "capabilities": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "The same grant in the legacy capability vocabulary (what /admin/me reports)."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": null,
        "x-scope": "tenant",
        "x-legacy-operation": null,
        "x-api-status": "stable"
      }
    },
    "/admin/v1/keys": {
      "get": {
        "tags": [
          "Management API v1 · Keys"
        ],
        "summary": "List client keys (`?type=service` for service keys only)",
        "description": "Minted client keys (enrolled users). Requires the `config:read` capability.\n\nDerived from `GET /admin/client-keys` (dispatches to it and its siblings; see the summary).\n\nRequires the `keys:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_keys",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "service"
              ]
            },
            "description": "`service` returns only non-human `ark_svc_` keys; omitted returns every key."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "keys:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/client-keys",
        "x-api-status": "stable"
      },
      "post": {
        "tags": [
          "Management API v1 · Keys"
        ],
        "summary": "Mint a client key (`type: \"service\"` for a non-human service key)",
        "description": "Mint a client key for an enrolled user. Requires the `clientkeys:manage` capability.\n\nDerived from `POST /admin/client-keys` (dispatches to it and its siblings; see the summary).\n\nRequires the `keys:write` scope (`tenant`-level resource).",
        "operationId": "v1_post_keys",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "keys:write",
        "x-scope": "tenant",
        "x-legacy-operation": "POST /admin/client-keys",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/keys/{id}": {
      "get": {
        "tags": [
          "Management API v1 · Keys"
        ],
        "summary": "One key record (metadata; never the token)",
        "description": "Native management API operation.\n\nRequires the `keys:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_keys_id",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The key record: metadata only, never the token or its hash.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "keys:read",
        "x-scope": "tenant",
        "x-legacy-operation": null,
        "x-api-status": "stable"
      },
      "patch": {
        "tags": [
          "Management API v1 · Keys"
        ],
        "summary": "Edit a key's label, expiry, service-key budget, delegated attribution, or agent routing binding (null clears a field)",
        "description": "Native management API operation.\n\nRequires the `keys:write` scope (`tenant`-level resource).",
        "operationId": "v1_patch_keys_id",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "label": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 80
                  },
                  "expiresAt": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  },
                  "monthlyBudgetUsd": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0,
                    "description": "Service keys only; a human key's budget lives on the user (`/admin/v1/users`)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The key record: metadata only, never the token or its hash.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "keys:write",
        "x-scope": "tenant",
        "x-legacy-operation": null,
        "x-api-status": "stable"
      },
      "delete": {
        "tags": [
          "Management API v1 · Keys"
        ],
        "summary": "Revoke a client key",
        "description": "Revoke a minted client key. Requires the `clientkeys:manage` capability.\n\nTwin of `DELETE /admin/client-keys/:id`: the same handler, so the response body is identical.\n\nRequires the `keys:write` scope (`tenant`-level resource).",
        "operationId": "v1_delete_keys_id",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "keys:write",
        "x-scope": "tenant",
        "x-legacy-operation": "DELETE /admin/client-keys/:id",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/keys/{id}/rotate": {
      "post": {
        "tags": [
          "Management API v1 · Keys"
        ],
        "summary": "Rotate the key's credential; the new token is returned exactly once",
        "description": "Native management API operation.\n\nRequires the `keys:write` scope (`tenant`-level resource).",
        "operationId": "v1_post_keys_id_rotate",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The fresh raw token (`key`, shown exactly once — only its hash is stored) plus the updated record.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "key",
                    "record"
                  ],
                  "properties": {
                    "key": {
                      "type": "string"
                    },
                    "record": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "keys:write",
        "x-scope": "tenant",
        "x-legacy-operation": null,
        "x-api-status": "stable"
      }
    },
    "/admin/v1/admin-keys": {
      "get": {
        "tags": [
          "Management API v1 · Admin keys"
        ],
        "summary": "List scoped admin API keys",
        "description": "List `aak_…` admin API keys as metadata only. Raw tokens and hashes are never returned. Requires the `config:read` capability and the deployment owner.\n\nTwin of `GET /admin/api-keys`: the same handler, so the response body is identical.\n\nRequires the `admin-keys:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_admin_keys",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Admin API key roster",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminApiKeyListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "admin-keys:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/api-keys",
        "x-api-status": "stable"
      },
      "post": {
        "tags": [
          "Management API v1 · Admin keys"
        ],
        "summary": "Mint a scoped admin API key",
        "description": "Mint an `aak_…` automation credential with exactly one grant shape: a subset of the admin capabilities or native Management API v1 scopes. The grant must be held by the minter and exclude the un-scopeable set; a key can never mint keys. Scope-minted keys are v1-only and cannot call legacy `/admin/*` capability-gated routes. The raw token is returned exactly once. Requires the `adminkeys:manage` capability and the deployment owner.\n\nTwin of `POST /admin/api-keys`: the same handler, so the response body is identical.\n\nRequires the `admin-keys:write` scope (`deployment`-level resource).",
        "operationId": "v1_post_admin_keys",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminApiKeyCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key minted; save the raw key now because it cannot be recovered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminApiKeyMintResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "admin-keys:write",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/api-keys",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/admin-keys/{id}": {
      "delete": {
        "tags": [
          "Management API v1 · Admin keys"
        ],
        "summary": "Revoke a scoped admin API key",
        "description": "Revoke the key (idempotent; it stays listed, marked revoked, and stops working on the next request on every replica). A key can never revoke keys. Requires the `adminkeys:manage` capability and the deployment owner.\n\nTwin of `DELETE /admin/api-keys/:id`: the same handler, so the response body is identical.\n\nRequires the `admin-keys:write` scope (`deployment`-level resource).",
        "operationId": "v1_delete_admin_keys_id",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "404": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "admin-keys:write",
        "x-scope": "deployment",
        "x-legacy-operation": "DELETE /admin/api-keys/:id",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/users/limits": {
      "get": {
        "tags": [
          "Management API v1 · Users"
        ],
        "summary": "Get per-user caps + monthly usage",
        "description": "Caps, the org-wide cap-alert posture (webhook URL never returned — only whether configured), and current-month tokens per user.\n\nTwin of `GET /admin/user-caps`: the same handler, so the response body is identical.\n\nRequires the `users:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_users_limits",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserCapsGet"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "users:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/user-caps",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Users"
        ],
        "summary": "Set per-user caps + alert settings",
        "description": "Replace the caps map and (optionally) the cap-alert settings. Requires the `usercaps:write` capability. Webhook URL merge: absent=keep, null=clear, string=set.\n\nTwin of `PUT /admin/user-caps`: the same handler, so the response body is identical.\n\nRequires the `users:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_users_limits",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserCapsPut"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserCapsGet"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "users:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/user-caps",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/users/revoked": {
      "get": {
        "tags": [
          "Management API v1 · Users"
        ],
        "summary": "List revoked developers",
        "description": "The tenant's SSO developer-revocation set (offboarded emails and when each was revoked). Requires the `config:read` capability.\n\nTwin of `GET /admin/revoked-users`: the same handler, so the response body is identical.\n\nRequires the `users:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_users_revoked",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "users:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/revoked-users",
        "x-api-status": "stable"
      },
      "post": {
        "tags": [
          "Management API v1 · Users"
        ],
        "summary": "Revoke a developer",
        "description": "Offboard an SSO developer by email so the gateway refuses to re-mint their key (within one lease heartbeat). This is the offboarding path for orgs without WorkOS Directory Sync. Requires the `idp:manage` capability.\n\nTwin of `POST /admin/revoked-users`: the same handler, so the response body is identical.\n\nRequires the `users:revoke` scope (`deployment`-level resource).",
        "operationId": "v1_post_users_revoked",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "users:revoke",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/revoked-users",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/users/revoked/{email}": {
      "delete": {
        "tags": [
          "Management API v1 · Users"
        ],
        "summary": "Reinstate a developer",
        "description": "Undo a revocation (IdP re-activation) for the given developer email. Requires the `idp:manage` capability.\n\nTwin of `DELETE /admin/revoked-users/:email`: the same handler, so the response body is identical.\n\nRequires the `users:revoke` scope (`deployment`-level resource).",
        "operationId": "v1_delete_users_revoked_email",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "parameters": [
          {
            "name": "email",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "users:revoke",
        "x-scope": "deployment",
        "x-legacy-operation": "DELETE /admin/revoked-users/:email",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/users/{user}/limits": {
      "patch": {
        "tags": [
          "Management API v1 · Users"
        ],
        "summary": "Patch one user's caps/budget",
        "description": "Merge a partial edit into a single user's cap entry (omit = keep, null = clear; clearing every field removes the entry). The automation lane for scoped admin API keys: a budget bot needs only `config:read` + `usercaps:write`. Never touches alert settings. Requires the `usercaps:write` capability.\n\nTwin of `PATCH /admin/user-caps/:user`: the same handler, so the response body is identical.\n\nRequires the `users:write` scope (`deployment`-level resource).",
        "operationId": "v1_patch_users_user_limits",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[\\w.@+:-]{1,128}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserCapPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK; same shape as GET /admin/user-caps.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserCapsGet"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "users:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PATCH /admin/user-caps/:user",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/users/{user}/export": {
      "get": {
        "tags": [
          "Management API v1 · Users"
        ],
        "summary": "Export a user's records",
        "description": "Export a user's content-free spend, connector-observation, and client-key records (GDPR). Deployment-owner requests include deployment-global connector observations; tenant-scoped SSO requests return an empty `connectorRecords` array. Requires the `gdpr:manage` capability.\n\nTwin of `GET /admin/gdpr/users/:user/export`: the same handler, so the response body is identical.\n\nRequires the `users:gdpr` scope (`tenant`-level resource).",
        "operationId": "v1_get_users_user_export",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "description": "Attributed user id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "user",
                    "generatedAt",
                    "spendRecords",
                    "connectorRecords",
                    "clientKeys"
                  ],
                  "properties": {
                    "user": {
                      "type": "string"
                    },
                    "generatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "spendRecords": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "connectorRecords": {
                      "type": "array",
                      "description": "Content-free vendor connector observations. Empty for tenant-scoped SSO requests.",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "clientKeys": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "users:gdpr",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/gdpr/users/:user/export",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/users/{user}/data": {
      "delete": {
        "tags": [
          "Management API v1 · Users"
        ],
        "summary": "Erase a user's records",
        "description": "Erase a user's spend, client-key, trace, and eligible connector-observation records (GDPR). Only deployment-owner requests erase deployment-global connector observations; tenant-scoped SSO requests report `erasedConnectorRecords: 0`. Requires the `gdpr:manage` capability.\n\nTwin of `DELETE /admin/gdpr/users/:user`: the same handler, so the response body is identical.\n\nRequires the `users:gdpr` scope (`tenant`-level resource).",
        "operationId": "v1_delete_users_user_data",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "description": "Attributed user id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "user",
                    "erasedSpendRecords",
                    "erasedConnectorRecords",
                    "erasedClientKeys",
                    "erasedTraces"
                  ],
                  "properties": {
                    "user": {
                      "type": "string"
                    },
                    "erasedSpendRecords": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "erasedConnectorRecords": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Always 0 for tenant-scoped SSO requests."
                    },
                    "erasedClientKeys": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "erasedTraces": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "users:gdpr",
        "x-scope": "tenant",
        "x-legacy-operation": "DELETE /admin/gdpr/users/:user",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/spend/summary": {
      "get": {
        "tags": [
          "Management API v1 · Spend"
        ],
        "summary": "Spend summary (byUser)",
        "description": "In-memory content-free summary: requests + tokens per attributed user.\n\nTwin of `GET /admin/spend`: the same handler, so the response body is identical.\n\nRequires the `spend:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_spend_summary",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "spend:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/spend",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/spend/dashboard": {
      "get": {
        "tags": [
          "Management API v1 · Spend"
        ],
        "summary": "Windowed spend dashboard",
        "description": "Money/usage split by billing class, per-day trend, top token-saving strategies, latency, and prompt-cache economics. Content-free.\n\nTwin of `GET /admin/spend/dashboard`: the same handler, so the response body is identical.\n\nRequires the `spend:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_spend_dashboard",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "mtd",
                "prev-month",
                "24h",
                "7d",
                "30d",
                "90d"
              ],
              "default": "mtd"
            },
            "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "spend:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/spend/dashboard",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/spend/usage": {
      "get": {
        "tags": [
          "Management API v1 · Spend"
        ],
        "summary": "Per-user usage detail",
        "description": "Per-user usage over a window with per-model and per-UTC-day breakdowns, each capped user's gauge, and an org-wide per-model rollup. Content-free.\n\nTwin of `GET /admin/spend/usage`: the same handler, so the response body is identical.\n\nRequires the `spend:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_spend_usage",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "mtd",
                "prev-month",
                "24h",
                "7d",
                "30d",
                "90d"
              ],
              "default": "mtd"
            },
            "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2000,
              "default": 200
            },
            "description": "Max users returned, heaviest first. `truncated` in the response flags when users were dropped."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendUsage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "spend:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/spend/usage",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/spend/usage/properties": {
      "get": {
        "tags": [
          "Management API v1 · Spend"
        ],
        "summary": "Spend grouped by a custom attribution dimension",
        "description": "Groups content-free spend over a window by one caller-supplied custom attribution dimension (sent as an `x-anyray-property-<name>` request header, stored under `attribution.properties`). Returns per-value request, token, and cost totals. Content-free: attribution ids, counts, and USD only.\n\nTwin of `GET /admin/spend/usage/properties`: the same handler, so the response body is identical.\n\nRequires the `spend:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_spend_usage_properties",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$"
            },
            "description": "The custom dimension name to group by (e.g. `feature`). Must match the bounded attribution-property charset."
          },
          {
            "name": "window",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "mtd",
                "prev-month",
                "24h",
                "7d",
                "30d",
                "90d"
              ],
              "default": "mtd"
            },
            "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "property": {
                      "type": "string"
                    },
                    "window": {
                      "type": "string"
                    },
                    "from": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "to": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "values": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string"
                          },
                          "requests": {
                            "type": "number"
                          },
                          "totalTokens": {
                            "type": "number"
                          },
                          "costUsd": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "spend:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/spend/usage/properties",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/spend/quality-parity": {
      "get": {
        "tags": [
          "Management API v1 · Spend"
        ],
        "summary": "Holdout quality and gross-cost objective",
        "description": "Quality proxies and measured list-price provider cost per observed session in the selected window compared holdout vs treated, with 95% CIs and proof status for the quality-gated 30% gross-cost reduction objective.\n\nTwin of `GET /admin/spend/quality-parity`: the same handler, so the response body is identical.\n\nRequires the `spend:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_spend_quality_parity",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "mtd",
                "prev-month",
                "24h",
                "7d",
                "30d",
                "90d"
              ],
              "default": "mtd"
            },
            "description": "Reporting window. `mtd` = current UTC calendar-month billing period (default)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "spend:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/spend/quality-parity",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/spend/external": {
      "get": {
        "tags": [
          "Management API v1 · Spend"
        ],
        "summary": "Read external subscription usage",
        "description": "Aggregates imported, content-free usage while preserving vendor-native units: Cursor token/cost events, Devin ACUs, and GitHub Copilot credits/activity plus real CLI tokens. Copilot's published $0.01-per-credit list value is reported separately and is not an invoice total; ACUs and credits are never fabricated as tokens. Requires `config:read` and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.\n\nTwin of `GET /admin/spend-connectors/usage`: the same handler, so the response body is identical.\n\nRequires the `spend:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_spend_external",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90,
              "default": 30
            },
            "description": "Rolling lookback in days. Missing, non-integer, or out-of-range values use 30 days."
          }
        ],
        "responses": {
          "200": {
            "description": "Vendor-native usage totals over the requested window.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendConnectorUsage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "spend:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/spend-connectors/usage",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/providers": {
      "get": {
        "tags": [
          "Management API v1 · Providers"
        ],
        "summary": "List provider keys (returned in full: credential-grade, so write-gated)",
        "description": "Configured providers, including per-provider named-key metadata (`capabilities.keyIds`: id/label/isDefault — key values are returned only in `config`; the metadata itself is content-free). A provider entry is a bare credential or a multi-key set `{ keys: [{id, label?, credential}], defaultKeyId }`. Requires the `providerkeys:manage` capability.\n\nTwin of `GET /admin/provider-keys`: the same handler, so the response body is identical.\n\nRequires the `providers:write` scope (`deployment`-level resource).",
        "operationId": "v1_get_providers",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "providers:write",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/provider-keys",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Providers"
        ],
        "summary": "Set provider keys",
        "description": "Set server-held provider API keys. Accepts a partial patch per slug: a credential (string or field bag) replaces the provider's DEFAULT key; '' clears the whole provider; the per-key form `{ keys: { [id]: credential | {label?, credential} | '' | null }, defaultKeyId? }` adds/replaces/removes named keys and reassigns the default. Named keys are pinned from routing configs via `provider_key_id`. Callers authenticate with a separate, minted Anyray client key and never receive the stored provider secret. Requires the `providerkeys:manage` capability.\n\nTwin of `PUT /admin/provider-keys`: the same handler, so the response body is identical.\n\nRequires the `providers:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_providers",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "providers:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/provider-keys",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/providers/{slug}/key": {
      "put": {
        "tags": [
          "Management API v1 · Providers"
        ],
        "summary": "Set one provider's key entry (merges; other providers untouched)",
        "description": "Set server-held provider API keys. Accepts a partial patch per slug: a credential (string or field bag) replaces the provider's DEFAULT key; '' clears the whole provider; the per-key form `{ keys: { [id]: credential | {label?, credential} | '' | null }, defaultKeyId? }` adds/replaces/removes named keys and reassigns the default. Named keys are pinned from routing configs via `provider_key_id`. Callers authenticate with a separate, minted Anyray client key and never receive the stored provider secret. Requires the `providerkeys:manage` capability.\n\nDerived from `PUT /admin/provider-keys` (dispatches to it and its siblings; see the summary).\n\nRequires the `providers:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_providers_slug_key",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "description": "One provider's key entry, same shape as one value of the whole-map `PUT /admin/provider-keys` body."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "providers:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/provider-keys",
        "x-api-status": "stable"
      },
      "delete": {
        "tags": [
          "Management API v1 · Providers"
        ],
        "summary": "Remove one provider's key entry",
        "description": "Set server-held provider API keys. Accepts a partial patch per slug: a credential (string or field bag) replaces the provider's DEFAULT key; '' clears the whole provider; the per-key form `{ keys: { [id]: credential | {label?, credential} | '' | null }, defaultKeyId? }` adds/replaces/removes named keys and reassigns the default. Named keys are pinned from routing configs via `provider_key_id`. Callers authenticate with a separate, minted Anyray client key and never receive the stored provider secret. Requires the `providerkeys:manage` capability.\n\nDerived from `PUT /admin/provider-keys` (dispatches to it and its siblings; see the summary).\n\nRequires the `providers:write` scope (`deployment`-level resource).",
        "operationId": "v1_delete_providers_slug_key",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "providers:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/provider-keys",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/providers/connectors": {
      "get": {
        "tags": [
          "Management API v1 · Providers"
        ],
        "summary": "Read external spend connectors",
        "description": "Returns redacted configuration and optional poll status for the official Cursor, Devin, and GitHub Copilot usage connectors. Credentials are write-only and never appear in this response. Requires the `config:read` capability and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.\n\nTwin of `GET /admin/spend-connectors`: the same handler, so the response body is identical.\n\nRequires the `providers:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_providers_connectors",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Redacted connector configuration. An unconfigured deployment returns an empty object.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendConnectorsRead"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "providers:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/spend-connectors",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Providers"
        ],
        "summary": "Set external spend connectors",
        "description": "Partially configure, rotate, or remove official vendor usage connectors. Omitted connectors stay unchanged; a connector object replaces that connector; `null` or `{}` removes it. Credential fields are write-only, encrypted at rest, never returned, and never audit-logged. Requires `providerkeys:manage` and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.\n\nTwin of `PUT /admin/spend-connectors`: the same handler, so the response body is identical.\n\nRequires the `providers:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_providers_connectors",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpendConnectorsPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The resulting redacted connector configuration. Credential values are never echoed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendConnectorsRead"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "providers:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/spend-connectors",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/providers/connectors/sync": {
      "post": {
        "tags": [
          "Management API v1 · Providers"
        ],
        "summary": "Synchronize external spend connectors",
        "description": "Requests a fleet-safe sync of every configured vendor connector. A durable lease prevents duplicate polling across replicas. Per-connector failures are isolated and represented only as `failed: true`; vendor bodies, signed report URLs, and credential-bearing errors are never returned. Requires `providerkeys:manage` and deployment-owner access; in fleet mode, tenant-bound SSO principals are rejected.\n\nTwin of `POST /admin/spend-connectors/sync`: the same handler, so the response body is identical.\n\nRequires the `providers:write` scope (`deployment`-level resource).",
        "operationId": "v1_post_providers_connectors_sync",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Safe, content-free result for each configured connector.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendConnectorSyncResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "502": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "providers:write",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/spend-connectors/sync",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/routing": {
      "get": {
        "tags": [
          "Management API v1 · Routing"
        ],
        "summary": "Read routing config",
        "description": "Routing strategy (single / loadbalance / fallback / conditional) and targets. Requires the `config:read` capability.\n\nTwin of `GET /admin/routing-config`: the same handler, so the response body is identical.\n\nRequires the `routing:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_routing",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "routing:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/routing-config",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Routing"
        ],
        "summary": "Update routing config",
        "description": "Update routing strategy and targets. See the Configure docs for the body shape. Requires the `routing:write` capability.\n\nTwin of `PUT /admin/routing-config`: the same handler, so the response body is identical.\n\nRequires the `routing:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_routing",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "routing:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/routing-config",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/routing/aliases": {
      "get": {
        "tags": [
          "Management API v1 · Routing"
        ],
        "summary": "Read model aliases",
        "description": "Model-alias → target mappings. Requires the `config:read` capability.\n\nTwin of `GET /admin/model-aliases`: the same handler, so the response body is identical.\n\nRequires the `routing:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_routing_aliases",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "routing:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/model-aliases",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Routing"
        ],
        "summary": "Update model aliases",
        "description": "Replace model-alias mappings. Requires the `modelaliases:write` capability.\n\nTwin of `PUT /admin/model-aliases`: the same handler, so the response body is identical.\n\nRequires the `routing:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_routing_aliases",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "routing:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/model-aliases",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/routing/models": {
      "get": {
        "tags": [
          "Management API v1 · Routing"
        ],
        "summary": "Official price table",
        "description": "The read-only official model price table. Requires the `config:read` capability.\n\nTwin of `GET /admin/pricing`: the same handler, so the response body is identical.\n\nRequires the `routing:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_routing_models",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "routing:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/pricing",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/optimizer": {
      "get": {
        "tags": [
          "Management API v1 · Optimizer"
        ],
        "summary": "Read optimizer config",
        "description": "The optimizer pipeline configuration (strategies + params). Requires the `config:read` capability.\n\nTwin of `GET /admin/optimizer/settings`: the same handler, so the response body is identical.\n\nRequires the `optimizer:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_optimizer",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "optimizer:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/optimizer/settings",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Optimizer"
        ],
        "summary": "Update optimizer config",
        "description": "Update the optimizer pipeline configuration. Requires the `optimizer:write` capability.\n\nTwin of `PUT /admin/optimizer/settings`: the same handler, so the response body is identical.\n\nRequires the `optimizer:write` scope (`tenant`-level resource).",
        "operationId": "v1_put_optimizer",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "optimizer:write",
        "x-scope": "tenant",
        "x-legacy-operation": "PUT /admin/optimizer/settings",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/optimizer/purge": {
      "post": {
        "tags": [
          "Management API v1 · Optimizer"
        ],
        "summary": "Purge optimizer state",
        "description": "Purge optimizer caches / session state. Requires the `optimizer:purge` capability.\n\nTwin of `POST /admin/optimizer/purge`: the same handler, so the response body is identical.\n\nRequires the `optimizer:write` scope (`tenant`-level resource).",
        "operationId": "v1_post_optimizer_purge",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "optimizer:write",
        "x-scope": "tenant",
        "x-legacy-operation": "POST /admin/optimizer/purge",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/policies/teams": {
      "get": {
        "tags": [
          "Management API v1 · Policies"
        ],
        "summary": "Read team skills",
        "description": "The stored team policy: shared skills, the fleet tool set (`tools.enabled` + per-tool `tools.tiers`), and the Connect update posture (`updates.mode`: `auto` | `directed` | `off`; `auto` is stored as absent). When no tool policy has ever been saved, `tools` is absent and a read-only `toolsDefault` lists what the deployment enrols instead; neither is returned when the policy store could not be read. Requires the `config:read` capability.\n\nTwin of `GET /admin/team-skills`: the same handler, so the response body is identical.\n\nRequires the `policies:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_policies_teams",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "policies:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/team-skills",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Policies"
        ],
        "summary": "Update team skills",
        "description": "Replace the team policy (skills use replace semantics; a legacy skills-only write preserves the stored `tools`, `lanes` and `updates` fields, including per-tool tiers). `updates.mode` sets the fleet Connect update posture: `auto` (machines self-update), `directed` (nothing downloads unattended; an admin queues each update), `off` (no binary is fetched at all). Requires the `teamskills:write` capability.\n\nTwin of `PUT /admin/team-skills`: the same handler, so the response body is identical.\n\nRequires the `policies:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_policies_teams",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "policies:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/team-skills",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/policies/claude-desktop": {
      "get": {
        "tags": [
          "Management API v1 · Policies"
        ],
        "summary": "Read Claude Desktop organization policy",
        "description": "Read the secret-free managed policy and resolved deployment fields. Requires `config:read` and the deployment owner.\n\nTwin of `GET /admin/claude-desktop-policy`: the same handler, so the response body is identical.\n\nRequires the `policies:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_policies_claude_desktop",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current policy and deployment metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaudeDesktopPolicyResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "policies:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/claude-desktop-policy",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Policies"
        ],
        "summary": "Replace Claude Desktop organization policy",
        "description": "Replace the secret-free managed policy. Rejects credential-shaped string values at every depth, server-owned inference/bootstrap fields, unknown keys, and documents over 128 KiB. Available in headless deployments; requires `desktopconfig:write` and the deployment owner.\n\nTwin of `PUT /admin/claude-desktop-policy`: the same handler, so the response body is identical.\n\nRequires the `policies:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_policies_claude_desktop",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClaudeDesktopPolicyInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved policy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaudeDesktopPolicyResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "policies:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/claude-desktop-policy",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/policies/claude-desktop/mobileconfig": {
      "get": {
        "tags": [
          "Management API v1 · Policies"
        ],
        "summary": "Download Claude Desktop MDM trust profile",
        "description": "Download a stable, credential-free macOS profile carrying the bootstrap URL and MDM-only helper path. Requires `config:read` and the deployment owner.\n\nTwin of `GET /admin/claude-desktop-policy/mobileconfig`: the same handler, so the response body is identical.\n\nRequires the `policies:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_policies_claude_desktop_mobileconfig",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Apple configuration profile",
            "content": {
              "application/x-apple-aspen-config": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "policies:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/claude-desktop-policy/mobileconfig",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/policies/claude-desktop/connectors/probe": {
      "post": {
        "tags": [
          "Management API v1 · Policies"
        ],
        "summary": "Ask a remote MCP server for its name and tools before adding it as a connector",
        "description": "Ask an MCP endpoint for its own name and tool list, so a connector can be added from its URL alone. HTTPS only, SSRF-guarded, and never persisted; requires `desktopconfig:write` and the deployment owner.\n\nTwin of `POST /admin/claude-desktop-policy/connectors/probe`: the same handler, so the response body is identical.\n\nRequires the `policies:write` scope (`deployment`-level resource).",
        "operationId": "v1_post_policies_claude_desktop_connectors_probe",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The server's HTTPS MCP endpoint."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "What the server answered, including the states in which it cannot be reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpProbeResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "policies:write",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/claude-desktop-policy/connectors/probe",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/policies/claude-desktop/connectors/sync": {
      "post": {
        "tags": [
          "Management API v1 · Policies"
        ],
        "summary": "Run the organization MCP hub connector mirror now",
        "description": "Wait for one connector-mirror round, then return its content-free status, counts, and recent timing summary. Tool arguments, results, connector credentials, OAuth tokens, upstream bodies, and raw errors are never returned. Requires `desktopconfig:write` and the deployment owner.\n\nTwin of `POST /admin/claude-desktop-policy/connectors/sync`: the same handler, so the response body is identical.\n\nRequires the `policies:write` scope (`deployment`-level resource).",
        "operationId": "v1_post_policies_claude_desktop_connectors_sync",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The hub summary after the requested round finishes or a newer queued round starts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpHubSyncResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "policies:write",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/claude-desktop-policy/connectors/sync",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/policies/claude-desktop/connectors/authorize": {
      "post": {
        "tags": [
          "Management API v1 · Policies"
        ],
        "summary": "Start a personal OAuth grant for the verified admin on an MCP connector",
        "description": "Start the vendor authorization flow for an OAuth connector. The returned URL contains no token. After consent, the callback returns a short claim code; a personal gateway grant is created only when a verified client-key user redeems that code, and belongs to that user. Requires `desktopconfig:write` and the deployment owner.\n\nTwin of `POST /admin/claude-desktop-policy/connectors/authorize`: the same handler, so the response body is identical.\n\nRequires the `policies:write` scope (`deployment`-level resource).",
        "operationId": "v1_post_policies_claude_desktop_connectors_authorize",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160,
                    "description": "The saved connector name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The HTTPS vendor authorization URL; it contains no connector token.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "authorizationUrl"
                  ],
                  "properties": {
                    "authorizationUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "502": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "policies:write",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/claude-desktop-policy/connectors/authorize",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/policies/claude-desktop/connectors/revoke": {
      "post": {
        "tags": [
          "Management API v1 · Policies"
        ],
        "summary": "Drop the hub-held OAuth grant for an MCP connector",
        "description": "Remove the encrypted OAuth grant stored by the org MCP hub, then return the connector to authorization-required. The pinned hub has no vendor-side revocation endpoint, so this does not claim to revoke a provider session. Requires `desktopconfig:write` and the deployment owner.\n\nTwin of `POST /admin/claude-desktop-policy/connectors/revoke`: the same handler, so the response body is identical.\n\nRequires the `policies:write` scope (`deployment`-level resource).",
        "operationId": "v1_post_policies_claude_desktop_connectors_revoke",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160,
                    "description": "The saved connector name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The hub-held grant was removed; the provider session may remain active.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "state",
                    "outcome"
                  ],
                  "properties": {
                    "state": {
                      "type": "string",
                      "enum": [
                        "needs-auth"
                      ]
                    },
                    "outcome": {
                      "type": "string",
                      "enum": [
                        "hub-grant-removed"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "502": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "policies:write",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/claude-desktop-policy/connectors/revoke",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/desktop-plugins": {
      "get": {
        "tags": [
          "Management API v1 · Desktop plugins"
        ],
        "summary": "List organization Skills and Guidance",
        "description": "List the Skills and Guidance distributed to managed Claude Desktop clients. Requires `config:read` and the deployment owner.\n\nTwin of `GET /admin/claude-desktop-plugins`: the same handler, so the response body is identical.\n\nRequires the `desktop-plugins:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_desktop_plugins",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current Skills and Guidance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "items"
                  ],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ClaudeDesktopOrgSkill"
                      }
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "desktop-plugins:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/claude-desktop-plugins",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Desktop plugins"
        ],
        "summary": "Create or update an organization Skill or Guidance item",
        "description": "Save one credential-free Skill or Guidance item. Each item is limited to 256 KiB of file content and the organization total is limited to 2 MiB. Requires `desktopconfig:write` and the deployment owner.\n\nTwin of `PUT /admin/claude-desktop-plugins`: the same handler, so the response body is identical.\n\nRequires the `desktop-plugins:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_desktop_plugins",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClaudeDesktopOrgSkillInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved Skill or Guidance item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "item"
                  ],
                  "properties": {
                    "item": {
                      "$ref": "#/components/schemas/ClaudeDesktopOrgSkill"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "413": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "desktop-plugins:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/claude-desktop-plugins",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/desktop-plugins/{id}": {
      "delete": {
        "tags": [
          "Management API v1 · Desktop plugins"
        ],
        "summary": "Remove an organization Skill or Guidance item",
        "description": "Remove one Skill or Guidance item by id. Requires `desktopconfig:write` and the deployment owner.\n\nTwin of `DELETE /admin/claude-desktop-plugins/:id`: the same handler, so the response body is identical.\n\nRequires the `desktop-plugins:write` scope (`deployment`-level resource).",
        "operationId": "v1_delete_desktop_plugins_id",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removal result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "deleted"
                  ],
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "desktop-plugins:write",
        "x-scope": "deployment",
        "x-legacy-operation": "DELETE /admin/claude-desktop-plugins/:id",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/settings": {
      "get": {
        "tags": [
          "Management API v1 · Settings"
        ],
        "summary": "Read runtime settings",
        "description": "Content mode, feature flags, and other runtime-mutable settings. Requires the `config:read` capability.\n\nTwin of `GET /admin/settings`: the same handler, so the response body is identical.\n\nRequires the `settings:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_settings",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "settings:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/settings",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Settings"
        ],
        "summary": "Update runtime settings (content-capture fields additionally require `settings:content`)",
        "description": "Update runtime-mutable settings. Requires the `content:manage` capability.\n\nDerived from `PUT /admin/settings` (dispatches to it and its siblings; see the summary).\n\nRequires the `settings:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_settings",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "settings:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/settings",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/settings/content": {
      "put": {
        "tags": [
          "Management API v1 · Settings"
        ],
        "summary": "Update the content-capture posture (content mode, trace retention)",
        "description": "Update runtime-mutable settings. Requires the `content:manage` capability.\n\nDerived from `PUT /admin/settings` (dispatches to it and its siblings; see the summary).\n\nRequires the `settings:content` scope (`deployment`-level resource).",
        "operationId": "v1_put_settings_content",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "settings:content",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/settings",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/settings/identity": {
      "put": {
        "tags": [
          "Management API v1 · Settings"
        ],
        "summary": "Set how /v1/* establishes who is calling: `enrolled` requires a minted client key, `network-trusted` lifts that for a network-isolated single-tenant deployment (RFC 0020)",
        "description": "Switch how `/v1/*` establishes who is calling (RFC 0019). `enrolled` (the default) requires every request to present a minted client key. `network-trusted` lifts that requirement for a network-isolated deployment, taking the developer's identity from the request instead — which turns off SCIM offboarding enforcement and leaves the server-held provider keys reachable by anything on that network. A presented key is still verified and still binds an authoritative identity in both modes, and only the ABSENCE of a key is forgiven — an expired, revoked, or deactivated key still returns 401. The relaxation covers INFERENCE paths only, never content retrieval (`/v1/files/{id}/content`, `/v1/batches/*/output`, `/v1/responses/{id}/input_items` stay key-gated in every mode). **Single-tenant self-hosted only:** a fleet deployment (`ANYRAY_MULTI_TENANT=true`) resolves identity through the control plane, which never consults this setting — a key-less `/v1/*` request there still returns `401 missing_key` whatever the mode says. Separate from `PUT /admin/settings` because it requires the distinct `identity:manage` capability.\n\nTwin of `PUT /admin/settings/identity`: the same handler, so the response body is identical.\n\nRequires the `settings:identity` scope (`deployment`-level resource).",
        "operationId": "v1_put_settings_identity",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "identityMode"
                ],
                "properties": {
                  "identityMode": {
                    "type": "string",
                    "enum": [
                      "enrolled",
                      "network-trusted"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "settings:identity",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/settings/identity",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/settings/updates": {
      "get": {
        "tags": [
          "Management API v1 · Settings"
        ],
        "summary": "Self-updater status",
        "description": "Available image tag vs the running version, the locally evaluated release preflight, the computed update class (`soft` = image-only, self-applies on Compose installs when the policy is on; `hard` = operator infra action required, never applied unattended), the `autoSoftUpdates` policy, and the last unattended apply attempt. Requires the `config:read` capability.\n\nTwin of `GET /admin/update-status`: the same handler, so the response body is identical.\n\nRequires the `settings:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_settings_updates",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "preflight": {
                      "type": "object",
                      "required": [
                        "target",
                        "status",
                        "missingEnv",
                        "removedEnvSet",
                        "breaking"
                      ],
                      "properties": {
                        "target": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "pattern": "^v?\\d+\\.\\d+\\.\\d+$"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "blocked",
                            "unknown"
                          ]
                        },
                        "missingEnv": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "name"
                            ],
                            "properties": {
                              "name": {
                                "type": "string",
                                "pattern": "^ANYRAY_[A-Z0-9_]{1,60}$"
                              },
                              "summary": {
                                "type": "string",
                                "maxLength": 200
                              },
                              "composeDefault": {
                                "type": "boolean"
                              }
                            }
                          }
                        },
                        "removedEnvSet": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "pattern": "^ANYRAY_[A-Z0-9_]{1,60}$"
                          }
                        },
                        "breaking": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "maxLength": 300
                          }
                        }
                      }
                    },
                    "updateClass": {
                      "type": "string",
                      "enum": [
                        "soft",
                        "hard",
                        "unknown"
                      ]
                    },
                    "autoSoftUpdates": {
                      "type": "boolean",
                      "description": "Whether soft (image-only) updates apply unattended. Default true."
                    },
                    "autoUpdate": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Last unattended apply attempt (in-memory; resets on gateway restart).",
                      "properties": {
                        "target": {
                          "type": "string"
                        },
                        "at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "result": {
                          "type": "string",
                          "enum": [
                            "triggered",
                            "unreachable",
                            "rejected"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "settings:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/update-status",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Settings"
        ],
        "summary": "Update policy",
        "description": "Set whether soft (image-only, preflight-green) updates apply unattended (Compose installs; other platforms are always notify-only). Default on. Hard updates are never applied unattended regardless of this setting. Requires the `update:run` capability.\n\nTwin of `PUT /admin/update/settings`: the same handler, so the response body is identical.\n\nRequires the `settings:update` scope (`deployment`-level resource).",
        "operationId": "v1_put_settings_updates",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "autoSoftUpdates"
                ],
                "properties": {
                  "autoSoftUpdates": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "autoSoftUpdates": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "settings:update",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/update/settings",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/settings/setup": {
      "get": {
        "tags": [
          "Management API v1 · Settings"
        ],
        "summary": "Onboarding wizard status",
        "description": "Onboarding wizard progress. Requires the `config:read` capability.\n\nTwin of `GET /admin/wizard-status`: the same handler, so the response body is identical.\n\nRequires the `settings:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_settings_setup",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "settings:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/wizard-status",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Settings"
        ],
        "summary": "Confirm wizard step",
        "description": "Confirm an onboarding wizard step. Requires the `wizard:write` capability.\n\nTwin of `PUT /admin/wizard-confirm`: the same handler, so the response body is identical.\n\nRequires the `settings:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_settings_setup",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "settings:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/wizard-confirm",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/settings/health": {
      "get": {
        "tags": [
          "Management API v1 · Settings"
        ],
        "summary": "Health & schema version",
        "description": "Liveness, spend-store ping, and the applied vs expected DB schema version. Requires the `config:read` capability.\n\nTwin of `GET /admin/health`: the same handler, so the response body is identical.\n\nRequires the `settings:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_settings_health",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "settings:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/health",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/settings/support-bundle": {
      "get": {
        "tags": [
          "Management API v1 · Settings"
        ],
        "summary": "Support bundle",
        "description": "Generate a content-free support bundle for remote debugging. Requires the `config:read` capability.\n\nTwin of `GET /admin/support/bundle`: the same handler, so the response body is identical.\n\nRequires the `settings:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_settings_support_bundle",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "settings:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/support/bundle",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/settings/support-bundle/share": {
      "post": {
        "tags": [
          "Management API v1 · Settings"
        ],
        "summary": "Share a support bundle",
        "description": "Generate, redact, and explicitly send a content-free support bundle to the Anyray Billing app. Requires the `content:manage` capability; the send is recorded in the deployment audit log.\n\nTwin of `POST /admin/support/bundle/share`: the same handler, so the response body is identical.\n\nRequires the `settings:content` scope (`deployment`-level resource).",
        "operationId": "v1_post_settings_support_bundle_share",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Bundle accepted; returns the support receipt id and metadata-only manifest summary.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "502": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "settings:content",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/support/bundle/share",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/sso": {
      "get": {
        "tags": [
          "Management API v1 · Sso"
        ],
        "summary": "Read SSO/IdP config",
        "description": "The SSO / IdP configuration. Requires the `config:read` capability.\n\nTwin of `GET /admin/idp-config`: the same handler, so the response body is identical.\n\nRequires the `sso:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_sso",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "sso:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/idp-config",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Sso"
        ],
        "summary": "Configure SSO/IdP",
        "description": "Set the SSO / IdP configuration. Requires the `idp:manage` capability.\n\nTwin of `PUT /admin/idp-config`: the same handler, so the response body is identical.\n\nRequires the `sso:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_sso",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "sso:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/idp-config",
        "x-api-status": "stable"
      },
      "delete": {
        "tags": [
          "Management API v1 · Sso"
        ],
        "summary": "Remove SSO/IdP config",
        "description": "Remove the SSO / IdP configuration. Requires the `idp:manage` capability.\n\nTwin of `DELETE /admin/idp-config`: the same handler, so the response body is identical.\n\nRequires the `sso:write` scope (`deployment`-level resource).",
        "operationId": "v1_delete_sso",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "sso:write",
        "x-scope": "deployment",
        "x-legacy-operation": "DELETE /admin/idp-config",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/sso/scim": {
      "get": {
        "tags": [
          "Management API v1 · Sso"
        ],
        "summary": "Read inbound SCIM settings",
        "description": "Return whether inbound SCIM is configured plus the admin group and group-to-team map. The bearer and its hash are never returned. Requires `config:read` and deployment-owner access.\n\nTwin of `GET /admin/scim/settings`: the same handler, so the response body is identical.\n\nRequires the `sso:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_sso_scim",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Redacted inbound SCIM settings.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "configured",
                    "adminGroup",
                    "groupTeamMap",
                    "updatedAt"
                  ],
                  "properties": {
                    "configured": {
                      "type": "boolean"
                    },
                    "adminGroup": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "groupTeamMap": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "updatedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "sso:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/scim/settings",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Sso"
        ],
        "summary": "Configure inbound SCIM",
        "description": "Set or rotate the static SCIM bearer and update the admin group or group-to-team map. Omit `bearerToken` to preserve an existing credential. Requires `idp:manage` and deployment-owner access.\n\nTwin of `PUT /admin/scim/settings`: the same handler, so the response body is identical.\n\nRequires the `sso:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_sso_scim",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bearerToken": {
                    "type": "string",
                    "minLength": 32,
                    "maxLength": 1024,
                    "writeOnly": true
                  },
                  "adminGroup": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "maxLength": 256
                  },
                  "groupTeamMap": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 256
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The resulting redacted inbound SCIM settings."
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "sso:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/scim/settings",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/sso/portal-link": {
      "post": {
        "tags": [
          "Management API v1 · Sso"
        ],
        "summary": "WorkOS admin-portal link",
        "description": "Mint a WorkOS admin-portal link. Requires the `idp:manage` capability.\n\nTwin of `POST /admin/workos-portal-link`: the same handler, so the response body is identical.\n\nRequires the `sso:write` scope (`deployment`-level resource).",
        "operationId": "v1_post_sso_portal_link",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "sso:write",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/workos-portal-link",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/enrollment/links": {
      "get": {
        "tags": [
          "Management API v1 · Enrollment"
        ],
        "summary": "List enrollment links",
        "description": "Enrollment / setup links. Requires the `config:read` capability.\n\nTwin of `GET /admin/enrollment-links`: the same handler, so the response body is identical.\n\nRequires the `enrollment:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_enrollment_links",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "enrollment:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/enrollment-links",
        "x-api-status": "stable"
      },
      "post": {
        "tags": [
          "Management API v1 · Enrollment"
        ],
        "summary": "Create enrollment link",
        "description": "Create an enrollment / setup link. Requires the `enrollment:manage` capability.\n\nTwin of `POST /admin/enrollment-links`: the same handler, so the response body is identical.\n\nRequires the `enrollment:write` scope (`deployment`-level resource).",
        "operationId": "v1_post_enrollment_links",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "enrollment:write",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/enrollment-links",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/enrollment/links/{id}": {
      "delete": {
        "tags": [
          "Management API v1 · Enrollment"
        ],
        "summary": "Revoke an enrollment link (`?hard=true` to delete the record)",
        "description": "Disable an enrollment link. Requires the `enrollment:manage` capability.\n\nDerived from `DELETE /admin/enrollment-links/:id` (dispatches to it and its siblings; see the summary).\n\nRequires the `enrollment:write` scope (`deployment`-level resource).",
        "operationId": "v1_delete_enrollment_links_id",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          {
            "name": "hard",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "`true` deletes the record; omitted revokes it (the link stops working, the row stays for audit)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "enrollment:write",
        "x-scope": "deployment",
        "x-legacy-operation": "DELETE /admin/enrollment-links/:id",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/provisioning/tokens": {
      "get": {
        "tags": [
          "Management API v1 · Provisioning"
        ],
        "summary": "List provisioning tokens",
        "description": "Deployment provisioning tokens. Requires the `config:read` capability.\n\nTwin of `GET /admin/provisioning-tokens`: the same handler, so the response body is identical.\n\nRequires the `provisioning:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_provisioning_tokens",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "provisioning:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/provisioning-tokens",
        "x-api-status": "stable"
      },
      "post": {
        "tags": [
          "Management API v1 · Provisioning"
        ],
        "summary": "Mint provisioning token",
        "description": "Mint a deployment provisioning token. Requires the `provisioning:manage` capability.\n\nTwin of `POST /admin/provisioning-tokens`: the same handler, so the response body is identical.\n\nRequires the `provisioning:write` scope (`deployment`-level resource).",
        "operationId": "v1_post_provisioning_tokens",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "provisioning:write",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/provisioning-tokens",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/provisioning/tokens/{id}/rotate": {
      "post": {
        "tags": [
          "Management API v1 · Provisioning"
        ],
        "summary": "Rotate provisioning token",
        "description": "Rotate a provisioning token. Requires the `provisioning:manage` capability.\n\nTwin of `POST /admin/provisioning-tokens/:id/rotate`: the same handler, so the response body is identical.\n\nRequires the `provisioning:write` scope (`deployment`-level resource).",
        "operationId": "v1_post_provisioning_tokens_id_rotate",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "provisioning:write",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/provisioning-tokens/:id/rotate",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/provisioning/tokens/{id}": {
      "delete": {
        "tags": [
          "Management API v1 · Provisioning"
        ],
        "summary": "Revoke provisioning token",
        "description": "Revoke a provisioning token. Requires the `provisioning:manage` capability.\n\nTwin of `DELETE /admin/provisioning-tokens/:id`: the same handler, so the response body is identical.\n\nRequires the `provisioning:write` scope (`deployment`-level resource).",
        "operationId": "v1_delete_provisioning_tokens_id",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "provisioning:write",
        "x-scope": "deployment",
        "x-legacy-operation": "DELETE /admin/provisioning-tokens/:id",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/status": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "End-point fleet status summary",
        "description": "Read-only, content-free summary of the org's end-point fleet, cached in-process for 15s. A stored Fleet config takes precedence; otherwise a portal-connected gateway relays through Billing to its tenant-paired endpoint-control org. Never returns credentials, policy queries, or resolutions. An unreachable upstream answers `{configured: true, reachable: false}` rather than an error. Requires the `observability:read` capability.\n\nTwin of `GET /admin/endpoint-fleet/status`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_status",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint-fleet/status",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/org": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "End-point control org summary (host and policy counts)",
        "description": "Twin of `GET /admin/endpoint/org`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_org",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint/org",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/hosts": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "List enrolled end-point hosts (hostname, platform, status, failing-policy count)",
        "description": "Twin of `GET /admin/endpoint/hosts`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_hosts",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint/hosts",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/hosts/{id}": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "End-point host detail with its policy results",
        "description": "Twin of `GET /admin/endpoint/hosts/:id`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_hosts_id",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint/hosts/:id",
        "x-api-status": "stable"
      },
      "delete": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Retire an end-point host record",
        "description": "Twin of `DELETE /admin/endpoint/hosts/:id`: the same handler, so the response body is identical.\n\nRequires the `fleet:remediate` scope (`deployment`-level resource).",
        "operationId": "v1_delete_fleet_hosts_id",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:remediate",
        "x-scope": "deployment",
        "x-legacy-operation": "DELETE /admin/endpoint/hosts/:id",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/hosts/{id}/remediate": {
      "post": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Run an allowlisted remediation script on a host (leased, at-least-once)",
        "description": "Twin of `POST /admin/endpoint/hosts/:id/remediate`: the same handler, so the response body is identical.\n\nRequires the `fleet:remediate` scope (`deployment`-level resource).",
        "operationId": "v1_post_fleet_hosts_id_remediate",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:remediate",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/endpoint/hosts/:id/remediate",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/hosts/{id}/scripts/{executionId}/output": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Read a remediation run's captured output (content; follows the deployment content mode)",
        "description": "Twin of `GET /admin/endpoint/hosts/:id/scripts/:executionId/output`: the same handler, so the response body is identical.\n\nRequires the `fleet:content` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_hosts_id_scripts_executionId_output",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "executionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:content",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint/hosts/:id/scripts/:executionId/output",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/policies": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "List the policy pack with per-policy enablement and pass/fail counts",
        "description": "Twin of `GET /admin/endpoint/policies`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_policies",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint/policies",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/policies/{name}/hosts": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Hosts failing a policy",
        "description": "Twin of `GET /admin/endpoint/policies/:name/hosts`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_policies_name_hosts",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint/policies/:name/hosts",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/policies/{name}": {
      "post": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Enable or disable a policy",
        "description": "Twin of `POST /admin/endpoint/policies/:name`: the same handler, so the response body is identical.\n\nRequires the `fleet:enroll` scope (`deployment`-level resource).",
        "operationId": "v1_post_fleet_policies_name",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:enroll",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/endpoint/policies/:name",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/scripts": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "List the allowlisted remediation scripts",
        "description": "Twin of `GET /admin/endpoint/scripts`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_scripts",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint/scripts",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/policy-push": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Read the pending policy-push state",
        "description": "Twin of `GET /admin/endpoint/policy-push`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_policy_push",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint/policy-push",
        "x-api-status": "stable"
      },
      "post": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Push the enabled policy set to the fleet",
        "description": "Twin of `POST /admin/endpoint/policy-push`: the same handler, so the response body is identical.\n\nRequires the `fleet:remediate` scope (`deployment`-level resource).",
        "operationId": "v1_post_fleet_policy_push",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:remediate",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/endpoint/policy-push",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/enroll-secret": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Read the end-point enroll secret (credential-grade)",
        "description": "Twin of `GET /admin/endpoint/enroll-secret`: the same handler, so the response body is identical.\n\nRequires the `fleet:enroll` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_enroll_secret",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:enroll",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint/enroll-secret",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/enroll-secret/rotate": {
      "post": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Rotate the end-point enroll secret",
        "description": "Twin of `POST /admin/endpoint/enroll-secret/rotate`: the same handler, so the response body is identical.\n\nRequires the `fleet:enroll` scope (`deployment`-level resource).",
        "operationId": "v1_post_fleet_enroll_secret_rotate",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:enroll",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/endpoint/enroll-secret/rotate",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/evidence-connectors": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "List customer-managed evidence connectors (source ids only)",
        "description": "Twin of `GET /admin/endpoint/evidence-connectors`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_evidence_connectors",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint/evidence-connectors",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/evidence-connectors/{source}/rotate": {
      "post": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Rotate an evidence connector bearer (returned once)",
        "description": "Twin of `POST /admin/endpoint/evidence-connectors/:source/rotate`: the same handler, so the response body is identical.\n\nRequires the `fleet:enroll` scope (`deployment`-level resource).",
        "operationId": "v1_post_fleet_evidence_connectors_source_rotate",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "source",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:enroll",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/endpoint/evidence-connectors/:source/rotate",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/evidence-connectors/{source}": {
      "delete": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Remove an evidence connector",
        "description": "Twin of `DELETE /admin/endpoint/evidence-connectors/:source`: the same handler, so the response body is identical.\n\nRequires the `fleet:enroll` scope (`deployment`-level resource).",
        "operationId": "v1_delete_fleet_evidence_connectors_source",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "source",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content-free JSON as served by the legacy twin (see `x-legacy-operation`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:enroll",
        "x-scope": "deployment",
        "x-legacy-operation": "DELETE /admin/endpoint/evidence-connectors/:source",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/mdm-servers": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Read registered MDM server URLs",
        "description": "Returns the normalized MDM server URLs used to verify managed devices. Requires the `config:read` capability and deployment-owner access.\n\nTwin of `GET /admin/endpoint-fleet/mdm-servers`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_mdm_servers",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "serverUrls",
                    "updatedAt"
                  ],
                  "properties": {
                    "serverUrls": {
                      "type": "array",
                      "maxItems": 20,
                      "items": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 512
                      }
                    },
                    "updatedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint-fleet/mdm-servers",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Replace registered MDM server URLs",
        "description": "Validates and stores up to 20 HTTPS MDM server URLs, then best-effort converges the local endpoint-control policy and legacy Fleet pack. The audit entry records only the URL count. Requires the `provisioning:manage` capability and deployment-owner access.\n\nTwin of `PUT /admin/endpoint-fleet/mdm-servers`: the same handler, so the response body is identical.\n\nRequires the `fleet:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_fleet_mdm_servers",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "serverUrls"
                ],
                "properties": {
                  "serverUrls": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "type": "string",
                      "format": "uri",
                      "maxLength": 512
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored and convergence attempted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "serverUrls"
                  ],
                  "properties": {
                    "serverUrls": {
                      "type": "array",
                      "maxItems": 20,
                      "items": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 512
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/endpoint-fleet/mdm-servers",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/mdm-profile": {
      "post": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Download the end-point MDM enrollment profile",
        "description": "Build this deployment's macOS enrollment profile (`.mobileconfig`) from the stored end-point control-server address and the organization's enroll secret. The profile is the per-organization half of the shared, credential-free agent installer and uses payload type `com.fleetdm.fleetd.config`. Repeated downloads contain the same current enrollment configuration and do not rotate the secret. The response body is a live credential and must not be logged or rendered. Requires the `enrollment:manage` capability and the deployment owner; proxied to Anyray Portal with this deployment's token.\n\nTwin of `POST /admin/endpoint-fleet/mdm-profile`: the same handler, so the response body is identical.\n\nRequires the `fleet:enroll` scope (`deployment`-level resource).",
        "operationId": "v1_post_fleet_mdm_profile",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The organization's current enrollment profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          },
          "409": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:enroll",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/endpoint-fleet/mdm-profile",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/installers": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "List end-point installers",
        "description": "List the stored per-OS fleetd installer artifacts and the pack version each was built with. Credential-grade (installers bake the enroll secret) — requires the `enrollment:manage` capability.\n\nTwin of `GET /admin/endpoint-fleet/installers`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_installers",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint-fleet/installers",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/installers/{os}": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Download an end-point installer",
        "description": "Download the stored fleetd installer for an OS (pkg/msi/deb/rpm). Bakes the enroll secret — requires the `enrollment:manage` capability.\n\nTwin of `GET /admin/endpoint-fleet/installers/:os`: the same handler, so the response body is identical.\n\nRequires the `fleet:enroll` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_installers_os",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "os",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:enroll",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/endpoint-fleet/installers/:os",
        "x-api-status": "stable"
      },
      "put": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Upload an end-point installer",
        "description": "Upload a pre-built fleetd installer for an OS (provisioning lane / CI). Requires the `provisioning:manage` capability.\n\nTwin of `PUT /admin/endpoint-fleet/installers/:os`: the same handler, so the response body is identical.\n\nRequires the `fleet:write` scope (`deployment`-level resource).",
        "operationId": "v1_put_fleet_installers_os",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "os",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:write",
        "x-scope": "deployment",
        "x-legacy-operation": "PUT /admin/endpoint-fleet/installers/:os",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/seats": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Per-seat connect-health rollup",
        "description": "Per-seat connect-health over the gateway's rolling 24h window (RFC 0010 P3): each seat's pseudonymous `userHash`, last-seen instant, connect version (when reported), per-check statuses (`gateway_reachable`, `enrollment_cert`, per-tool `routing`, …), and a 0–100 `complianceScore` weighted against the fleet tool policy's `tools.enabled`. Content-free — opaque hashes, enum tokens, counts, and timestamps only; never a name or email. Requires the `observability:read` capability plus deployment owner.\n\nTwin of `GET /admin/connect-health`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_seats",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 200
            },
            "description": "Maximum seats returned (worst compliance first)."
          },
          {
            "name": "user",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{20,64}$"
            },
            "description": "Narrow to one seat by its pseudonymous `userHash`."
          }
        ],
        "responses": {
          "200": {
            "description": "The per-seat rollup: `windowHours`, `generatedAt`, `policyEnabledTools`, `userCount`, `users[]` (each with `userHash`, `lastSeen`, `connectVersion`, `complianceScore`, `failingChecks`, `checks[]`), and the deployment-wide `versions` mix.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/connect-health",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/seats/query": {
      "post": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Per-user end-point machine compliance",
        "description": "Resolve which end-point machines each supplied roster identity's enrolled seat runs on, with each machine's compliance state. The gateway resolves identity → pseudonym → machine-seat rows → the end-point host with the same hardware-UUID hash entirely server-side; the pseudonym secret never leaves the deployment and no hash is mapped back to an identity the caller did not supply. A machine that joins to no end-point host record carries no compliance claim. Read-only despite the POST (the roster does not fit a query string). Requires the `observability:read` capability.\n\nTwin of `POST /admin/endpoint-fleet/user-machines`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_post_fleet_seats_query",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "users"
                ],
                "properties": {
                  "users": {
                    "type": "array",
                    "description": "Roster identities to resolve (1–200).",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/endpoint-fleet/user-machines",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/fleet/directives": {
      "get": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "List connect remediation directives",
        "description": "Directive history (every status, acked included), newest first — the console coverage page's read counterpart of the queue POST. Optional `user` filters to one pseudonymous `userHash`; `limit` (default 200, max 1000) bounds the page. Requires the `observability:read` capability plus the deployment owner. Content-free: userHash, enums, and timestamps only.\n\nTwin of `GET /admin/connect/directives`: the same handler, so the response body is identical.\n\nRequires the `fleet:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_fleet_directives",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "user",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{20,64}$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "directives"
                  ],
                  "properties": {
                    "directives": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "userHash",
                          "kind",
                          "status",
                          "queuedBy",
                          "createdAt"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "userHash": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "reapply_config",
                              "remint",
                              "revert"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "delivered",
                              "acked"
                            ]
                          },
                          "queuedBy": {
                            "type": "string"
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "deliveredAt": {
                            "type": "string"
                          },
                          "ackedAt": {
                            "type": "string"
                          },
                          "ackResult": {
                            "type": "string",
                            "enum": [
                              "ok",
                              "failed"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/connect/directives",
        "x-api-status": "stable"
      },
      "post": {
        "tags": [
          "Management API v1 · Fleet"
        ],
        "summary": "Queue a connect remediation directive",
        "description": "Queue a per-user remediation directive (RFC 0009 §4.3) for a developer identified by their pseudonymous `userHash` (from the per-user connect-health view). The developer's machine picks it up on its next `/connect/verify` and applies it — pull-only, never pushed. `kind` is one of `reapply_config` (re-apply the tool config), `remint`, or `revert`. Requires the `idp:manage` capability. `kind` is `reapply_config`, `remint`, `revert`, or `revert_tool`; `revert_tool` additionally requires `tool` (a lowercase adapter slug) and un-routes only that tool, leaving the seat enrolled for the rest.\n\nTwin of `POST /admin/connect/directives`: the same handler, so the response body is identical.\n\nRequires the `fleet:direct` scope (`deployment`-level resource).",
        "operationId": "v1_post_fleet_directives",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userHash",
                  "kind"
                ],
                "properties": {
                  "userHash": {
                    "type": "string",
                    "description": "Pseudonymous developer id (HMAC-SHA256, base64url) from the per-user connect-health view."
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "reapply_config",
                      "remint",
                      "revert"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The queued directive.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "fleet:direct",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/connect/directives",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/traces": {
      "get": {
        "tags": [
          "Management API v1 · Traces"
        ],
        "summary": "List traces (metadata only)",
        "description": "Native management API operation.\n\nRequires the `traces:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_traces",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Metadata-only observability rows from the trace store (never prompt/response content).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "traces:read",
        "x-scope": "tenant",
        "x-legacy-operation": null,
        "x-api-status": "stable"
      }
    },
    "/admin/v1/traces/facets": {
      "get": {
        "tags": [
          "Management API v1 · Traces"
        ],
        "summary": "Trace facets for filtering (metadata only)",
        "description": "Native management API operation.\n\nRequires the `traces:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_traces_facets",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Metadata-only observability rows from the trace store (never prompt/response content).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "traces:read",
        "x-scope": "tenant",
        "x-legacy-operation": null,
        "x-api-status": "stable"
      }
    },
    "/admin/v1/traces/sessions": {
      "get": {
        "tags": [
          "Management API v1 · Traces"
        ],
        "summary": "List sessions (metadata only)",
        "description": "Native management API operation.\n\nRequires the `traces:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_traces_sessions",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Metadata-only observability rows from the trace store (never prompt/response content).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "traces:read",
        "x-scope": "tenant",
        "x-legacy-operation": null,
        "x-api-status": "stable"
      }
    },
    "/admin/v1/traces/{id}": {
      "get": {
        "tags": [
          "Management API v1 · Traces"
        ],
        "summary": "Read a trace (metadata only; bodies are on the /content path)",
        "description": "Fetch one trace. Content is redacted unless the caller has `observability:read-content`. Other `/admin/observability/*` read paths proxy to the observability API. Requires the `observability:read` capability.\n\nDerived from `GET /admin/observability/traces/:id` (dispatches to it and its siblings; see the summary).\n\nRequires the `traces:read` scope (`tenant`-level resource).",
        "operationId": "v1_get_traces_id",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metadata-only observability rows from the trace store (never prompt/response content).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "traces:read",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/observability/traces/:id",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/traces/{id}/content": {
      "get": {
        "tags": [
          "Management API v1 · Traces"
        ],
        "summary": "Read a trace with its prompt/response bodies (never available to an API key)",
        "description": "Fetch one trace. Content is redacted unless the caller has `observability:read-content`. Other `/admin/observability/*` read paths proxy to the observability API. Requires the `observability:read` capability.\n\nTwin of `GET /admin/observability/traces/:id`: the same handler, so the response body is identical.\n\nRequires the `traces:content` scope (`tenant`-level resource).",
        "operationId": "v1_get_traces_id_content",
        "security": [
          {
            "AdminToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "traces:content",
        "x-scope": "tenant",
        "x-legacy-operation": "GET /admin/observability/traces/:id",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/audit/events": {
      "get": {
        "tags": [
          "Management API v1 · Audit"
        ],
        "summary": "Read the admin/GDPR audit trail, newest first ({data,next_cursor}; ?limit=&cursor=&category=)",
        "description": "Native management API operation.\n\nRequires the `audit:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_audit_events",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The previous page's `next_cursor`."
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[\\w-]{1,64}$"
            },
            "description": "Filter to one audit domain (e.g. `client-keys`, `gdpr`)."
          }
        ],
        "responses": {
          "200": {
            "description": "One page of the metadata-only audit trail, newest first. `next_cursor` is null on the last page.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "ts",
                          "category",
                          "event"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "ts": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "category": {
                            "type": "string"
                          },
                          "event": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "audit:read",
        "x-scope": "deployment",
        "x-legacy-operation": null,
        "x-api-status": "stable"
      }
    },
    "/admin/v1/audit/auth-events": {
      "get": {
        "tags": [
          "Management API v1 · Audit"
        ],
        "summary": "Auth rejection diagnostics",
        "description": "Customer-local, content-free auth rejection events with machine-readable reason codes and remediation hints.\n\nTwin of `GET /admin/auth-events`: the same handler, so the response body is identical.\n\nRequires the `audit:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_audit_auth_events",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "user",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "description": "Optional customer-local user id filter."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            },
            "description": "Max events returned, newest first. Values above 200 are clamped."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthEvents"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "audit:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/auth-events",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/audit/metering": {
      "get": {
        "tags": [
          "Management API v1 · Audit"
        ],
        "summary": "Read the last metering report",
        "description": "Returns the exact final payload from this process's last successful, verified metering round, plus the active diagnostics tier and metering state. Requires the `config:read` capability.\n\nTwin of `GET /admin/metering/last-report`: the same handler, so the response body is identical.\n\nRequires the `audit:read` scope (`deployment`-level resource).",
        "operationId": "v1_get_audit_metering",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "audit:read",
        "x-scope": "deployment",
        "x-legacy-operation": "GET /admin/metering/last-report",
        "x-api-status": "stable"
      }
    },
    "/admin/v1/playground": {
      "post": {
        "tags": [
          "Management API v1 · Playground"
        ],
        "summary": "Playground test request",
        "description": "Send a test request through the gateway (console playground). Requires the `playground:run` capability.\n\nTwin of `POST /admin/test-request`: the same handler, so the response body is identical.\n\nRequires the `playground:run` scope (`deployment`-level resource).",
        "operationId": "v1_post_playground",
        "security": [
          {
            "AdminToken": []
          },
          {
            "AdminApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiError"
          },
          "403": {
            "$ref": "#/components/responses/ApiError"
          }
        },
        "x-required-scope": "playground:run",
        "x-scope": "deployment",
        "x-legacy-operation": "POST /admin/test-request",
        "x-api-status": "stable"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Anyray client or service key, sent as `Authorization: Bearer <key>`. Human `ark_` keys carry developer attribution; non-human `ark_svc_` keys carry service identity and may have a per-key monthly dollar budget. A valid minted key is ALWAYS required on `/v1/*` (no opt-out), and its bound identity is authoritative over the `x-anyray-metadata` header. The real upstream provider key is held server-side and never sent by the client."
      },
      "AnyrayApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-anyray-api-key",
        "description": "The same Anyray client key, supplied via the `x-anyray-api-key` header instead of `Authorization: Bearer`. Takes precedence over the bearer header when both are present."
      },
      "AdminToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Admin access: the break-glass `ANYRAY_ADMIN_TOKEN` as `Authorization: Bearer <token>`, or a role-scoped console SSO session. Each /admin/* route also requires a capability (shown per operation); the admin token owner passes all capability checks."
      },
      "ConnectKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-anyray-api-key",
        "description": "Connect (coding-tool) client key — an `ark_`-prefixed key minted by `POST /connect/verify` (or by an admin via the console / an enrollment link) and stored in the shared spend DB. Sent via the `x-anyray-api-key` header, or as `Authorization: Bearer <key>` when that header is absent. It carries the developer's user/team attribution; the `/connect/*` routes resolve identity from it. This is the same credential accepted on `/v1/*`, scoped here to the coding-tool integration surface."
      },
      "AuthKitBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "WorkOS AuthKit access token for the exact `/mcp/org` resource URL. The gateway verifies RS256 signature, issuer, scalar audience, expiry, subject, and WorkOS organization, then Billing resolves current organization membership and Anyray policy."
      },
      "AdminApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Scoped admin API key (`aak_…`), sent as `Authorization: Bearer <key>` to the GATEWAY origin (the console host strips this header). Listed on an operation only when the capability that operation enforces is one a key may hold: trace content, content-mode, SSO config, self-update, and key management can never ride a key, so those operations accept the admin token or an SSO session only. In fleet mode a tenant-bound key additionally fails the deployment-owner routes."
      }
    },
    "parameters": {
      "ProviderHeader": {
        "name": "x-anyray-provider",
        "in": "header",
        "required": false,
        "description": "Upstream provider id to route to (e.g. `openai`, `anthropic`, `vertex-ai`, `bedrock`, `azure-openai`). Optional when a default provider or routing config is configured server-side.",
        "schema": {
          "type": "string"
        }
      },
      "MetadataHeader": {
        "name": "x-anyray-metadata",
        "in": "header",
        "required": false,
        "description": "Content-free attribution as a JSON object, e.g. `{\"user\":\"alice\",\"team\":\"platform\"}`. Used for spend attribution and per-user caps. Never carries prompt/response content.",
        "schema": {
          "type": "string"
        }
      },
      "ConfigHeader": {
        "name": "x-anyray-config",
        "in": "header",
        "required": false,
        "description": "JSON routing config for this request (fallback list, load-balance weights, retry policy). Credentials are never carried here — they are resolved from the server-held key store.",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed request (failed Zod validation, bad JSON, or an unknown provider/model).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Authentication is missing or invalid. The response is content-free and never echoes a credential.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit or per-user monthly token cap exceeded. Honors `Retry-After`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServiceKeyBudgetExceeded": {
        "description": "The bound service key has reached its successful-request cost budget for the current UTC calendar month. The soft cap is fail-open when its durable counter is unavailable.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ServiceKeyBudgetExceeded"
            }
          }
        }
      },
      "ClientKeyUnauthorized": {
        "description": "A personal gateway key is missing, unknown, expired, or revoked. The response is content-free and never echoes a credential.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ClientKeyUnauthorized"
            }
          }
        }
      },
      "ApiError": {
        "description": "Error. Every management API error, whatever the status, carries this envelope; the `code` is stable and the message is content-free.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "schemas": {
      "ChatCompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "description": "OpenAI-compatible chat completion request. Unlisted OpenAI fields are passed through to the provider.",
        "properties": {
          "model": {
            "type": "string",
            "minLength": 1,
            "description": "Model id or alias (e.g. `gpt-4o`, `claude-sonnet-4-5`)."
          },
          "messages": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            }
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2,
            "default": 1
          },
          "top_p": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Max output tokens (legacy field)."
          },
          "max_completion_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Max output tokens (preferred field)."
          },
          "n": {
            "type": "integer",
            "minimum": 1,
            "default": 1
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "Stream the response as server-sent events."
          },
          "stop": {
            "description": "Up to 4 stop sequences.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "presence_penalty": {
            "type": "number",
            "minimum": -2,
            "maximum": 2
          },
          "frequency_penalty": {
            "type": "number",
            "minimum": -2,
            "maximum": 2
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "description": "Tool/function definitions, OpenAI tool-calling format."
          },
          "tool_choice": {
            "description": "Controls which tool is called.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "additionalProperties": true
              }
            ]
          },
          "response_format": {
            "type": "object",
            "additionalProperties": true
          },
          "seed": {
            "type": "integer"
          },
          "user": {
            "type": "string",
            "description": "End-user identifier passed to the provider. Use `x-anyray-metadata` for Anyray attribution."
          }
        },
        "additionalProperties": true
      },
      "ChatMessage": {
        "type": "object",
        "required": [
          "role"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "user",
              "assistant",
              "tool",
              "developer"
            ]
          },
          "content": {
            "description": "Message content — a string, or an array of typed content parts (text/image).",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "name": {
            "type": "string"
          },
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "tool_call_id": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "chat.completion"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "$ref": "#/components/schemas/ChatMessage"
                },
                "finish_reason": {
                  "type": "string"
                }
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "additionalProperties": true
      },
      "EmbeddingRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "minLength": 1
          },
          "input": {
            "description": "Text(s) to embed.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            ]
          },
          "dimensions": {
            "type": "integer",
            "minimum": 1,
            "description": "Truncate the output embedding to this many dimensions (if the model supports it)."
          },
          "encoding_format": {
            "type": "string",
            "enum": [
              "float",
              "base64"
            ]
          },
          "user": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "EmbeddingResponse": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "list"
          },
          "model": {
            "type": "string"
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "object": {
                  "type": "string",
                  "const": "embedding"
                },
                "index": {
                  "type": "integer"
                },
                "embedding": {
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                }
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "additionalProperties": true
      },
      "MessagesRequest": {
        "type": "object",
        "required": [
          "model",
          "messages",
          "max_tokens"
        ],
        "description": "Anthropic-native Messages request. Unlisted Anthropic fields are passed through.",
        "properties": {
          "model": {
            "type": "string",
            "minLength": 1
          },
          "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",
                        "additionalProperties": true
                      }
                    }
                  ]
                }
              },
              "additionalProperties": true
            }
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Maximum output tokens (required by the Anthropic API)."
          },
          "system": {
            "description": "System prompt — a string or an array of content blocks.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            ]
          },
          "stop_sequences": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "top_p": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "top_k": {
            "type": "integer",
            "minimum": 0
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "tool_choice": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "MessagesResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "const": "message"
          },
          "role": {
            "type": "string",
            "const": "assistant"
          },
          "model": {
            "type": "string"
          },
          "content": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "stop_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "stop_sequence": {
            "type": [
              "string",
              "null"
            ]
          },
          "usage": {
            "type": "object",
            "properties": {
              "input_tokens": {
                "type": "integer"
              },
              "output_tokens": {
                "type": "integer"
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "model"
          },
          "created": {
            "type": "integer"
          },
          "owned_by": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "Usage": {
        "type": "object",
        "properties": {
          "prompt_tokens": {
            "type": "integer"
          },
          "completion_tokens": {
            "type": "integer"
          },
          "total_tokens": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "code": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "param": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "ClientKeyUnauthorized": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "code",
          "message",
          "hint"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "failure"
          },
          "code": {
            "type": "string",
            "enum": [
              "missing_key",
              "key_unknown",
              "key_expired",
              "key_revoked"
            ]
          },
          "message": {
            "type": "string",
            "const": "valid client key required"
          },
          "hint": {
            "type": "string",
            "description": "Bounded, content-free remediation for the reason code."
          }
        }
      },
      "ServiceKeyCreateRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "team"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Service identity name; also stored as the key label."
          },
          "team": {
            "type": "string",
            "minLength": 1
          },
          "monthlyBudgetUsd": {
            "type": "number",
            "minimum": 0,
            "description": "Optional successful-request cost cap for one UTC calendar month. Omit or set to 0 for unlimited."
          },
          "delegatedAttribution": {
            "type": "boolean",
            "description": "Service keys only. When true, each request the key signs is attributed to the end user named in its x-anyray-metadata header (`user`, validated as an id), with `team` from the header when sent, so the people a shared agent serves become the attributed seats; the agent stays on every row as `agent`. A claim that fails validation falls back to the agent's own name."
          }
        }
      },
      "ServiceKeyRecord": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "user",
          "team",
          "tenant",
          "label",
          "createdAt",
          "keyType",
          "source",
          "type"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "user": {
            "type": "string"
          },
          "team": {
            "type": "string"
          },
          "tenant": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "revokedAt": {
            "type": "string",
            "format": "date-time"
          },
          "firstSeenAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the key first signed a verified request. Absent until it has."
          },
          "lastSeenAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the key last signed a verified request, to within a few minutes."
          },
          "lastSeenTool": {
            "type": "string",
            "description": "Client id of the last request: an inferred id (codex, claude-code, shell-env, unknown, …) or a shape-validated x-anyray-metadata tool such as openclaw. Never the raw User-Agent."
          },
          "keyType": {
            "type": "string",
            "const": "service"
          },
          "monthlyBudgetUsd": {
            "type": "number",
            "minimum": 0
          },
          "source": {
            "type": "string",
            "const": "service"
          },
          "type": {
            "type": "string",
            "const": "service"
          },
          "delegatedAttribution": {
            "type": "boolean",
            "const": true,
            "description": "Present (true) only on a service key with delegated attribution on; absent when off."
          }
        }
      },
      "ServiceKeyMintResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "key",
          "record"
        ],
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^ark_svc_",
            "description": "Raw token, returned exactly once and never stored."
          },
          "record": {
            "$ref": "#/components/schemas/ServiceKeyRecord"
          }
        }
      },
      "ServiceKeyListResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "keys"
        ],
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceKeyRecord"
            }
          }
        }
      },
      "ServiceKeyBudgetExceeded": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "const": "service_key_budget_exceeded"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "UsageBucket": {
        "type": "object",
        "properties": {
          "requests": {
            "type": "integer"
          },
          "totalTokens": {
            "type": "integer"
          },
          "promptTokens": {
            "type": "integer"
          },
          "completionTokens": {
            "type": "integer"
          },
          "costUsd": {
            "type": "number",
            "description": "List price of what ran."
          },
          "spendUsd": {
            "type": "number",
            "description": "Real out-of-pocket (subscription seats spend only their overage)."
          },
          "savingsUsd": {
            "type": "number",
            "description": "Billed savings."
          },
          "grossSavingsUsd": {
            "type": "number",
            "description": "Pre-scaling savings; use for cross-user comparisons."
          }
        }
      },
      "UserCapGauge": {
        "type": "object",
        "nullable": true,
        "properties": {
          "monthlyTokens": {
            "type": "integer"
          },
          "usedTokens": {
            "type": "integer",
            "description": "Current calendar month, whatever window is shown."
          },
          "pctUsed": {
            "type": "number"
          }
        }
      },
      "UsageUser": {
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/UsageBucket"
          }
        ],
        "properties": {
          "user": {
            "type": "string"
          },
          "team": {
            "type": "string",
            "nullable": true
          },
          "subscriptionTokens": {
            "type": "integer",
            "description": "Tokens on subscription-seat rows (>0 marks a seat)."
          },
          "seatExcluded": {
            "type": "boolean",
            "description": "Matches ANYRAY_SEAT_EXCLUDE (bot/service account)."
          },
          "cap": {
            "$ref": "#/components/schemas/UserCapGauge"
          },
          "byModel": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Per-model UsageBucket + model id, heaviest first."
          },
          "byDay": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Per-UTC-day usage, ascending."
          }
        }
      },
      "SpendUsage": {
        "type": "object",
        "properties": {
          "window": {
            "type": "string"
          },
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          },
          "totalUsers": {
            "type": "integer"
          },
          "truncated": {
            "type": "boolean"
          },
          "users": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsageUser"
            }
          },
          "byModel": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Org-wide per-model rollup incl. distinct-user reach."
          },
          "capAlerts": {
            "type": "object",
            "properties": {
              "thresholds": {
                "type": "array",
                "items": {
                  "type": "number"
                }
              },
              "webhookConfigured": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "AuthEvents": {
        "type": "object",
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuthEvent"
            }
          }
        }
      },
      "AuthEvent": {
        "type": "object",
        "properties": {
          "ts": {
            "type": "string",
            "format": "date-time"
          },
          "reason": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          },
          "userRef": {
            "type": "string"
          },
          "keyPrefix": {
            "type": "string",
            "description": "Short prefix only; never the full credential."
          },
          "tool": {
            "type": "string"
          },
          "toolVersion": {
            "type": "string"
          },
          "replicaId": {
            "type": "string"
          }
        }
      },
      "SpendConnectorPollCounts": {
        "type": "object",
        "required": [
          "fetched",
          "inserted",
          "duplicate"
        ],
        "properties": {
          "fetched": {
            "type": "integer",
            "minimum": 0
          },
          "inserted": {
            "type": "integer",
            "minimum": 0
          },
          "duplicate": {
            "type": "integer",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorPollStatus": {
        "type": "object",
        "required": [
          "state",
          "leaseUntil",
          "lastAttemptAt",
          "consecutiveFailures"
        ],
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "running",
              "succeeded",
              "failed"
            ]
          },
          "leaseUntil": {
            "type": "string",
            "format": "date-time",
            "description": "Earliest instant at which another fleet replica may claim this connector."
          },
          "lastAttemptAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastSuccessAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastFailureAt": {
            "type": "string",
            "format": "date-time"
          },
          "consecutiveFailures": {
            "type": "integer",
            "minimum": 0
          },
          "lastResult": {
            "$ref": "#/components/schemas/SpendConnectorPollCounts"
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorReadState": {
        "type": "object",
        "required": [
          "configured",
          "enabled"
        ],
        "properties": {
          "configured": {
            "type": "boolean",
            "const": true
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether automatic polling is enabled. Disabled legacy credentials remain encrypted until rotated or removed."
          },
          "status": {
            "$ref": "#/components/schemas/SpendConnectorPollStatus"
          }
        },
        "additionalProperties": false
      },
      "GithubCopilotSpendConnectorReadState": {
        "type": "object",
        "required": [
          "configured",
          "enabled"
        ],
        "properties": {
          "configured": {
            "type": "boolean",
            "const": true
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether automatic polling is enabled."
          },
          "scope": {
            "type": "string",
            "enum": [
              "organization",
              "enterprise"
            ]
          },
          "slug": {
            "type": "string",
            "description": "Non-secret GitHub organization or enterprise slug."
          },
          "status": {
            "$ref": "#/components/schemas/SpendConnectorPollStatus"
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorsRead": {
        "type": "object",
        "description": "Redacted connector state. Unconfigured connectors are omitted; credentials never appear.",
        "properties": {
          "cursor": {
            "$ref": "#/components/schemas/SpendConnectorReadState"
          },
          "devin": {
            "$ref": "#/components/schemas/SpendConnectorReadState"
          },
          "githubCopilot": {
            "$ref": "#/components/schemas/GithubCopilotSpendConnectorReadState"
          }
        },
        "additionalProperties": false
      },
      "CursorSpendConnectorCredential": {
        "type": "object",
        "required": [
          "adminApiKey"
        ],
        "properties": {
          "adminApiKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 16384,
            "writeOnly": true,
            "description": "Cursor Teams Admin API key. Non-empty after trimming; encrypted at rest and never returned."
          },
          "enabled": {
            "type": "boolean",
            "default": true,
            "description": "Set false to retain the encrypted credential without polling."
          }
        },
        "additionalProperties": false
      },
      "DevinSpendConnectorCredential": {
        "type": "object",
        "required": [
          "serviceUserToken"
        ],
        "properties": {
          "serviceUserToken": {
            "type": "string",
            "minLength": 1,
            "maxLength": 16384,
            "writeOnly": true,
            "description": "Devin service-user token with consumption-read permission. Non-empty after trimming; encrypted at rest and never returned."
          },
          "enabled": {
            "type": "boolean",
            "default": true,
            "description": "Set false to retain the encrypted credential without polling."
          }
        },
        "additionalProperties": false
      },
      "GithubCopilotSpendConnectorCredential": {
        "type": "object",
        "required": [
          "token"
        ],
        "anyOf": [
          {
            "required": [
              "scope",
              "slug"
            ]
          },
          {
            "required": [
              "enabled"
            ],
            "properties": {
              "enabled": {
                "const": false
              }
            }
          }
        ],
        "properties": {
          "token": {
            "type": "string",
            "minLength": 1,
            "maxLength": 16384,
            "writeOnly": true,
            "description": "GitHub token with Copilot usage-metrics read permission. Non-empty after trimming; encrypted at rest and never returned."
          },
          "enabled": {
            "type": "boolean",
            "default": true,
            "description": "Set false to retain the encrypted credential without polling. Scope and slug are required whenever enabled is true."
          },
          "scope": {
            "type": "string",
            "enum": [
              "organization",
              "enterprise"
            ]
          },
          "slug": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^[A-Za-z0-9_.-]+$",
            "description": "GitHub organization or enterprise slug for the selected scope."
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorRemoval": {
        "type": "object",
        "maxProperties": 0,
        "additionalProperties": false,
        "description": "An empty object removes this connector; JSON `null` has the same effect."
      },
      "SpendConnectorsPatch": {
        "type": "object",
        "description": "Partial connector update. Omitted properties stay unchanged; credential fields are write-only.",
        "properties": {
          "cursor": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CursorSpendConnectorCredential"
              },
              {
                "$ref": "#/components/schemas/SpendConnectorRemoval"
              },
              {
                "type": "null"
              }
            ]
          },
          "devin": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DevinSpendConnectorCredential"
              },
              {
                "$ref": "#/components/schemas/SpendConnectorRemoval"
              },
              {
                "type": "null"
              }
            ]
          },
          "githubCopilot": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/GithubCopilotSpendConnectorCredential"
              },
              {
                "$ref": "#/components/schemas/SpendConnectorRemoval"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "LegacySpendConnectorToken": {
        "type": "string",
        "minLength": 0,
        "maxLength": 16384,
        "writeOnly": true,
        "description": "Legacy vendor credential. An empty value removes the source; other values must be non-empty after trimming, are encrypted at rest, and are never returned."
      },
      "LegacyCursorSpendConnectorPatch": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/LegacySpendConnectorToken"
          },
          {
            "type": "object",
            "description": "Legacy token object. A missing or empty token removes Cursor.",
            "not": {
              "required": [
                "adminApiKey"
              ]
            },
            "properties": {
              "token": {
                "$ref": "#/components/schemas/LegacySpendConnectorToken"
              },
              "enabled": {
                "type": "boolean",
                "default": true
              }
            },
            "additionalProperties": true
          },
          {
            "$ref": "#/components/schemas/CursorSpendConnectorCredential"
          },
          {
            "type": "null"
          }
        ]
      },
      "LegacyDevinSpendConnectorPatch": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/LegacySpendConnectorToken"
          },
          {
            "type": "object",
            "description": "Legacy token object. A missing or empty token removes Devin.",
            "not": {
              "required": [
                "serviceUserToken"
              ]
            },
            "properties": {
              "token": {
                "$ref": "#/components/schemas/LegacySpendConnectorToken"
              },
              "enabled": {
                "type": "boolean",
                "default": true
              }
            },
            "additionalProperties": true
          },
          {
            "$ref": "#/components/schemas/DevinSpendConnectorCredential"
          },
          {
            "type": "null"
          }
        ]
      },
      "LegacyCopilotSpendConnectorPatch": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/LegacySpendConnectorToken"
          },
          {
            "type": "object",
            "description": "Legacy token object. A missing or empty token removes Copilot; a token without an org or enterprise is retained disabled.",
            "not": {
              "required": [
                "scope",
                "slug"
              ]
            },
            "properties": {
              "token": {
                "$ref": "#/components/schemas/LegacySpendConnectorToken"
              },
              "enabled": {
                "type": "boolean",
                "default": true
              },
              "org": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255,
                "pattern": "^[A-Za-z0-9_.-]+$"
              },
              "enterprise": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255,
                "pattern": "^[A-Za-z0-9_.-]+$"
              }
            },
            "additionalProperties": true
          },
          {
            "$ref": "#/components/schemas/GithubCopilotSpendConnectorCredential"
          },
          {
            "type": "null"
          }
        ]
      },
      "LegacySpendConnectorsPatch": {
        "type": "object",
        "properties": {
          "cursor": {
            "$ref": "#/components/schemas/LegacyCursorSpendConnectorPatch"
          },
          "devin": {
            "$ref": "#/components/schemas/LegacyDevinSpendConnectorPatch"
          },
          "copilot": {
            "$ref": "#/components/schemas/LegacyCopilotSpendConnectorPatch"
          },
          "githubCopilot": {
            "$ref": "#/components/schemas/LegacyCopilotSpendConnectorPatch"
          }
        },
        "additionalProperties": false
      },
      "LegacySpendConnectorReadState": {
        "type": "object",
        "required": [
          "configured",
          "enabled"
        ],
        "properties": {
          "configured": {
            "type": "boolean",
            "const": true
          },
          "enabled": {
            "type": "boolean"
          },
          "org": {
            "type": "string"
          },
          "enterprise": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "LegacySpendConnectorsRead": {
        "type": "object",
        "required": [
          "connectors",
          "supportedVendors"
        ],
        "properties": {
          "connectors": {
            "type": "object",
            "properties": {
              "cursor": {
                "$ref": "#/components/schemas/LegacySpendConnectorReadState"
              },
              "devin": {
                "$ref": "#/components/schemas/LegacySpendConnectorReadState"
              },
              "copilot": {
                "$ref": "#/components/schemas/LegacySpendConnectorReadState"
              }
            },
            "additionalProperties": false
          },
          "supportedVendors": {
            "type": "array",
            "minItems": 3,
            "maxItems": 3,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "cursor",
                "devin",
                "copilot"
              ]
            }
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorName": {
        "type": "string",
        "enum": [
          "cursor",
          "devin",
          "githubCopilot"
        ]
      },
      "SpendConnectorSyncSuccess": {
        "type": "object",
        "required": [
          "connector",
          "fetched",
          "inserted",
          "duplicate"
        ],
        "properties": {
          "connector": {
            "$ref": "#/components/schemas/SpendConnectorName"
          },
          "fetched": {
            "type": "integer",
            "minimum": 0
          },
          "inserted": {
            "type": "integer",
            "minimum": 0
          },
          "duplicate": {
            "type": "integer",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorSyncSkipped": {
        "type": "object",
        "required": [
          "connector",
          "skipped"
        ],
        "properties": {
          "connector": {
            "$ref": "#/components/schemas/SpendConnectorName"
          },
          "skipped": {
            "type": "boolean",
            "const": true,
            "description": "Another replica owns the connector's durable poll lease."
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorSyncFailed": {
        "type": "object",
        "required": [
          "connector",
          "failed"
        ],
        "properties": {
          "connector": {
            "$ref": "#/components/schemas/SpendConnectorName"
          },
          "failed": {
            "type": "boolean",
            "const": true,
            "description": "The vendor sync failed. No vendor error body, URL, or credential is exposed."
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorSyncResult": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/SpendConnectorSyncSuccess"
          },
          {
            "$ref": "#/components/schemas/SpendConnectorSyncSkipped"
          },
          {
            "$ref": "#/components/schemas/SpendConnectorSyncFailed"
          }
        ]
      },
      "SpendConnectorSyncResponse": {
        "type": "object",
        "required": [
          "connectors"
        ],
        "properties": {
          "connectors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpendConnectorSyncResult"
            }
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorCursorUsage": {
        "type": "object",
        "required": [
          "events",
          "users",
          "tokens",
          "listPriceUsd",
          "paidExtraUsd",
          "requestUnits"
        ],
        "properties": {
          "events": {
            "type": "integer",
            "minimum": 0
          },
          "users": {
            "type": "integer",
            "minimum": 0
          },
          "tokens": {
            "type": "number",
            "minimum": 0
          },
          "listPriceUsd": {
            "type": "number",
            "minimum": 0,
            "description": "Published model value in USD; distinct from paid-extra spend."
          },
          "paidExtraUsd": {
            "type": "number",
            "minimum": 0,
            "description": "Vendor-confirmed usage-based amount charged beyond included subscription usage."
          },
          "requestUnits": {
            "type": "number",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorDevinUsage": {
        "type": "object",
        "required": [
          "days",
          "acus",
          "byProduct"
        ],
        "properties": {
          "days": {
            "type": "integer",
            "minimum": 0,
            "description": "Distinct closed Devin billing days represented."
          },
          "acus": {
            "type": "number",
            "minimum": 0,
            "description": "Vendor-native Agent Compute Units; never converted to tokens or USD."
          },
          "byProduct": {
            "type": "object",
            "additionalProperties": {
              "type": "number",
              "minimum": 0
            }
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorGithubCopilotUsage": {
        "type": "object",
        "required": [
          "userDays",
          "users",
          "cliTokens",
          "aiCreditsUsed",
          "aiCreditsListValueUsd",
          "interactions",
          "generations",
          "acceptances"
        ],
        "properties": {
          "userDays": {
            "type": "integer",
            "minimum": 0
          },
          "users": {
            "type": "integer",
            "minimum": 0
          },
          "cliTokens": {
            "type": "number",
            "minimum": 0,
            "description": "Provider-reported Copilot CLI prompt plus output tokens."
          },
          "aiCreditsUsed": {
            "type": "number",
            "minimum": 0,
            "description": "Vendor-native AI credits."
          },
          "aiCreditsListValueUsd": {
            "type": "number",
            "minimum": 0,
            "description": "Public GitHub list value at $0.01 per reported AI credit; visibility only, not an invoice total."
          },
          "interactions": {
            "type": "number",
            "minimum": 0
          },
          "generations": {
            "type": "number",
            "minimum": 0
          },
          "acceptances": {
            "type": "number",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "SpendConnectorUsage": {
        "type": "object",
        "required": [
          "from",
          "to",
          "cursor",
          "devin",
          "githubCopilot"
        ],
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          },
          "cursor": {
            "$ref": "#/components/schemas/SpendConnectorCursorUsage"
          },
          "devin": {
            "$ref": "#/components/schemas/SpendConnectorDevinUsage"
          },
          "githubCopilot": {
            "$ref": "#/components/schemas/SpendConnectorGithubCopilotUsage"
          }
        },
        "additionalProperties": false
      },
      "UserCap": {
        "type": "object",
        "required": [
          "monthlyTokens"
        ],
        "properties": {
          "monthlyTokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Positive whole token ceiling for the calendar month."
          }
        }
      },
      "ClaudeDesktopPolicyInput": {
        "type": "object",
        "required": [
          "enabled",
          "settings"
        ],
        "additionalProperties": false,
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "settings": {
            "type": "object",
            "additionalProperties": true,
            "description": "Recognized, secret-free Claude managed-policy fields. Inference connection and credential fields are server-owned."
          }
        }
      },
      "ClaudeDesktopOrgSkillInput": {
        "type": "object",
        "required": [
          "id",
          "name",
          "description",
          "version",
          "kind",
          "files"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9_-])?$"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": {
            "type": "string",
            "maxLength": 4096
          },
          "version": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "kind": {
            "type": "string",
            "enum": [
              "skill",
              "guidance"
            ]
          },
          "files": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "string"
            },
            "description": "Relative file paths mapped to credential-free UTF-8 content."
          }
        },
        "additionalProperties": false
      },
      "ClaudeDesktopOrgSkill": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ClaudeDesktopOrgSkillInput"
          },
          {
            "type": "object",
            "required": [
              "updatedAt",
              "updatedBy"
            ],
            "properties": {
              "updatedAt": {
                "type": "string",
                "format": "date-time"
              },
              "updatedBy": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        ]
      },
      "ClaudeDesktopPolicyResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ClaudeDesktopPolicyInput"
          },
          {
            "type": "object",
            "required": [
              "updatedAt",
              "deployment",
              "mcpHub"
            ],
            "properties": {
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "deployment": {
                "type": "object",
                "required": [
                  "gatewayBaseUrl",
                  "bootstrapUrl",
                  "helperPath",
                  "bootstrapHeadersHelperPath",
                  "mobileconfigFilename",
                  "bootstrapPolicyVisibility"
                ],
                "properties": {
                  "gatewayBaseUrl": {
                    "type": "string",
                    "format": "uri",
                    "nullable": true
                  },
                  "bootstrapUrl": {
                    "type": "string",
                    "format": "uri",
                    "nullable": true
                  },
                  "helperPath": {
                    "type": "string"
                  },
                  "bootstrapHeadersHelperPath": {
                    "type": "string"
                  },
                  "mobileconfigFilename": {
                    "type": "string"
                  },
                  "bootstrapPolicyVisibility": {
                    "type": "string",
                    "enum": [
                      "public-secret-free"
                    ]
                  }
                }
              },
              "mcpHub": {
                "$ref": "#/components/schemas/McpHubSummary"
              }
            }
          }
        ]
      },
      "UserCapsGet": {
        "type": "object",
        "properties": {
          "config": {
            "type": "object",
            "properties": {
              "caps": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/UserCap"
                }
              },
              "alerts": {
                "type": "object",
                "properties": {
                  "thresholds": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "webhookConfigured": {
                    "type": "boolean",
                    "description": "The webhook URL itself is write-only and never returned."
                  }
                }
              }
            }
          },
          "usage": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Current-month tokens per user."
          },
          "period": {
            "type": "string",
            "example": "2026-07"
          }
        }
      },
      "UserCapsPut": {
        "type": "object",
        "required": [
          "caps"
        ],
        "properties": {
          "caps": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/UserCap"
            }
          },
          "alerts": {
            "type": "object",
            "properties": {
              "webhookUrl": {
                "type": "string",
                "nullable": true,
                "description": "Slack-compatible incoming webhook. Absent = keep, null = clear, string = set. Write-only."
              },
              "thresholds": {
                "type": "array",
                "items": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "description": "Cap fractions (0<t≤1) that each fire once/user/month. Empty = reset to 0.8, 1.0."
              }
            }
          }
        }
      },
      "AdminApiKeyRecord": {
        "type": "object",
        "description": "A scoped admin API key, metadata only: the raw token is returned once at mint and only its SHA-256 is stored.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Opaque record id (the DELETE handle, not key material)."
          },
          "label": {
            "type": "string"
          },
          "caps": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The granted capability ids. Scope-minted keys store an empty array here and grant only their scopes."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Native Management API v1 scope ids, present only for a scope-minted key."
          },
          "tenant": {
            "type": "string"
          },
          "createdBy": {
            "type": "string",
            "description": "The minting operator (audit identity)."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "Absent = never expires (an explicit mint-time choice; the default is 90 days)."
          },
          "revokedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "caps",
          "createdBy",
          "createdAt"
        ]
      },
      "AdminApiKeyCreateRequest": {
        "type": "object",
        "description": "Exactly one of caps or scopes is required. A scope-minted key is Management API v1-only: it has no capabilities and cannot call legacy /admin/* capability-gated routes.",
        "properties": {
          "label": {
            "type": "string",
            "pattern": "^[\\w.:-]{1,64}$",
            "description": "Identity-shaped: 1-64 chars of letters, digits, and \".:-_\"."
          },
          "caps": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "description": "Capability ids to grant. Must be known, scopeable, and a subset of the minter's capabilities. Mutually exclusive with scopes."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "description": "Management API v1 scope ids to grant. Must be known, grantable, and held by the minter. Mutually exclusive with caps."
          },
          "expiresInDays": {
            "type": "integer",
            "minimum": 1,
            "description": "Days until expiry; omitted = the 90-day default. Mutually exclusive with neverExpires."
          },
          "neverExpires": {
            "type": "boolean",
            "description": "Explicit opt-out of expiry."
          }
        },
        "oneOf": [
          {
            "required": [
              "caps"
            ]
          },
          {
            "required": [
              "scopes"
            ]
          }
        ],
        "additionalProperties": false
      },
      "AdminApiKeyMintResponse": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The raw `aak_…` token. Shown exactly once; never retrievable again.",
            "example": "aak_synthetic-1234567890"
          },
          "record": {
            "$ref": "#/components/schemas/AdminApiKeyRecord"
          }
        },
        "required": [
          "key",
          "record"
        ]
      },
      "AdminApiKeyListResponse": {
        "type": "object",
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminApiKeyRecord"
            }
          }
        },
        "required": [
          "keys"
        ]
      },
      "UserCapPatch": {
        "type": "object",
        "description": "Partial edit of one user's cap entry: an omitted field is kept, null clears it, a value replaces it. Unknown fields are rejected; alert settings are unreachable from this route.",
        "properties": {
          "monthlyTokens": {
            "type": "integer",
            "minimum": 1,
            "nullable": true
          },
          "maxUsd": {
            "type": "number",
            "minimum": 0,
            "nullable": true
          },
          "softUsd": {
            "type": "number",
            "minimum": 0,
            "nullable": true
          },
          "reset": {
            "type": "string",
            "enum": [
              "never",
              "daily",
              "weekly",
              "monthly"
            ],
            "nullable": true
          },
          "expectedRevision": {
            "type": "string",
            "description": "Makes the write conditional; a stale revision returns 409. Omitted, a lost race is retried internally."
          }
        },
        "additionalProperties": false
      },
      "ApiError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "request_id"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine code: `unauthenticated`, `insufficient_scope`, `deployment_scope_required`, `invalid_request`, `not_found`, `conflict`, `rate_limited`, `unavailable`, or a legacy reason code such as `key_unknown` / `admin_key_store_unavailable`."
              },
              "message": {
                "type": "string",
                "description": "Fixed, content-free explanation."
              },
              "hint": {
                "type": "string",
                "description": "Safe remediation hint, when one exists."
              },
              "required_scope": {
                "type": "string",
                "description": "On `insufficient_scope`: the scope the caller must hold."
              },
              "request_id": {
                "type": "string",
                "description": "Echo of the response's `x-request-id`, for support correlation."
              }
            }
          }
        },
        "additionalProperties": true
      },
      "McpHubSyncCounts": {
        "type": "object",
        "description": "Counts from the last connector-mirror round. Tools counts only the shared authless set; personal OAuth tools are caller-specific and excluded.",
        "required": [
          "connectors",
          "tools",
          "failed"
        ],
        "properties": {
          "connectors": {
            "type": "integer",
            "minimum": 0
          },
          "tools": {
            "type": "integer",
            "minimum": 0
          },
          "failed": {
            "type": "integer",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "McpHubLegTimingSummary": {
        "type": "object",
        "description": "Process-local, content-free wall-time samples for one closed hub operation.",
        "required": [
          "samples",
          "p50Ms",
          "p95Ms",
          "lastOutcome"
        ],
        "properties": {
          "samples": {
            "type": "integer",
            "minimum": 0,
            "maximum": 128
          },
          "p50Ms": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          },
          "p95Ms": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          },
          "lastOutcome": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "success",
                  "http_4xx",
                  "http_5xx",
                  "http_other",
                  "timeout",
                  "network",
                  "invalid_response",
                  "unconfigured",
                  "not_ready",
                  "internal"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "McpHubTimingSummary": {
        "type": "object",
        "description": "Recent timing samples on this gateway replica. The snapshot resets when the replica restarts.",
        "required": [
          "hubCall",
          "oauthFetchTools",
          "oauthAuthorize",
          "refreshTools",
          "relay"
        ],
        "properties": {
          "hubCall": {
            "$ref": "#/components/schemas/McpHubLegTimingSummary"
          },
          "oauthFetchTools": {
            "$ref": "#/components/schemas/McpHubLegTimingSummary"
          },
          "oauthAuthorize": {
            "$ref": "#/components/schemas/McpHubLegTimingSummary"
          },
          "refreshTools": {
            "$ref": "#/components/schemas/McpHubLegTimingSummary"
          },
          "relay": {
            "$ref": "#/components/schemas/McpHubLegTimingSummary"
          }
        },
        "additionalProperties": false
      },
      "McpHubSummary": {
        "type": "object",
        "description": "Content-free status of the organization MCP relay on this gateway replica.",
        "required": [
          "configured",
          "syncing",
          "lastSyncAt",
          "lastSyncOk",
          "lastSyncCounts",
          "timings"
        ],
        "properties": {
          "configured": {
            "type": "boolean"
          },
          "syncing": {
            "type": "boolean"
          },
          "lastSyncAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastSyncOk": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "lastSyncCounts": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/McpHubSyncCounts"
              },
              {
                "type": "null"
              }
            ]
          },
          "timings": {
            "$ref": "#/components/schemas/McpHubTimingSummary"
          }
        },
        "additionalProperties": false
      },
      "McpHubSyncResponse": {
        "type": "object",
        "required": [
          "mcpHub"
        ],
        "properties": {
          "mcpHub": {
            "$ref": "#/components/schemas/McpHubSummary"
          }
        },
        "additionalProperties": false
      },
      "McpProbeResult": {
        "type": "object",
        "description": "What a remote MCP server said when the gateway asked. `needs-auth` is distinct from an empty `ok`, and from `forbidden`: a 401 can be fixed by authorization, while a 403 requires a vendor-side access change.",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "needs-auth",
              "forbidden",
              "unreachable"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The server's own `serverInfo.name`, else null. Present on `ok`, `needs-auth`, and `forbidden`."
          },
          "version": {
            "type": [
              "string",
              "null"
            ],
            "description": "Present on `ok`."
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tool names the server listed, capped at 200. Present on `ok`."
          },
          "truncated": {
            "type": "boolean",
            "description": "The server listed more tools than were returned."
          },
          "auth": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/McpAuthDiscovery"
              },
              {
                "type": "null"
              }
            ],
            "description": "OAuth discovery from a 401 Bearer challenge. Present on `needs-auth`."
          },
          "reason": {
            "type": "string",
            "enum": [
              "invalid-url",
              "blocked",
              "too-large",
              "redirected",
              "timeout",
              "unreachable",
              "not-mcp",
              "server-error"
            ],
            "description": "Present on `unreachable`."
          }
        }
      },
      "McpAuthDiscovery": {
        "type": "object",
        "description": "Metadata learned from the OAuth Bearer challenge without reading MCP request or response content.",
        "required": [
          "authorizationServer",
          "scopes",
          "registration",
          "resource",
          "resourceMismatch",
          "discovery"
        ],
        "properties": {
          "authorizationServer": {
            "type": [
              "string",
              "null"
            ],
            "description": "Authorization-server issuer named by protected-resource metadata."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Scopes from the Bearer challenge, or `scopes_supported` when it omitted them."
          },
          "registration": {
            "type": "string",
            "enum": [
              "dcr",
              "cimd",
              "both",
              "none"
            ],
            "description": "Supported OAuth client-registration lanes."
          },
          "resource": {
            "type": [
              "string",
              "null"
            ],
            "description": "Canonical resource named by protected-resource metadata."
          },
          "resourceMismatch": {
            "type": "boolean",
            "description": "Whether the metadata resource has a different URL origin or pathname from the probed address."
          },
          "discovery": {
            "type": "string",
            "enum": [
              "ok",
              "no-challenge",
              "no-metadata",
              "metadata-unreadable",
              "slow"
            ],
            "description": "How far OAuth discovery progressed."
          }
        }
      }
    }
  }
}