{"openapi":"3.1.0","info":{"title":"Hooshyar Admin API","version":"1.0.0","description":"Versioned control-plane API for the Hooshyar AI Gateway."},"servers":[{"url":"https://console.example.com/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Automation token — `Authorization: Bearer hsk_…` (see /tokens)."}}},"security":[{"bearerAuth":[]}],"paths":{"/auth/whoami":{"get":{"operationId":"auth.whoami","summary":"Describe the calling principal and the operations it is allowed to call.","security":[{"bearerAuth":[]}],"x-required-role":"member","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"principal":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"user"},"id":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["member","viewer","admin","owner"]}},"required":["kind","id","email","role"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"token"},"id":{"type":"string"},"name":{"type":"string"},"tokenPrefix":{"type":"string"},"role":{"type":"string","enum":["member","viewer","admin","owner"]},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":["string","null"]}},"required":["kind","id","name","tokenPrefix","role","scopes","expiresAt"],"additionalProperties":false}]},"allowedOperations":{"type":"array","items":{"type":"string"}}},"required":["principal","allowedOperations"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}}},"/tokens":{"get":{"operationId":"tokens.list","summary":"List automation tokens (metadata only — never the secret or hash).","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"tokens:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"tokens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tokenPrefix":{"type":"string"},"role":{"type":"string","enum":["member","viewer","admin","owner"]},"scopes":{"type":"array","items":{"type":"string"}},"createdByUserId":{"type":["string","null"]},"createdAt":{"type":"string"},"expiresAt":{"type":["string","null"]},"lastUsedAt":{"type":["string","null"]},"revokedAt":{"type":["string","null"]}},"required":["id","name","tokenPrefix","role","scopes","createdByUserId","createdAt","expiresAt","lastUsedAt","revokedAt"],"additionalProperties":false}}},"required":["tokens"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"tokens.mint","summary":"Mint an automation token; the plaintext secret is returned ONCE and never again.","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"tokens:write","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"token":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tokenPrefix":{"type":"string"},"role":{"type":"string","enum":["member","viewer","admin","owner"]},"scopes":{"type":"array","items":{"type":"string"}},"createdByUserId":{"type":["string","null"]},"createdAt":{"type":"string"},"expiresAt":{"type":["string","null"]},"lastUsedAt":{"type":["string","null"]},"revokedAt":{"type":["string","null"]},"secret":{"type":"string"}},"required":["id","name","tokenPrefix","role","scopes","createdByUserId","createdAt","expiresAt","lastUsedAt","revokedAt","secret"],"additionalProperties":false}},"required":["token"],"additionalProperties":false}}},"headers":{"Idempotency-Replayed":{"description":"`true` when this response was replayed from a previously recorded `Idempotency-Key` rather than produced by this call.","schema":{"type":"boolean"}}}},"400":{"description":"Invalid request — schema violation or a rejected value. Also `code: idempotency_key_required` when the `Idempotency-Key` header is absent, and `idempotency_key_invalid` when it is malformed."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"409":{"description":"Either another request with this `Idempotency-Key` is still in progress (`code: idempotency_in_progress`, body carries `retryAfterSeconds`), or it already succeeded and its response is not replayable because it carried a secret (`code: idempotency_result_not_replayable`, body carries `resourceId`). Nothing was performed a second time in either case."},"410":{"description":"The key is known but its response is no longer stored (replay window: 24h). Check current state and use a new key."},"422":{"description":"This `Idempotency-Key` was already used for a DIFFERENT request (`code: idempotency_key_reused`). Use a new key — note the `If-Match` version, the query and the body are all part of the request the key names."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-idempotency":"required","x-idempotency-replay":"outcome-only","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"A unique key identifying THIS attempt, so a retry cannot perform the operation twice. Generate one per logical invocation (a UUID) and reuse it across transport retries — never regenerate it when retrying, which defeats the purpose. The If-Match version, query and body are all part of the request the key names: change any of them and you need a new key.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,255}$","minLength":8,"maxLength":255,"examples":["3f1a9c52-7b0e-4a1d-9f2c-8e6d4b0a1c37"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1},"role":{"type":"string","enum":["viewer","admin","owner"]},"scopes":{"type":"array","items":{"type":"string","enum":["config:read","config:write","config:apply","keys:read","keys:write","tokens:read","tokens:write","users:read","users:write","providers:read","providers:write","alerts:read","alerts:write","usage:read","reports:write","audit:read","logs:read","guardrails:activity:read","guardrails:read","guardrails:test","retention:read","subscription_lane:read","tools:read","connections:read","packs:read","skills:read"]}},"expiresAt":{"type":["string","null"]}},"required":["name","role"]}}}}}},"/tokens/{id}":{"delete":{"operationId":"tokens.revoke","summary":"Revoke an automation token (idempotent — it stops authenticating immediately).","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"tokens:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-retry-safe":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/config":{"get":{"operationId":"config.read","summary":"Read the routing config as a declarative, round-trippable document.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"config:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"document":{"type":"object","properties":{"schemaVersion":{"type":"number","const":1},"defaultRoute":{"type":"string"},"classifier":{"type":"object","properties":{"confidenceThreshold":{"type":"number"},"semanticEnabled":{"type":"boolean"},"encoder":{"type":"string"},"llmFallbackEnabled":{"type":"boolean"},"llmFallbackModel":{"type":["string","null"]}},"required":["confidenceThreshold","semanticEnabled","encoder","llmFallbackEnabled","llmFallbackModel"],"additionalProperties":false},"routes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"model":{"type":"string"},"fallbacks":{"type":"array","items":{"type":"string"}},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"enabled":{"type":"boolean"},"requireZdr":{"default":false,"type":"boolean"},"packBudgetTokens":{"default":null,"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"utterances":{"type":"array","items":{"type":"string"}}},"required":["name","model","fallbacks","params","enabled","requireZdr","packBudgetTokens","utterances"],"additionalProperties":false}}},"required":["schemaVersion","defaultRoute","classifier","routes"],"additionalProperties":false},"version":{"type":"number"},"hash":{"type":"string"}},"required":["document","version","hash"],"additionalProperties":false}}},"headers":{"ETag":{"description":"Current `config_version`, quoted — pass it back as `If-Match` on the next config write.","schema":{"type":"string"}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-concurrency":"config-version"},"put":{"operationId":"config.apply","summary":"Apply a whole config document declaratively — routes absent from it are deleted.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"config:apply","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"applied":{"type":"boolean"},"version":{"type":"number"},"diff":{"type":"object","properties":{"routes":{"type":"object","properties":{"added":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}},"changed":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"from":{},"to":{}},"required":["field","from","to"],"additionalProperties":false}},"utterances":{"type":"object","properties":{"added":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}}},"required":["added","removed"],"additionalProperties":false},"utterancesReordered":{"type":"boolean"}},"required":["name","fields","utterances","utterancesReordered"],"additionalProperties":false}}},"required":["added","removed","changed"],"additionalProperties":false},"defaultRoute":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"from":{},"to":{}},"required":["field","from","to"],"additionalProperties":false},{"type":"null"}]},"classifier":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"from":{},"to":{}},"required":["field","from","to"],"additionalProperties":false}},"empty":{"type":"boolean"}},"required":["routes","defaultRoute","classifier","empty"],"additionalProperties":false}},"required":["ok","applied","version","diff"],"additionalProperties":false}}},"headers":{"ETag":{"description":"Current `config_version`, quoted — pass it back as `If-Match` on the next config write.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"`true` when this response was replayed from a previously recorded `Idempotency-Key` rather than produced by this call.","schema":{"type":"boolean"}}}},"400":{"description":"Invalid request — schema violation or a rejected value. Also `code: idempotency_key_required` when the `Idempotency-Key` header is absent, and `idempotency_key_invalid` when it is malformed."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"409":{"description":"Either another request with this `Idempotency-Key` is still in progress (`code: idempotency_in_progress`, body carries `retryAfterSeconds`), or it already succeeded and its response is not replayable because it carried a secret (`code: idempotency_result_not_replayable`, body carries `resourceId`). Nothing was performed a second time in either case."},"410":{"description":"The key is known but its response is no longer stored (replay window: 24h). Check current state and use a new key."},"412":{"description":"Precondition failed — the config changed since the declared version; nothing was applied. Body carries `currentVersion`."},"422":{"description":"This `Idempotency-Key` was already used for a DIFFERENT request (`code: idempotency_key_reused`). Use a new key — note the `If-Match` version, the query and the body are all part of the request the key names."},"428":{"description":"Precondition required — `If-Match` was not supplied."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-concurrency":"config-version","x-idempotency":"required","x-idempotency-replay":"response","parameters":[{"name":"allow_deletions","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}},{"name":"If-Match","in":"header","required":true,"description":"The `config_version` this edit is based on (the `ETag` from a prior read), quoted — e.g. `\"7\"`. The write is applied only if that is still the stored version. `*` applies unconditionally, overwriting any concurrent change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"A unique key identifying THIS attempt, so a retry cannot perform the operation twice. Generate one per logical invocation (a UUID) and reuse it across transport retries — never regenerate it when retrying, which defeats the purpose. The If-Match version, query and body are all part of the request the key names: change any of them and you need a new key.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,255}$","minLength":8,"maxLength":255,"examples":["3f1a9c52-7b0e-4a1d-9f2c-8e6d4b0a1c37"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schemaVersion":{"type":"number","const":1},"defaultRoute":{"type":"string"},"classifier":{"type":"object","properties":{"confidenceThreshold":{"type":"number"},"semanticEnabled":{"type":"boolean"},"encoder":{"type":"string"},"llmFallbackEnabled":{"type":"boolean"},"llmFallbackModel":{"type":["string","null"]}},"required":["confidenceThreshold","semanticEnabled","encoder","llmFallbackEnabled","llmFallbackModel"]},"routes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"model":{"type":"string"},"fallbacks":{"type":"array","items":{"type":"string"}},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"enabled":{"type":"boolean"},"requireZdr":{"default":false,"type":"boolean"},"packBudgetTokens":{"default":null,"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"utterances":{"type":"array","items":{"type":"string"}}},"required":["name","model","fallbacks","params","enabled","utterances"]}}},"required":["schemaVersion","defaultRoute","classifier","routes"]}}}}}},"/config/validate":{"post":{"operationId":"config.validate","summary":"Dry-run a config document: diagnostics plus a structured diff against the live config.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"config:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"valid":{"type":"boolean"},"diagnostics":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning"]},"code":{"type":"string"},"path":{"type":"string"},"message":{"type":"string"}},"required":["severity","code","path","message"],"additionalProperties":false}},"diff":{"type":"object","properties":{"routes":{"type":"object","properties":{"added":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}},"changed":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"from":{},"to":{}},"required":["field","from","to"],"additionalProperties":false}},"utterances":{"type":"object","properties":{"added":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}}},"required":["added","removed"],"additionalProperties":false},"utterancesReordered":{"type":"boolean"}},"required":["name","fields","utterances","utterancesReordered"],"additionalProperties":false}}},"required":["added","removed","changed"],"additionalProperties":false},"defaultRoute":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"from":{},"to":{}},"required":["field","from","to"],"additionalProperties":false},{"type":"null"}]},"classifier":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"from":{},"to":{}},"required":["field","from","to"],"additionalProperties":false}},"empty":{"type":"boolean"}},"required":["routes","defaultRoute","classifier","empty"],"additionalProperties":false},"baseVersion":{"type":"number"},"documentHash":{"type":"string"},"catalogChecked":{"type":"boolean"}},"required":["valid","diagnostics","diff","baseVersion","documentHash","catalogChecked"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schemaVersion":{"type":"number","const":1},"defaultRoute":{"type":"string"},"classifier":{"type":"object","properties":{"confidenceThreshold":{"type":"number"},"semanticEnabled":{"type":"boolean"},"encoder":{"type":"string"},"llmFallbackEnabled":{"type":"boolean"},"llmFallbackModel":{"type":["string","null"]}},"required":["confidenceThreshold","semanticEnabled","encoder","llmFallbackEnabled","llmFallbackModel"]},"routes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"model":{"type":"string"},"fallbacks":{"type":"array","items":{"type":"string"}},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"enabled":{"type":"boolean"},"requireZdr":{"default":false,"type":"boolean"},"packBudgetTokens":{"default":null,"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"utterances":{"type":"array","items":{"type":"string"}}},"required":["name","model","fallbacks","params","enabled","utterances"]}}},"required":["schemaVersion","defaultRoute","classifier","routes"]}}}}}},"/config/generations":{"get":{"operationId":"config.generations.list","summary":"List the routing-config history, newest first: one entry per change to the document.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"config:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generations":{"type":"array","items":{"type":"object","properties":{"version":{"type":"number"},"hash":{"type":"string"},"source":{"type":"string","enum":["baseline","route.upsert","route.delete","utterances.replace","settings.update","config.apply"]},"createdAt":{"type":"string"},"routeCount":{"type":"number"}},"required":["version","hash","source","createdAt","routeCount"],"additionalProperties":false}},"next":{"type":["number","null"]}},"required":["generations","next"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"before","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}]}},"/config/generations/{version}":{"get":{"operationId":"config.generations.read","summary":"Read one past routing-config state as a document, ready to validate and apply back.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"config:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"version":{"type":"number"},"hash":{"type":"string"},"source":{"type":"string","enum":["baseline","route.upsert","route.delete","utterances.replace","settings.update","config.apply"]},"createdAt":{"type":"string"},"routeCount":{"type":"number"},"document":{"type":"object","properties":{"schemaVersion":{"type":"number","const":1},"defaultRoute":{"type":"string"},"classifier":{"type":"object","properties":{"confidenceThreshold":{"type":"number"},"semanticEnabled":{"type":"boolean"},"encoder":{"type":"string"},"llmFallbackEnabled":{"type":"boolean"},"llmFallbackModel":{"type":["string","null"]}},"required":["confidenceThreshold","semanticEnabled","encoder","llmFallbackEnabled","llmFallbackModel"],"additionalProperties":false},"routes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"model":{"type":"string"},"fallbacks":{"type":"array","items":{"type":"string"}},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"enabled":{"type":"boolean"},"requireZdr":{"default":false,"type":"boolean"},"packBudgetTokens":{"default":null,"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"utterances":{"type":"array","items":{"type":"string"}}},"required":["name","model","fallbacks","params","enabled","requireZdr","packBudgetTokens","utterances"],"additionalProperties":false}}},"required":["schemaVersion","defaultRoute","classifier","routes"],"additionalProperties":false}},"required":["version","hash","source","createdAt","routeCount","document"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"version","in":"path","required":true,"schema":{"type":"string"}}]}},"/config/routes/{name}":{"put":{"operationId":"config.route.upsert","summary":"Create or update one route (model, fallbacks, params, enabled).","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"config:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"created":{"type":"boolean"}},"required":["ok","created"],"additionalProperties":false}}},"headers":{"ETag":{"description":"Current `config_version`, quoted — pass it back as `If-Match` on the next config write.","schema":{"type":"string"}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"412":{"description":"Precondition failed — the config changed since the declared version; nothing was applied. Body carries `currentVersion`."},"428":{"description":"Precondition required — `If-Match` was not supplied."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-concurrency":"config-version","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-Match","in":"header","required":true,"description":"The `config_version` this edit is based on (the `ETag` from a prior read), quoted — e.g. `\"7\"`. The write is applied only if that is still the stored version. `*` applies unconditionally, overwriting any concurrent change.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"model":{"type":"string","minLength":1},"fallbacks":{"default":[],"type":"array","items":{"type":"string"}},"params":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"enabled":{"default":true,"type":"boolean"},"requireZdr":{"default":false,"type":"boolean"},"packBudgetTokens":{"default":null,"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["model"]}}}}},"delete":{"operationId":"config.route.delete","summary":"Delete one route and its utterance examples.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"config:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}},"headers":{"ETag":{"description":"Current `config_version`, quoted — pass it back as `If-Match` on the next config write.","schema":{"type":"string"}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"412":{"description":"Precondition failed — the config changed since the declared version; nothing was applied. Body carries `currentVersion`."},"428":{"description":"Precondition required — `If-Match` was not supplied."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-concurrency":"config-version","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-Match","in":"header","required":true,"description":"The `config_version` this edit is based on (the `ETag` from a prior read), quoted — e.g. `\"7\"`. The write is applied only if that is still the stored version. `*` applies unconditionally, overwriting any concurrent change.","schema":{"type":"string"}}]}},"/config/settings":{"put":{"operationId":"config.settings.update","summary":"Update the default route and/or the classifier settings.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"config:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}},"headers":{"ETag":{"description":"Current `config_version`, quoted — pass it back as `If-Match` on the next config write.","schema":{"type":"string"}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"412":{"description":"Precondition failed — the config changed since the declared version; nothing was applied. Body carries `currentVersion`."},"428":{"description":"Precondition required — `If-Match` was not supplied."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-concurrency":"config-version","parameters":[{"name":"If-Match","in":"header","required":true,"description":"The `config_version` this edit is based on (the `ETag` from a prior read), quoted — e.g. `\"7\"`. The write is applied only if that is still the stored version. `*` applies unconditionally, overwriting any concurrent change.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"defaultRoute":{"type":"string","minLength":1},"classifier":{"type":"object","properties":{"confidenceThreshold":{"type":"number","minimum":0,"maximum":1},"semanticEnabled":{"type":"boolean"},"llmFallbackEnabled":{"type":"boolean"}}}}}}}}}},"/models":{"get":{"operationId":"models.list","summary":"List the chassis model catalog — the valid targets for a route.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"config:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"models":{"type":"array","items":{"type":"string"}}},"required":["models"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"models.create","summary":"Add a model to the chassis catalog. It must name an existing provider credential. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"config:write","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1},"providerModel":{"type":"string","minLength":1},"credentialName":{"default":"","type":"string"},"apiBase":{"type":"string"}},"required":["name","providerModel"]}}}}}},"/usage":{"get":{"operationId":"usage.report","summary":"Aggregate request usage grouped by one dimension over an optional date range.","security":[{"bearerAuth":[]}],"x-required-role":"member","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"groupBy":{"type":"string","enum":["route","model","user","tag","key","channel","client","session","subject"]},"from":{"type":["string","null"]},"to":{"type":["string","null"]},"rows":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string"},"requests":{"type":"number"},"promptTokens":{"type":"number"},"completionTokens":{"type":"number"},"totalTokens":{"type":"number"},"cachedTokens":{"type":"number"},"avgLatencyMs":{"type":"number"},"p95LatencyMs":{"type":"number"},"avgTtftMs":{"type":["number","null"]},"costUsd":{"type":"number"},"unpricedRequests":{"type":"number"},"subscriptionRequests":{"type":"number"},"imageCount":{"type":"number"},"audioSeconds":{"type":"number"},"characters":{"type":"number"},"documents":{"type":"number"},"subjectName":{"type":["string","null"]}},"required":["group","requests","promptTokens","completionTokens","totalTokens","cachedTokens","avgLatencyMs","p95LatencyMs","avgTtftMs","costUsd","unpricedRequests","subscriptionRequests","imageCount","audioSeconds","characters","documents","subjectName"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["groupBy","from","to","rows","truncated"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"group_by","in":"query","required":false,"schema":{"default":"route","type":"string","enum":["route","model","user","tag","key","channel","client","session","subject"]}},{"name":"from","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"to","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"default":500,"type":"integer","minimum":1,"maximum":5000}},{"name":"channel","in":"query","required":false,"schema":{"type":"string","enum":["api","subscription"]}}]}},"/reports/run":{"post":{"operationId":"reports.run","summary":"Run one report (a built-in or saved report by id, or a draft spec) for the caller.","security":[{"bearerAuth":[]}],"x-required-role":"member","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":["string","null"]},"title":{"type":["string","null"]},"result":{"type":"object","properties":{"spec":{"type":"object","properties":{"source":{"type":"string","enum":["requests","tool_calls","agent_metrics","outcomes"]},"dimensions":{"maxItems":2,"type":"array","items":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]}},"measures":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]}},"filters":{"type":"object","propertyNames":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]},"additionalProperties":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"range":{"anyOf":[{"type":"string","enum":["7d","30d","mtd","last_month"]},{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false}]},"compare":{"type":"string","enum":["none","previous_period"]},"view":{"type":"string","enum":["table","bar","line","stacked","waterfall"]}},"required":["source","dimensions","measures","filters","range","compare","view"],"additionalProperties":false},"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false},"previousWindow":{"anyOf":[{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false},{"type":"null"}]},"rows":{"type":"array","items":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"string"}},"current":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"delta":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"floor":{"type":"boolean"},"previousFloor":{"type":"boolean"}},"required":["groups","current","previous","delta","floor","previousFloor"],"additionalProperties":false}},"total":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"string"}},"current":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"delta":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"floor":{"type":"boolean"},"previousFloor":{"type":"boolean"}},"required":["groups","current","previous","delta","floor","previousFloor"],"additionalProperties":false},"decomposition":{"anyOf":[{"type":"object","properties":{"previousUsd":{"type":"number"},"currentUsd":{"type":"number"},"deltaUsd":{"type":"number"},"parts":{"type":"object","properties":{"users":{"type":"number"},"requestsPerUser":{"type":"number"},"inputTokensPerRequest":{"type":"number"},"outputTokensPerRequest":{"type":"number"},"pricePerToken":{"type":"number"}},"required":["users","requestsPerUser","inputTokensPerRequest","outputTokensPerRequest","pricePerToken"],"additionalProperties":false},"unmodelledUsd":{"type":"number"},"floor":{"type":"boolean"}},"required":["previousUsd","currentUsd","deltaUsd","parts","unmodelledUsd","floor"],"additionalProperties":false},{"type":"null"}]},"coverage":{"anyOf":[{"type":"object","properties":{"dimensionsSince":{"type":["string","null"]},"rowsBefore":{"type":"number"},"previousRowsBefore":{"type":["number","null"]}},"required":["dimensionsSince","rowsBefore","previousRowsBefore"],"additionalProperties":false},{"type":"null"}]}},"required":["spec","window","previousWindow","rows","total","decomposition","coverage"],"additionalProperties":false},"rowCount":{"type":"number"},"truncated":{"type":"boolean"}},"required":["id","title","result","rowCount","truncated"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"spec":{"type":"object","properties":{"source":{"type":"string","enum":["requests","tool_calls","agent_metrics","outcomes"]},"dimensions":{"maxItems":2,"type":"array","items":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]}},"measures":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]}},"filters":{"type":"object","propertyNames":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]},"additionalProperties":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"range":{"anyOf":[{"type":"string","enum":["7d","30d","mtd","last_month"]},{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"]}]},"compare":{"type":"string","enum":["none","previous_period"]},"view":{"type":"string","enum":["table","bar","line","stacked","waterfall"]}},"required":["source","dimensions","measures","filters","range","compare","view"]},"limit":{"default":500,"type":"integer","minimum":1,"maximum":5000}}}}}}}},"/reports":{"get":{"operationId":"reports.list","summary":"List the reports the caller may open: built-in, their own, and shared with their role.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"builtIn":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["built_in","saved"]},"id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"spec":{"type":"object","properties":{"source":{"type":"string","enum":["requests","tool_calls","agent_metrics","outcomes"]},"dimensions":{"maxItems":2,"type":"array","items":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]}},"measures":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]}},"filters":{"type":"object","propertyNames":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]},"additionalProperties":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"range":{"anyOf":[{"type":"string","enum":["7d","30d","mtd","last_month"]},{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false}]},"compare":{"type":"string","enum":["none","previous_period"]},"view":{"type":"string","enum":["table","bar","line","stacked","waterfall"]}},"required":["source","dimensions","measures","filters","range","compare","view"],"additionalProperties":false},"ownerEmail":{"type":["string","null"]},"visibility":{"type":"string","enum":["private","role:viewer","role:admin","role:owner"]},"pinned":{"type":"boolean"},"editable":{"type":"boolean"},"updatedAt":{"type":["string","null"]}},"required":["kind","id","title","description","spec","ownerEmail","visibility","pinned","editable","updatedAt"],"additionalProperties":false}},"mine":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["built_in","saved"]},"id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"spec":{"type":"object","properties":{"source":{"type":"string","enum":["requests","tool_calls","agent_metrics","outcomes"]},"dimensions":{"maxItems":2,"type":"array","items":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]}},"measures":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]}},"filters":{"type":"object","propertyNames":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]},"additionalProperties":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"range":{"anyOf":[{"type":"string","enum":["7d","30d","mtd","last_month"]},{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false}]},"compare":{"type":"string","enum":["none","previous_period"]},"view":{"type":"string","enum":["table","bar","line","stacked","waterfall"]}},"required":["source","dimensions","measures","filters","range","compare","view"],"additionalProperties":false},"ownerEmail":{"type":["string","null"]},"visibility":{"type":"string","enum":["private","role:viewer","role:admin","role:owner"]},"pinned":{"type":"boolean"},"editable":{"type":"boolean"},"updatedAt":{"type":["string","null"]}},"required":["kind","id","title","description","spec","ownerEmail","visibility","pinned","editable","updatedAt"],"additionalProperties":false}},"shared":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["built_in","saved"]},"id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"spec":{"type":"object","properties":{"source":{"type":"string","enum":["requests","tool_calls","agent_metrics","outcomes"]},"dimensions":{"maxItems":2,"type":"array","items":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]}},"measures":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]}},"filters":{"type":"object","propertyNames":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]},"additionalProperties":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"range":{"anyOf":[{"type":"string","enum":["7d","30d","mtd","last_month"]},{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false}]},"compare":{"type":"string","enum":["none","previous_period"]},"view":{"type":"string","enum":["table","bar","line","stacked","waterfall"]}},"required":["source","dimensions","measures","filters","range","compare","view"],"additionalProperties":false},"ownerEmail":{"type":["string","null"]},"visibility":{"type":"string","enum":["private","role:viewer","role:admin","role:owner"]},"pinned":{"type":"boolean"},"editable":{"type":"boolean"},"updatedAt":{"type":["string","null"]}},"required":["kind","id","title","description","spec","ownerEmail","visibility","pinned","editable","updatedAt"],"additionalProperties":false}}},"required":["builtIn","mine","shared"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"reports.save","summary":"Save a report for the caller: create one, or replace one they own. It stores the question, never the figures.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"reports:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"report":{"type":"object","properties":{"kind":{"type":"string","enum":["built_in","saved"]},"id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"spec":{"type":"object","properties":{"source":{"type":"string","enum":["requests","tool_calls","agent_metrics","outcomes"]},"dimensions":{"maxItems":2,"type":"array","items":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]}},"measures":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]}},"filters":{"type":"object","propertyNames":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]},"additionalProperties":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"range":{"anyOf":[{"type":"string","enum":["7d","30d","mtd","last_month"]},{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false}]},"compare":{"type":"string","enum":["none","previous_period"]},"view":{"type":"string","enum":["table","bar","line","stacked","waterfall"]}},"required":["source","dimensions","measures","filters","range","compare","view"],"additionalProperties":false},"ownerEmail":{"type":["string","null"]},"visibility":{"type":"string","enum":["private","role:viewer","role:admin","role:owner"]},"pinned":{"type":"boolean"},"editable":{"type":"boolean"},"updatedAt":{"type":["string","null"]}},"required":["kind","id","title","description","spec","ownerEmail","visibility","pinned","editable","updatedAt"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["report","created"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"spec":{"type":"object","properties":{"source":{"type":"string","enum":["requests","tool_calls","agent_metrics","outcomes"]},"dimensions":{"maxItems":2,"type":"array","items":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]}},"measures":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]}},"filters":{"type":"object","propertyNames":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]},"additionalProperties":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"range":{"anyOf":[{"type":"string","enum":["7d","30d","mtd","last_month"]},{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"]}]},"compare":{"type":"string","enum":["none","previous_period"]},"view":{"type":"string","enum":["table","bar","line","stacked","waterfall"]}},"required":["source","dimensions","measures","filters","range","compare","view"]},"visibility":{"default":"private","type":"string","enum":["private","role:viewer","role:admin","role:owner"]},"pinned":{"default":false,"type":"boolean"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["title","spec"]}}}}}},"/usage/series":{"get":{"operationId":"usage.series","summary":"Read usage per hour or day: requests, tokens, cost, and latency and time-to-first-token percentiles.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"bucket":{"type":"string","enum":["hour","day"]},"from":{"type":["string","null"]},"to":{"type":["string","null"]},"points":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string"},"requests":{"type":"number"},"totalTokens":{"type":"number"},"cachedTokens":{"type":"number"},"costUsd":{"type":"number"},"avgLatencyMs":{"type":"number"},"p50LatencyMs":{"type":"number"},"p95LatencyMs":{"type":"number"},"p50TtftMs":{"type":["number","null"]},"p95TtftMs":{"type":["number","null"]}},"required":["bucket","requests","totalTokens","cachedTokens","costUsd","avgLatencyMs","p50LatencyMs","p95LatencyMs","p50TtftMs","p95TtftMs"],"additionalProperties":false}}},"required":["bucket","from","to","points"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"bucket","in":"query","required":false,"schema":{"default":"day","type":"string","enum":["hour","day"]}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/usage/spend-split":{"get":{"operationId":"usage.spend-split","summary":"Read interactive and batch spend for one window, side by side. Only the money is added up.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"interactive":{"type":"object","properties":{"requests":{"type":"number"},"totalTokens":{"type":"number"},"costUsd":{"type":"number"},"unpricedRequests":{"type":"number"}},"required":["requests","totalTokens","costUsd","unpricedRequests"],"additionalProperties":false},"batch":{"type":"object","properties":{"batches":{"type":"number"},"logicalRequests":{"type":"number"},"totalTokens":{"type":"number"},"costUsd":{"type":"number"},"unpricedRows":{"type":"number"}},"required":["batches","logicalRequests","totalTokens","costUsd","unpricedRows"],"additionalProperties":false},"byModel":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"batches":{"type":"number"},"logicalRequests":{"type":"number"},"totalTokens":{"type":"number"},"cachedTokens":{"type":"number"},"costUsd":{"type":"number"},"unpricedRows":{"type":"number"}},"required":["model","batches","logicalRequests","totalTokens","cachedTokens","costUsd","unpricedRows"],"additionalProperties":false}},"combinedCostUsd":{"type":"number"},"caveat":{"type":"string"}},"required":["interactive","batch","byModel","combinedCostUsd","caveat"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/reports/executive":{"get":{"operationId":"reports.executive","summary":"Read the executive summary: spend, traffic, latency, top routes and models, and credit alerts.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]},"cost":{"type":"object","properties":{"usd":{"type":"number"},"unpricedRequests":{"type":"number"},"subscriptionRequests":{"type":"number"},"requests":{"type":"number"}},"required":["usd","unpricedRequests","subscriptionRequests","requests"],"additionalProperties":false},"requests":{"type":"number"},"totalTokens":{"type":"number"},"cachedTokens":{"type":"number"},"avgLatencyMs":{"type":"number"},"p95LatencyMs":{"type":"number"},"avgTtftMs":{"type":["number","null"]},"series":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string"},"requests":{"type":"number"},"totalTokens":{"type":"number"},"cachedTokens":{"type":"number"},"costUsd":{"type":"number"},"avgLatencyMs":{"type":"number"},"p50LatencyMs":{"type":"number"},"p95LatencyMs":{"type":"number"},"p50TtftMs":{"type":["number","null"]},"p95TtftMs":{"type":["number","null"]}},"required":["bucket","requests","totalTokens","cachedTokens","costUsd","avgLatencyMs","p50LatencyMs","p95LatencyMs","p50TtftMs","p95TtftMs"],"additionalProperties":false}},"topRoutes":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string"},"requests":{"type":"number"},"promptTokens":{"type":"number"},"completionTokens":{"type":"number"},"totalTokens":{"type":"number"},"cachedTokens":{"type":"number"},"avgLatencyMs":{"type":"number"},"p95LatencyMs":{"type":"number"},"avgTtftMs":{"type":["number","null"]},"costUsd":{"type":"number"},"unpricedRequests":{"type":"number"},"subscriptionRequests":{"type":"number"},"imageCount":{"type":"number"},"audioSeconds":{"type":"number"},"characters":{"type":"number"},"documents":{"type":"number"}},"required":["group","requests","promptTokens","completionTokens","totalTokens","cachedTokens","avgLatencyMs","p95LatencyMs","avgTtftMs","costUsd","unpricedRequests","subscriptionRequests","imageCount","audioSeconds","characters","documents"],"additionalProperties":false}},"topModels":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string"},"requests":{"type":"number"},"promptTokens":{"type":"number"},"completionTokens":{"type":"number"},"totalTokens":{"type":"number"},"cachedTokens":{"type":"number"},"avgLatencyMs":{"type":"number"},"p95LatencyMs":{"type":"number"},"avgTtftMs":{"type":["number","null"]},"costUsd":{"type":"number"},"unpricedRequests":{"type":"number"},"subscriptionRequests":{"type":"number"},"imageCount":{"type":"number"},"audioSeconds":{"type":"number"},"characters":{"type":"number"},"documents":{"type":"number"}},"required":["group","requests","promptTokens","completionTokens","totalTokens","cachedTokens","avgLatencyMs","p95LatencyMs","avgTtftMs","costUsd","unpricedRequests","subscriptionRequests","imageCount","audioSeconds","characters","documents"],"additionalProperties":false}},"activeKeys":{"type":"number"},"creditAlerts":{"type":"number"}},"required":["from","to","cost","requests","totalTokens","cachedTokens","avgLatencyMs","p95LatencyMs","avgTtftMs","series","topRoutes","topModels","activeKeys","creditAlerts"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/reports/team":{"get":{"operationId":"reports.team","summary":"Report usage per person, rolled up through key ownership, with an unassigned bucket.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":["string","null"]},"label":{"type":"string"},"email":{"type":["string","null"]},"role":{"anyOf":[{"type":"string","enum":["member","viewer","admin","owner"]},{"type":"null"}]},"keys":{"type":"array","items":{"type":"string"}},"requests":{"type":"number"},"totalTokens":{"type":"number"},"cachedTokens":{"type":"number"},"cost":{"type":"object","properties":{"usd":{"type":"number"},"unpricedRequests":{"type":"number"},"subscriptionRequests":{"type":"number"},"requests":{"type":"number"}},"required":["usd","unpricedRequests","subscriptionRequests","requests"],"additionalProperties":false},"avgLatencyMs":{"type":"number"}},"required":["userId","label","email","role","keys","requests","totalTokens","cachedTokens","cost","avgLatencyMs"],"additionalProperties":false}},"total":{"type":"object","properties":{"usd":{"type":"number"},"unpricedRequests":{"type":"number"},"subscriptionRequests":{"type":"number"},"requests":{"type":"number"}},"required":["usd","unpricedRequests","subscriptionRequests","requests"],"additionalProperties":false}},"required":["from","to","members","total"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/reports/providers":{"get":{"operationId":"reports.providers","summary":"Report spend per provider credential, against its declared limit, with live rate-limit headroom.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]},"rows":{"type":"array","items":{"type":"object","properties":{"credential":{"type":"string"},"provider":{"type":["string","null"]},"models":{"type":"array","items":{"type":"string"}},"requests":{"type":"number"},"totalTokens":{"type":"number"},"cost":{"type":"object","properties":{"usd":{"type":"number"},"unpricedRequests":{"type":"number"},"subscriptionRequests":{"type":"number"},"requests":{"type":"number"}},"required":["usd","unpricedRequests","subscriptionRequests","requests"],"additionalProperties":false},"limitUsd":{"type":["number","null"]},"limitPeriod":{"anyOf":[{"type":"string","enum":["month","30d"]},{"type":"null"}]},"windowCost":{"anyOf":[{"type":"object","properties":{"usd":{"type":"number"},"unpricedRequests":{"type":"number"},"subscriptionRequests":{"type":"number"},"requests":{"type":"number"}},"required":["usd","unpricedRequests","subscriptionRequests","requests"],"additionalProperties":false},{"type":"null"}]},"pctUsd":{"type":["number","null"]},"headroom":{"anyOf":[{"type":"object","properties":{"model":{"type":"string"},"pctLeft":{"type":"number"},"tokensRemaining":{"type":["number","null"]},"tokensLimit":{"type":["number","null"]},"requestsRemaining":{"type":["number","null"]},"requestsLimit":{"type":["number","null"]},"capturedAt":{"type":"string"}},"required":["model","pctLeft","tokensRemaining","tokensLimit","requestsRemaining","requestsLimit","capturedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["credential","provider","models","requests","totalTokens","cost","limitUsd","limitPeriod","windowCost","pctUsd","headroom"],"additionalProperties":false}},"unattributed":{"type":"object","properties":{"usd":{"type":"number"},"unpricedRequests":{"type":"number"},"subscriptionRequests":{"type":"number"},"requests":{"type":"number"}},"required":["usd","unpricedRequests","subscriptionRequests","requests"],"additionalProperties":false},"total":{"type":"object","properties":{"usd":{"type":"number"},"unpricedRequests":{"type":"number"},"subscriptionRequests":{"type":"number"},"requests":{"type":"number"}},"required":["usd","unpricedRequests","subscriptionRequests","requests"],"additionalProperties":false}},"required":["from","to","rows","unattributed","total"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/reports/developers":{"get":{"operationId":"reports.developers","summary":"Report each developer's Claude Code usage from the client's own telemetry. Estimates, never spend.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]},"developers":{"type":"array","items":{"type":"object","properties":{"developer":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"keyIds":{"type":"array","items":{"type":"string"}},"clients":{"type":"array","items":{"type":"string"}},"sessions":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"cacheReadTokens":{"type":"number"},"cacheCreationTokens":{"type":"number"},"totalTokens":{"type":"number"},"estimatedCostUsd":{"type":"number"},"linesAdded":{"type":"number"},"linesRemoved":{"type":"number"},"commits":{"type":"number"},"pullRequests":{"type":"number"},"activeSeconds":{"type":"number"},"models":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"totalTokens":{"type":"number"}},"required":["model","totalTokens"],"additionalProperties":false}},"gatewayRequests":{"type":"number"},"firstSeen":{"type":"string"},"lastSeen":{"type":"string"}},"required":["developer","name","email","keyIds","clients","sessions","inputTokens","outputTokens","cacheReadTokens","cacheCreationTokens","totalTokens","estimatedCostUsd","linesAdded","linesRemoved","commits","pullRequests","activeSeconds","models","gatewayRequests","firstSeen","lastSeen"],"additionalProperties":false}},"empty":{"type":"boolean"}},"required":["from","to","developers","empty"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/reports/hooks":{"get":{"operationId":"reports.hooks","summary":"Report what the managed Claude Code hooks decided: denials, unscreened work and screening outages.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]},"developers":{"type":"array","items":{"type":"object","properties":{"developer":{"type":"string"},"name":{"type":["string","null"]},"keyId":{"type":"string"},"events":{"type":"number"},"denials":{"type":"number"},"unscreened":{"type":"number"},"outages":{"type":"number"},"lastSeen":{"type":"string"}},"required":["developer","name","keyId","events","denials","unscreened","outages","lastSeen"],"additionalProperties":false}},"recent":{"type":"array","items":{"type":"object","properties":{"ts":{"type":"string"},"keyId":{"type":"string"},"sessionId":{"type":["string","null"]},"event":{"type":"string","enum":["UserPromptSubmit","PreToolUse","PostToolUse"]},"tool":{"type":["string","null"]},"decision":{"type":"string","enum":["allow","deny","audit"]},"screened":{"type":"boolean"},"guardAction":{"anyOf":[{"type":"string","enum":["allow","flag","block"]},{"type":"null"}]},"unscreenedReason":{"type":["string","null"]},"guards":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}},"latencyMs":{"type":["number","null"]},"attributes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean"]}}},"required":["ts","keyId","sessionId","event","tool","decision","screened","guardAction","unscreenedReason","guards","categories","latencyMs","attributes"],"additionalProperties":false}},"totalOutages":{"type":"number"},"totalDenials":{"type":"number"}},"required":["from","to","developers","recent","totalOutages","totalDenials"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/reports/economics":{"get":{"operationId":"reports.economics","summary":"Read cost economics: spend per client, model and tool, with the driver decomposition and the subscription lane.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"result":{"anyOf":[{"type":"object","properties":{"spec":{"type":"object","properties":{"source":{"type":"string","enum":["requests","tool_calls","agent_metrics","outcomes"]},"dimensions":{"maxItems":2,"type":"array","items":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]}},"measures":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]}},"filters":{"type":"object","propertyNames":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]},"additionalProperties":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"range":{"anyOf":[{"type":"string","enum":["7d","30d","mtd","last_month"]},{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false}]},"compare":{"type":"string","enum":["none","previous_period"]},"view":{"type":"string","enum":["table","bar","line","stacked","waterfall"]}},"required":["source","dimensions","measures","filters","range","compare","view"],"additionalProperties":false},"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false},"previousWindow":{"anyOf":[{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false},{"type":"null"}]},"rows":{"type":"array","items":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"string"}},"current":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"delta":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"floor":{"type":"boolean"},"previousFloor":{"type":"boolean"}},"required":["groups","current","previous","delta","floor","previousFloor"],"additionalProperties":false}},"total":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"string"}},"current":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"delta":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"floor":{"type":"boolean"},"previousFloor":{"type":"boolean"}},"required":["groups","current","previous","delta","floor","previousFloor"],"additionalProperties":false},"decomposition":{"anyOf":[{"type":"object","properties":{"previousUsd":{"type":"number"},"currentUsd":{"type":"number"},"deltaUsd":{"type":"number"},"parts":{"type":"object","properties":{"users":{"type":"number"},"requestsPerUser":{"type":"number"},"inputTokensPerRequest":{"type":"number"},"outputTokensPerRequest":{"type":"number"},"pricePerToken":{"type":"number"}},"required":["users","requestsPerUser","inputTokensPerRequest","outputTokensPerRequest","pricePerToken"],"additionalProperties":false},"unmodelledUsd":{"type":"number"},"floor":{"type":"boolean"}},"required":["previousUsd","currentUsd","deltaUsd","parts","unmodelledUsd","floor"],"additionalProperties":false},{"type":"null"}]},"coverage":{"anyOf":[{"type":"object","properties":{"dimensionsSince":{"type":["string","null"]},"rowsBefore":{"type":"number"},"previousRowsBefore":{"type":["number","null"]}},"required":["dimensionsSince","rowsBefore","previousRowsBefore"],"additionalProperties":false},{"type":"null"}]}},"required":["spec","window","previousWindow","rows","total","decomposition","coverage"],"additionalProperties":false},{"type":"null"}]}},"required":["id","title","description","result"],"additionalProperties":false}},"subscription":{"type":"object","properties":{"spec":{"type":"object","properties":{"source":{"type":"string","enum":["requests","tool_calls","agent_metrics","outcomes"]},"dimensions":{"maxItems":2,"type":"array","items":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]}},"measures":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]}},"filters":{"type":"object","propertyNames":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]},"additionalProperties":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"range":{"anyOf":[{"type":"string","enum":["7d","30d","mtd","last_month"]},{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false}]},"compare":{"type":"string","enum":["none","previous_period"]},"view":{"type":"string","enum":["table","bar","line","stacked","waterfall"]}},"required":["source","dimensions","measures","filters","range","compare","view"],"additionalProperties":false},"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false},"previousWindow":{"anyOf":[{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false},{"type":"null"}]},"rows":{"type":"array","items":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"string"}},"current":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"delta":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"floor":{"type":"boolean"},"previousFloor":{"type":"boolean"}},"required":["groups","current","previous","delta","floor","previousFloor"],"additionalProperties":false}},"total":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"string"}},"current":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"delta":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"floor":{"type":"boolean"},"previousFloor":{"type":"boolean"}},"required":["groups","current","previous","delta","floor","previousFloor"],"additionalProperties":false},"decomposition":{"anyOf":[{"type":"object","properties":{"previousUsd":{"type":"number"},"currentUsd":{"type":"number"},"deltaUsd":{"type":"number"},"parts":{"type":"object","properties":{"users":{"type":"number"},"requestsPerUser":{"type":"number"},"inputTokensPerRequest":{"type":"number"},"outputTokensPerRequest":{"type":"number"},"pricePerToken":{"type":"number"}},"required":["users","requestsPerUser","inputTokensPerRequest","outputTokensPerRequest","pricePerToken"],"additionalProperties":false},"unmodelledUsd":{"type":"number"},"floor":{"type":"boolean"}},"required":["previousUsd","currentUsd","deltaUsd","parts","unmodelledUsd","floor"],"additionalProperties":false},{"type":"null"}]},"coverage":{"anyOf":[{"type":"object","properties":{"dimensionsSince":{"type":["string","null"]},"rowsBefore":{"type":"number"},"previousRowsBefore":{"type":["number","null"]}},"required":["dimensionsSince","rowsBefore","previousRowsBefore"],"additionalProperties":false},{"type":"null"}]}},"required":["spec","window","previousWindow","rows","total","decomposition","coverage"],"additionalProperties":false},"agentEstimate":{"type":"object","properties":{"spec":{"type":"object","properties":{"source":{"type":"string","enum":["requests","tool_calls","agent_metrics","outcomes"]},"dimensions":{"maxItems":2,"type":"array","items":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]}},"measures":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]}},"filters":{"type":"object","propertyNames":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]},"additionalProperties":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"range":{"anyOf":[{"type":"string","enum":["7d","30d","mtd","last_month"]},{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false}]},"compare":{"type":"string","enum":["none","previous_period"]},"view":{"type":"string","enum":["table","bar","line","stacked","waterfall"]}},"required":["source","dimensions","measures","filters","range","compare","view"],"additionalProperties":false},"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false},"previousWindow":{"anyOf":[{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false},{"type":"null"}]},"rows":{"type":"array","items":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"string"}},"current":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"delta":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"floor":{"type":"boolean"},"previousFloor":{"type":"boolean"}},"required":["groups","current","previous","delta","floor","previousFloor"],"additionalProperties":false}},"total":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"string"}},"current":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"delta":{"anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]},"additionalProperties":{"type":["number","null"]}},{"type":"null"}]},"floor":{"type":"boolean"},"previousFloor":{"type":"boolean"}},"required":["groups","current","previous","delta","floor","previousFloor"],"additionalProperties":false},"decomposition":{"anyOf":[{"type":"object","properties":{"previousUsd":{"type":"number"},"currentUsd":{"type":"number"},"deltaUsd":{"type":"number"},"parts":{"type":"object","properties":{"users":{"type":"number"},"requestsPerUser":{"type":"number"},"inputTokensPerRequest":{"type":"number"},"outputTokensPerRequest":{"type":"number"},"pricePerToken":{"type":"number"}},"required":["users","requestsPerUser","inputTokensPerRequest","outputTokensPerRequest","pricePerToken"],"additionalProperties":false},"unmodelledUsd":{"type":"number"},"floor":{"type":"boolean"}},"required":["previousUsd","currentUsd","deltaUsd","parts","unmodelledUsd","floor"],"additionalProperties":false},{"type":"null"}]},"coverage":{"anyOf":[{"type":"object","properties":{"dimensionsSince":{"type":["string","null"]},"rowsBefore":{"type":"number"},"previousRowsBefore":{"type":["number","null"]}},"required":["dimensionsSince","rowsBefore","previousRowsBefore"],"additionalProperties":false},{"type":"null"}]}},"required":["spec","window","previousWindow","rows","total","decomposition","coverage"],"additionalProperties":false}},"required":["reports","subscription","agentEstimate"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","mtd","last_month"]}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}},{"name":"compare","in":"query","required":false,"schema":{"type":"string","enum":["none","previous_period"]}}]}},"/reports/tool-calls":{"get":{"operationId":"reports.tool-calls","summary":"Report tool calls through /mcp per tool, server, person or key: calls, outcomes, refusals, cost and latency.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"groupBy":{"type":"string","enum":["tool","server","person","key"]},"from":{"type":["string","null"]},"to":{"type":["string","null"]},"rows":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string"},"calls":{"type":"number"},"dispatched":{"type":"number"},"denied":{"type":"number"},"pending":{"type":"number"},"failed":{"type":"number"},"unknown":{"type":"number"},"costUsd":{"type":"number"},"unpricedCalls":{"type":"number"},"avgLatencyMs":{"type":["number","null"]},"p95LatencyMs":{"type":["number","null"]},"subjectName":{"type":["string","null"]}},"required":["group","calls","dispatched","denied","pending","failed","unknown","costUsd","unpricedCalls","avgLatencyMs","p95LatencyMs","subjectName"],"additionalProperties":false}}},"required":["groupBy","from","to","rows"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"group_by","in":"query","required":false,"schema":{"default":"tool","type":"string","enum":["tool","server","person","key"]}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/reports/agent-metrics":{"get":{"operationId":"reports.agent-metrics","summary":"Report the usage the agents reported themselves, per client, model, person, session, key or user. Never spend.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"groupBy":{"type":"string","enum":["client","model","subject","session","key","user"]},"from":{"type":["string","null"]},"to":{"type":["string","null"]},"rows":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string"},"operations":{"type":"number"},"operationSeconds":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"totalTokens":{"type":"number"},"sessions":{"type":"number"},"estimatedCostUsd":{"type":"number"},"subjectName":{"type":["string","null"]}},"required":["group","operations","operationSeconds","inputTokens","outputTokens","totalTokens","sessions","estimatedCostUsd","subjectName"],"additionalProperties":false}}},"required":["groupBy","from","to","rows"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"group_by","in":"query","required":false,"schema":{"default":"client","type":"string","enum":["client","model","subject","session","key","user"]}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/reports/security":{"get":{"operationId":"reports.security","summary":"Report security events: refused and failed requests, and the security-relevant audit entries.","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"audit:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]},"blocked":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"route":{"type":"string"},"keyId":{"type":"string"},"requests":{"type":"number"},"lastSeen":{"type":"string"}},"required":["status","route","keyId","requests","lastSeen"],"additionalProperties":false}},"counts":{"type":"object","properties":{"unauthorized":{"type":"number"},"forbidden":{"type":"number"},"rateLimited":{"type":"number"},"upstreamErrors":{"type":"number"}},"required":["unauthorized","forbidden","rateLimited","upstreamErrors"],"additionalProperties":false},"audit":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"ts":{"type":"string"},"actorType":{"type":"string","enum":["user","token"]},"actorUserId":{"type":["string","null"]},"actorEmail":{"type":["string","null"]},"actorTokenId":{"type":["string","null"]},"action":{"type":"string"},"resourceType":{"type":["string","null"]},"resourceId":{"type":["string","null"]},"before":{},"after":{},"ip":{"type":["string","null"]},"userAgent":{"type":["string","null"]},"reason":{"type":["string","null"]},"reasonCategory":{"type":["string","null"]}},"required":["id","ts","actorType","actorUserId","actorEmail","actorTokenId","action","resourceType","resourceId","before","after","ip","userAgent","reason","reasonCategory"],"additionalProperties":false}}},"required":["from","to","blocked","counts","audit"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/status":{"get":{"operationId":"status.read","summary":"Read each catalog model's health: up, degraded, down or unknown, with recent traffic, errors and latency.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"providerModel":{"type":"string"},"provider":{"type":"string"},"credential":{"type":["string","null"]},"state":{"type":"string","enum":["up","degraded","down","unknown"]},"probeHealthy":{"type":["boolean","null"]},"probeError":{"type":["string","null"]},"requests":{"type":"number"},"errorRate":{"type":["number","null"]},"avgLatencyMs":{"type":["number","null"]},"p95LatencyMs":{"type":["number","null"]}},"required":["model","providerModel","provider","credential","state","probeHealthy","probeError","requests","errorRate","avgLatencyMs","p95LatencyMs"],"additionalProperties":false}},"windowMinutes":{"type":"number"}},"required":["models","windowMinutes"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}}},"/batches":{"get":{"operationId":"batches.list","summary":"List batch jobs, newest first, each with its per-model usage ledger and deferred cost.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"batchId":{"type":"string"},"keyId":{"type":"string"},"endpoint":{"type":["string","null"]},"inputFileId":{"type":["string","null"]},"outputFileId":{"type":["string","null"]},"errorFileId":{"type":["string","null"]},"status":{"type":"string"},"requestCounts":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"submittedAt":{"type":"string"},"completedAt":{"type":["string","null"]},"reconciledAt":{"type":["string","null"]},"reconcileAttempts":{"type":"number"},"lastError":{"type":["string","null"]},"partial":{"type":"boolean"},"usage":{"type":"array","items":{"type":"object","properties":{"batchId":{"type":"string"},"model":{"type":"string"},"logicalRequests":{"type":"number"},"promptTokens":{"type":["number","null"]},"completionTokens":{"type":["number","null"]},"totalTokens":{"type":["number","null"]},"cachedTokens":{"type":["number","null"]},"costUsd":{"type":["number","null"]},"costSource":{"anyOf":[{"type":"string","enum":["upstream","catalog","catalog_interactive"]},{"type":"null"}]},"effectiveAt":{"type":"string"}},"required":["batchId","model","logicalRequests","promptTokens","completionTokens","totalTokens","cachedTokens","costUsd","costSource","effectiveAt"],"additionalProperties":false}}},"required":["batchId","keyId","endpoint","inputFileId","outputFileId","errorFileId","status","requestCounts","submittedAt","completedAt","reconciledAt","reconcileAttempts","lastError","partial","usage"],"additionalProperties":false}},"caveat":{"type":"string"}},"required":["rows","caveat"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":500}}]}},"/observability/metrics":{"get":{"operationId":"observability.metrics","summary":"Read daily request, token, cost and latency trends from Langfuse over a window (default: 14 days).","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"configured":{"type":"boolean"},"from":{"type":["string","null"]},"to":{"type":["string","null"]},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"requests":{"type":"number"},"totalTokens":{"type":"number"},"costUsd":{"type":"number"},"avgLatencyMs":{"type":"number"}},"required":["date","requests","totalTokens","costUsd","avgLatencyMs"],"additionalProperties":false}}},"required":["configured","from","to","points"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/logs":{"get":{"operationId":"logs.list","summary":"List recent request-log rows, newest first: route, key, model, status, latency, tokens and cost. Never a body.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"logs:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"ts":{"type":"string"},"endpoint":{"type":"string"},"channel":{"type":"string","enum":["api","subscription"]},"route":{"type":["string","null"]},"model":{"type":["string","null"]},"source":{"type":["string","null"]},"keyId":{"type":"string"},"subjectType":{"anyOf":[{"type":"string","enum":["human","workload"]},{"type":"null"}]},"subjectId":{"type":["string","null"]},"client":{"type":["string","null"]},"sessionId":{"type":["string","null"]},"endUser":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"streamed":{"type":"boolean"},"aborted":{"type":"boolean"},"latencyMs":{"type":"number"},"ttftMs":{"type":["number","null"]},"promptTokens":{"type":["number","null"]},"completionTokens":{"type":["number","null"]},"totalTokens":{"type":["number","null"]},"cachedTokens":{"type":["number","null"]},"cacheWriteTokens":{"type":["number","null"]},"imageCount":{"type":["number","null"]},"audioSeconds":{"type":["number","null"]},"characters":{"type":["number","null"]},"documents":{"type":["number","null"]},"costUsd":{"type":["number","null"]},"costSource":{"anyOf":[{"type":"string","enum":["upstream","catalog","catalog_interactive"]},{"type":"null"}]},"guardFindings":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"logId":{"type":"number"},"stage":{"type":"string","enum":["request","response","tool_call","tool_result"]},"ruleId":{"type":["string","null"]},"guard":{"type":"string"},"ruleType":{"type":["string","null"]},"action":{"type":"string"},"category":{"type":["string","null"]}},"required":["id","logId","stage","ruleId","guard","ruleType","action","category"],"additionalProperties":false}},{"type":"null"}]},"packTokens":{"type":["number","null"]},"packs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"logId":{"type":"number"},"packId":{"type":"string"},"versionId":{"type":["string","null"]},"assignmentId":{"type":"string"},"outcome":{"type":"string"},"tokens":{"type":["number","null"]},"chunkIndexes":{"anyOf":[{"type":"array","items":{"type":"number"}},{"type":"null"}]}},"required":["id","logId","packId","versionId","assignmentId","outcome","tokens"],"additionalProperties":false}}},"required":["id","ts","endpoint","channel","keyId","subjectType","subjectId","client","sessionId","tags","status","aborted","latencyMs","ttftMs","cachedTokens","cacheWriteTokens","imageCount","audioSeconds","characters","documents","costUsd","costSource","guardFindings","packTokens","packs"],"additionalProperties":false}}},"required":["rows"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":500}},{"name":"route","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"key_id","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"include_copilot","in":"query","required":false,"schema":{"default":"false","type":"string","enum":["true","false"]}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/observability/traces":{"get":{"operationId":"observability.traces.list","summary":"List Langfuse traces (names, timings, costs, tags), filtered by window, user, tag or name. Never a body.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"logs:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"configured":{"type":"boolean"},"traces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"timestamp":{"type":"string"},"name":{"type":["string","null"]},"user":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"latencyMs":{"type":["number","null"]},"costUsd":{"type":["number","null"]},"observationCount":{"type":"number"}},"required":["id","timestamp","name","user","tags","latencyMs","costUsd","observationCount"],"additionalProperties":false}},"page":{"type":"number"},"totalPages":{"type":"number"},"totalItems":{"type":"number"}},"required":["configured","traces","page","totalPages","totalItems"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}},{"name":"user","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"tag","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"name","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}}]}},"/audit":{"get":{"operationId":"audit.list","summary":"List audit-log entries, newest first: who changed what, when, and the before and after.","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"audit:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"ts":{"type":"string"},"actorType":{"type":"string","enum":["user","token"]},"actorUserId":{"type":["string","null"]},"actorEmail":{"type":["string","null"]},"actorTokenId":{"type":["string","null"]},"action":{"type":"string"},"resourceType":{"type":["string","null"]},"resourceId":{"type":["string","null"]},"before":{},"after":{},"ip":{"type":["string","null"]},"userAgent":{"type":["string","null"]},"reason":{"type":["string","null"]},"reasonCategory":{"type":["string","null"]}},"required":["id","ts","actorType","actorUserId","actorEmail","actorTokenId","action","resourceType","resourceId","before","after","ip","userAgent","reason","reasonCategory"],"additionalProperties":false}}},"required":["entries"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":500}},{"name":"action","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"actor_user_id","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"content_only","in":"query","required":false,"schema":{"default":"false","type":"string","enum":["true","false"]}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/keys":{"get":{"operationId":"keys.list","summary":"List client keys with their owner, route and ZDR fences, tool grant, team, budget and spend. Never a secret.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"keys:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"keyId":{"type":["string","null"]},"label":{"type":"string"},"assignee":{"type":["string","null"]},"ownerUserId":{"type":["string","null"]},"ownerEmail":{"type":["string","null"]},"allowedRoutes":{"type":"array","items":{"type":"string"}},"pinnedRoute":{"type":["string","null"]},"requireZdr":{"type":"boolean"},"toolAccess":{"anyOf":[{"type":"object","properties":{"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"readOnly":{"type":"boolean"},"version":{"type":"number"},"syncedVersion":{"type":["number","null"]},"syncedAt":{"type":["string","null"]},"syncError":{"type":["string","null"]},"status":{"type":"string","enum":["none","drift","ready"]}},"required":["servers","tools","resources","prompts","groups","readOnly","version","syncedVersion","syncedAt","syncError","status"],"additionalProperties":false},{"type":"null"}]},"teamId":{"type":["string","null"]},"budget":{"type":["number","null"]},"budgetDuration":{"type":["string","null"]},"spend":{"type":"number"},"status":{"type":"string","enum":["active","revoked"]},"createdAt":{"type":["string","null"]},"isCopilot":{"type":"boolean"}},"required":["id","keyId","label","assignee","ownerUserId","ownerEmail","allowedRoutes","pinnedRoute","budget","budgetDuration","spend","status","createdAt"],"additionalProperties":false}}},"required":["keys"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"keys.create","summary":"Mint a client key; its secret is returned once and never again. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"keys:write","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string"},"keyId":{"type":["string","null"]},"label":{"type":"string"},"assignee":{"type":["string","null"]},"ownerUserId":{"type":["string","null"]},"ownerEmail":{"type":["string","null"]},"allowedRoutes":{"type":"array","items":{"type":"string"}},"pinnedRoute":{"type":["string","null"]},"requireZdr":{"type":"boolean"},"toolAccess":{"anyOf":[{"type":"object","properties":{"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"readOnly":{"type":"boolean"},"version":{"type":"number"},"syncedVersion":{"type":["number","null"]},"syncedAt":{"type":["string","null"]},"syncError":{"type":["string","null"]},"status":{"type":"string","enum":["none","drift","ready"]}},"required":["servers","tools","resources","prompts","groups","readOnly","version","syncedVersion","syncedAt","syncError","status"],"additionalProperties":false},{"type":"null"}]},"teamId":{"type":["string","null"]},"budget":{"type":["number","null"]},"budgetDuration":{"type":["string","null"]},"spend":{"type":"number"},"status":{"type":"string","enum":["active","revoked"]},"createdAt":{"type":["string","null"]},"isCopilot":{"type":"boolean"},"secret":{"type":"string"}},"required":["id","keyId","label","assignee","ownerUserId","ownerEmail","allowedRoutes","pinnedRoute","budget","budgetDuration","spend","status","createdAt","secret"],"additionalProperties":false}},"required":["key"],"additionalProperties":false}}},"headers":{"Idempotency-Replayed":{"description":"`true` when this response was replayed from a previously recorded `Idempotency-Key` rather than produced by this call.","schema":{"type":"boolean"}}}},"400":{"description":"Invalid request — schema violation or a rejected value. Also `code: idempotency_key_required` when the `Idempotency-Key` header is absent, and `idempotency_key_invalid` when it is malformed."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"409":{"description":"Either another request with this `Idempotency-Key` is still in progress (`code: idempotency_in_progress`, body carries `retryAfterSeconds`), or it already succeeded and its response is not replayable because it carried a secret (`code: idempotency_result_not_replayable`, body carries `resourceId`). Nothing was performed a second time in either case."},"410":{"description":"The key is known but its response is no longer stored (replay window: 24h). Check current state and use a new key."},"422":{"description":"This `Idempotency-Key` was already used for a DIFFERENT request (`code: idempotency_key_reused`). Use a new key — note the `If-Match` version, the query and the body are all part of the request the key names."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-idempotency":"required","x-idempotency-replay":"outcome-only","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"A unique key identifying THIS attempt, so a retry cannot perform the operation twice. Generate one per logical invocation (a UUID) and reuse it across transport retries — never regenerate it when retrying, which defeats the purpose. The If-Match version, query and body are all part of the request the key names: change any of them and you need a new key.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,255}$","minLength":8,"maxLength":255,"examples":["3f1a9c52-7b0e-4a1d-9f2c-8e6d4b0a1c37"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"label":{"type":"string","minLength":1},"ownerUserId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"assignee":{"type":"string"},"budget":{"type":"number","minimum":0},"budgetDuration":{"type":"string","minLength":1},"allowedRoutes":{"type":"array","items":{"type":"string","minLength":1}},"pinnedRoute":{"type":"string","minLength":1}},"required":["label"]}}}}}},"/users":{"get":{"operationId":"users.list","summary":"List console users with their role, status, identity provider and last sign-in.","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"users:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["member","viewer","admin","owner"]},"status":{"type":"string","enum":["invited","active","disabled"]},"authProvider":{"type":"string"},"externalId":{"type":["string","null"]},"createdAt":{"type":"string"},"lastLoginAt":{"type":["string","null"]}},"required":["id","email","name","role","status","authProvider","externalId","createdAt","lastLoginAt"],"additionalProperties":false}}},"required":["users"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"users.create","summary":"Pre-provision a console user by email and role. A duplicate email is a 409. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"users:write","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["member","viewer","admin","owner"]},"status":{"type":"string","enum":["invited","active","disabled"]},"authProvider":{"type":"string"},"externalId":{"type":["string","null"]},"createdAt":{"type":"string"},"lastLoginAt":{"type":["string","null"]}},"required":["id","email","name","role","status","authProvider","externalId","createdAt","lastLoginAt"],"additionalProperties":false}},"required":["user"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"email":{"type":"string","pattern":"^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"},"role":{"type":"string","enum":["owner","admin","viewer"]},"name":{"type":"string"}},"required":["email","role"]}}}}}},"/users/directory":{"get":{"operationId":"users.directory","summary":"List the accounts that can own a key: id, name and email only. Disabled accounts are left out.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"users:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"additionalProperties":false}}},"required":["users"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}}},"/credentials":{"get":{"operationId":"credentials.list","summary":"List provider credentials: name, provider and endpoint. Never the provider key.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"providers:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"credentials":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"provider":{"type":["string","null"]},"apiBase":{"type":["string","null"]}},"required":["name","provider","apiBase"],"additionalProperties":false}}},"required":["credentials"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"credentials.create","summary":"Store a provider key in the chassis under a name models reference. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"providers:write","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1},"provider":{"type":"string","minLength":1},"apiKey":{"type":"string","minLength":1},"apiBase":{"type":"string"}},"required":["name","provider","apiKey"]}}}}}},"/credentials/usage":{"get":{"operationId":"credentials.usage","summary":"Read each provider credential's usage in its limit window, as tokens, USD and percent of the limit.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"providers:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"usage":{"type":"array","items":{"type":"object","properties":{"credential":{"type":"string"},"provider":{"type":["string","null"]},"period":{"type":"string","enum":["month","30d"]},"windowStart":{"type":"string"},"models":{"type":"array","items":{"type":"string"}},"usedTokens":{"type":"number"},"usedUsd":{"type":"number"},"unpricedModels":{"type":"array","items":{"type":"string"}},"limitTokens":{"type":["number","null"]},"limitUsd":{"type":["number","null"]},"pctTokens":{"type":["number","null"]},"pctUsd":{"type":["number","null"]},"pct":{"type":["number","null"]},"headroom":{"anyOf":[{"type":"object","properties":{"model":{"type":"string"},"pctLeft":{"type":"number"},"tokensRemaining":{"type":["number","null"]},"tokensLimit":{"type":["number","null"]},"requestsRemaining":{"type":["number","null"]},"requestsLimit":{"type":["number","null"]},"capturedAt":{"type":"string"}},"required":["model","pctLeft","tokensRemaining","tokensLimit","requestsRemaining","requestsLimit","capturedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["credential","provider","period","windowStart","models","usedTokens","usedUsd","unpricedModels","limitTokens","limitUsd","pctTokens","pctUsd","pct","headroom"],"additionalProperties":false}}},"required":["usage"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}}},"/models/catalog":{"get":{"operationId":"models.catalog","summary":"List the routable models with their provider model, credential and source.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"config:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"providerModel":{"type":"string"},"credentialName":{"type":["string","null"]},"source":{"type":"string","enum":["config","database"]}},"required":["id","name","providerModel","credentialName","source"],"additionalProperties":false}}},"required":["models"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}}},"/prices":{"get":{"operationId":"prices.list","summary":"List the rates the gateway prices each request with, per model, and where each rate came from.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"providers:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"prices":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"inputUsdPerMtok":{"type":["number","null"]},"outputUsdPerMtok":{"type":["number","null"]},"cacheReadUsdPerMtok":{"type":["number","null"]},"cacheWriteUsdPerMtok":{"type":["number","null"]},"imageUsdPerUnit":{"type":["number","null"]},"audioUsdPerSecond":{"type":["number","null"]},"characterUsdPerMchar":{"type":["number","null"]},"maxInputTokens":{"type":["number","null"]},"source":{"type":"string","enum":["chassis","manual"]},"updatedAt":{"type":"string"}},"required":["model","inputUsdPerMtok","outputUsdPerMtok","cacheReadUsdPerMtok","cacheWriteUsdPerMtok","imageUsdPerUnit","audioUsdPerSecond","characterUsdPerMchar","maxInputTokens","source","updatedAt"],"additionalProperties":false}}},"required":["prices"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"prices.import","summary":"Import the chassis catalog's list prices. Manual rates are never overwritten. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"providers:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"found":{"type":"number"},"imported":{"type":"number"},"skippedManual":{"type":"number"}},"required":["found","imported","skippedManual"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true},"put":{"operationId":"prices.set","summary":"Set one model's rates by hand (a negotiated price). An absent rate is unknown. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"providers:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"price":{"type":"object","properties":{"model":{"type":"string"},"inputUsdPerMtok":{"type":["number","null"]},"outputUsdPerMtok":{"type":["number","null"]},"cacheReadUsdPerMtok":{"type":["number","null"]},"cacheWriteUsdPerMtok":{"type":["number","null"]},"imageUsdPerUnit":{"type":["number","null"]},"audioUsdPerSecond":{"type":["number","null"]},"characterUsdPerMchar":{"type":["number","null"]},"maxInputTokens":{"type":["number","null"]},"source":{"type":"string","enum":["chassis","manual"]},"updatedAt":{"type":"string"}},"required":["model","inputUsdPerMtok","outputUsdPerMtok","cacheReadUsdPerMtok","cacheWriteUsdPerMtok","imageUsdPerUnit","audioUsdPerSecond","characterUsdPerMchar","maxInputTokens","source","updatedAt"],"additionalProperties":false}},"required":["price"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"model":{"type":"string","minLength":1},"inputUsdPerMtok":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"outputUsdPerMtok":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"cacheReadUsdPerMtok":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"cacheWriteUsdPerMtok":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"imageUsdPerUnit":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"audioUsdPerSecond":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"characterUsdPerMchar":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]}},"required":["model"]}}}}},"delete":{"operationId":"prices.delete","summary":"Remove a model's rates; its requests are then unpriced. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"providers:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"model","in":"query","required":true,"schema":{"type":"string","minLength":1}}]}},"/model-policy":{"get":{"operationId":"model-policy.list","summary":"List the per-model zero-data-retention attestations that ZDR-only keys and routes are routed on.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"providers:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"policies":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"zdr":{"type":"boolean"},"note":{"type":["string","null"]},"updatedAt":{"type":"string"}},"required":["model","zdr","note","updatedAt"],"additionalProperties":false}}},"required":["policies"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"put":{"operationId":"model-policy.set","summary":"Record or withdraw one model's ZDR attestation — a claim an operator makes, audited with its note. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"providers:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"policy":{"type":"object","properties":{"model":{"type":"string"},"zdr":{"type":"boolean"},"note":{"type":["string","null"]},"updatedAt":{"type":"string"}},"required":["model","zdr","note","updatedAt"],"additionalProperties":false}},"required":["policy"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"model":{"type":"string","minLength":1},"zdr":{"type":"boolean"},"note":{"type":["string","null"]}},"required":["model","zdr"]}}}}},"delete":{"operationId":"model-policy.delete","summary":"Drop a model's attestation, returning it to unattested. ZDR-only traffic stops using it. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"providers:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"model","in":"query","required":true,"schema":{"type":"string","minLength":1}}]}},"/providers":{"get":{"operationId":"providers.list","summary":"List the providers and models the chassis registry knows, for choosing a model to add.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"providers:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"models":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"providerModel":{"type":"string"},"mode":{"type":"string"}},"required":["model","providerModel","mode"],"additionalProperties":false}}},"required":["id","models"],"additionalProperties":false}}},"required":["providers"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}}},"/keys/{id}":{"delete":{"operationId":"keys.revoke","summary":"Revoke a client key by its chassis id; clients using it stop at once. The copilot's own key needs force=true.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"keys:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"key_id","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"force","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}]}},"/keys/owner":{"post":{"operationId":"keys.owner.set","summary":"Set or clear the person a key belongs to — whose usage its spend is reported under. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"keys:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"ownerUserId":{"type":["string","null"]},"ownerEmail":{"type":["string","null"]}},"required":["ok","ownerUserId","ownerEmail"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keyId":{"type":"string","minLength":1},"userId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["keyId"]}}}}}},"/keys/pin":{"post":{"operationId":"keys.pin.set","summary":"Pin a key to one route, which skips the classifier, or clear its pin. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"keys:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"pinned":{"type":["string","null"]}},"required":["ok","pinned"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keyId":{"type":"string","minLength":1},"route":{"type":["string","null"]}},"required":["keyId","route"]}}}}}},"/keys/repair":{"post":{"operationId":"keys.identity.repair","summary":"Record our id for a key this console did not create, so it can be owned, scoped and pinned. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"keys:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keyId":{"type":"string"},"alreadyRecorded":{"type":"boolean"}},"required":["keyId","alreadyRecorded"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"]}}}}}},"/keys/scope":{"post":{"operationId":"keys.scope.set","summary":"Set the routes a key may use; an empty list allows every route. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"keys:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"routes":{"type":"array","items":{"type":"string"}}},"required":["ok","routes"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keyId":{"type":"string","minLength":1},"routes":{"type":"array","items":{"type":"string"}}},"required":["keyId","routes"]}}}}}},"/keys/zdr":{"post":{"operationId":"keys.zdr.set","summary":"Require, or stop requiring, ZDR-attested models for a key. Turning it on can refuse its traffic at once. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"keys:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"requireZdr":{"type":"boolean"}},"required":["ok","requireZdr"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keyId":{"type":"string","minLength":1},"required":{"type":"boolean"}},"required":["keyId","required"]}}}}}},"/keys/tools":{"post":{"operationId":"keys.tools.set","summary":"Set which MCP tools, resources and prompts a key may use, then sync the chassis copy. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"keys:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"access":{"type":"object","properties":{"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"readOnly":{"type":"boolean"},"version":{"type":"number"},"syncedVersion":{"type":["number","null"]},"syncedAt":{"type":["string","null"]},"syncError":{"type":["string","null"]},"status":{"type":"string","enum":["none","drift","ready"]}},"required":["servers","tools","resources","prompts","groups","readOnly","version","syncedVersion","syncedAt","syncError","status"],"additionalProperties":false}},"required":["access"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keyId":{"type":"string","minLength":1},"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"readOnly":{"type":"boolean"}},"required":["keyId","servers","tools","readOnly"]}}}}},"delete":{"operationId":"keys.tools.revoke","summary":"Remove a key's tool grant: it may then call no tool. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"keys:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"key_id","in":"query","required":true,"schema":{"type":"string","minLength":1}}]}},"/keys/tools/resync":{"post":{"operationId":"keys.tools.resync","summary":"Push a key's stored tool grant to the chassis again, after a failed sync. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"keys:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"access":{"type":"object","properties":{"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"readOnly":{"type":"boolean"},"version":{"type":"number"},"syncedVersion":{"type":["number","null"]},"syncedAt":{"type":["string","null"]},"syncError":{"type":["string","null"]},"status":{"type":"string","enum":["none","drift","ready"]}},"required":["servers","tools","resources","prompts","groups","readOnly","version","syncedVersion","syncedAt","syncError","status"],"additionalProperties":false}},"required":["access"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keyId":{"type":"string","minLength":1}},"required":["keyId"]}}}}}},"/keys/team":{"post":{"operationId":"keys.team.set","summary":"Put a key in a team, whose tool grant is AND-ed with the key's, or take it out. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"keys:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"teamId":{"type":["string","null"]},"access":{"anyOf":[{"type":"object","properties":{"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"readOnly":{"type":"boolean"},"version":{"type":"number"},"syncedVersion":{"type":["number","null"]},"syncedAt":{"type":["string","null"]},"syncError":{"type":["string","null"]},"status":{"type":"string","enum":["none","drift","ready"]}},"required":["servers","tools","resources","prompts","groups","readOnly","version","syncedVersion","syncedAt","syncError","status"],"additionalProperties":false},{"type":"null"}]}},"required":["teamId","access"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keyId":{"type":"string","minLength":1},"teamId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["keyId","teamId"]}}}}}},"/users/{id}":{"patch":{"operationId":"users.update","summary":"Change a user's role or status. Nobody changes their own, and the last active owner stays. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"users:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"role":{"type":"string","enum":["member","viewer","admin","owner"]},"status":{"type":"string","enum":["invited","active","disabled"]}},"required":["ok","role","status"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"role":{"type":"string","enum":["owner","admin","viewer"]},"status":{"type":"string","enum":["invited","active","disabled"]}}}}}}}},"/credentials/{name}":{"patch":{"operationId":"credentials.rotate","summary":"Replace a provider key in place; every model on it uses the new key from its next request. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"providers:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"apiKey":{"type":"string","minLength":1}},"required":["apiKey"]}}}}},"delete":{"operationId":"credentials.delete","summary":"Delete a provider credential and its declared limit. A 409 names the models still using it. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"providers:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}]}},"/credentials/{name}/limit":{"put":{"operationId":"credentials.limit.set","summary":"Declare a provider credential's token and USD ceilings per window; both null clears them. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"providers:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"limit":{"anyOf":[{"type":"object","properties":{"credentialName":{"type":"string"},"limitTokens":{"type":["number","null"]},"limitUsd":{"type":["number","null"]},"period":{"type":"string","enum":["month","30d"]},"updatedAt":{"type":"string"}},"required":["credentialName","limitTokens","limitUsd","period","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["limit"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"limitTokens":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"limitUsd":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"period":{"type":"string","enum":["month","30d"]}}}}}}}},"/models/{id}":{"put":{"operationId":"models.update","summary":"Update a console-added model's provider model, credential or endpoint. Seed models are managed in git. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"config:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1},"providerModel":{"type":"string","minLength":1},"credentialName":{"default":"","type":"string"},"apiBase":{"type":"string"}},"required":["name","providerModel"]}}}}},"delete":{"operationId":"models.delete","summary":"Remove a console-added model from the chassis catalog. A 409 names the routes that still use it as model or fallback. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"config:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/tools/servers":{"get":{"operationId":"tools.servers.list","summary":"List the registered MCP and REST servers with every tool, resource and prompt they declare. Never a credential.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"tools:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"servers":{"type":"array","items":{"type":"object","properties":{"serverId":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"transport":{"type":"string","enum":["http","sse"]},"authType":{"type":"string","enum":["none","api_key","bearer_token","oauth2"]},"enabled":{"type":"boolean"},"description":{"type":["string","null"]},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"readOnly":{"type":"boolean"},"destructive":{"type":"boolean"},"description":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"mask":{"type":"array","items":{"type":"string"}},"rateLimit":{"anyOf":[{"type":"object","properties":{"requests":{"type":"number"},"windowSeconds":{"type":"number"}},"required":["requests","windowSeconds"],"additionalProperties":false},{"type":"null"}]},"requiresApproval":{"type":"boolean"},"allowedParams":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rest":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string"},"parameters":{"$ref":"#/$defs/__schema0"}},"required":["method","path","parameters"],"additionalProperties":false},"policyInvalid":{"type":"boolean"}},"required":["name","readOnly","destructive","description"],"additionalProperties":false}},"resources":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"policyInvalid":{"type":"boolean"}},"required":["uri","name","description","mimeType"],"additionalProperties":false}},"prompts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"policyInvalid":{"type":"boolean"}},"required":["name","description"],"additionalProperties":false}},"custody":{"type":"string","enum":["service","connection"]},"provider":{"type":["string","null"]},"audience":{"type":["string","null"]},"maxScopes":{"type":"array","items":{"type":"string"}},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"header":{"type":"string"},"description":{"type":["string","null"]},"required":{"type":"boolean"}},"required":["name","header","description","required"],"additionalProperties":false}},"kind":{"type":"string","enum":["mcp","rest"]},"restAuth":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","enum":["header","query"]},"name":{"type":"string"},"prefix":{"type":["string","null"]}},"required":["location","name","prefix"],"additionalProperties":false},{"type":"null"}]}},"required":["serverId","name","url","transport","authType","enabled","description","tools","resources","prompts"],"additionalProperties":false}},"tools":{"type":"array","items":{"type":"object","properties":{"canonicalName":{"type":"string"},"server":{"type":"string"},"name":{"type":"string"},"readOnly":{"type":"boolean"},"destructive":{"type":"boolean"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"}},"required":["canonicalName","server","name","readOnly","destructive","description","enabled"],"additionalProperties":false}},"resources":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"template":{"type":"boolean"},"server":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"enabled":{"type":"boolean"}},"required":["uri","template","server","name","description","mimeType","enabled"],"additionalProperties":false}},"prompts":{"type":"array","items":{"type":"object","properties":{"canonicalName":{"type":"string"},"server":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"}},"required":["canonicalName","server","name","description","enabled"],"additionalProperties":false}},"restCredentials":{"type":"array","items":{"type":"object","properties":{"serverId":{"type":"string"},"generation":{"type":"number"},"updatedAt":{"type":"string"},"updatedByUserId":{"type":["string","null"]}},"required":["serverId","generation","updatedAt","updatedByUserId"],"additionalProperties":false}}},"required":["servers","tools","resources","prompts","restCredentials"],"additionalProperties":false,"$defs":{"__schema0":{"type":"object","properties":{"type":{"type":"string","enum":["object","array","string","number","integer","boolean","null"]},"description":{"type":"string"},"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"required":{"type":"array","items":{"type":"string"}},"visible":{"type":"array","items":{"type":"string"}},"items":{"$ref":"#/$defs/__schema0"},"enum":{"type":"array","items":{}},"default":{}},"additionalProperties":{}}}}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"tools.servers.register","summary":"Register an MCP or REST server, which makes a third-party system reachable through this gateway. An existing id is a 409. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"server":{"type":"object","properties":{"serverId":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"transport":{"type":"string","enum":["http","sse"]},"authType":{"type":"string","enum":["none","api_key","bearer_token","oauth2"]},"enabled":{"type":"boolean"},"description":{"type":["string","null"]},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"readOnly":{"type":"boolean"},"destructive":{"type":"boolean"},"description":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"mask":{"type":"array","items":{"type":"string"}},"rateLimit":{"anyOf":[{"type":"object","properties":{"requests":{"type":"number"},"windowSeconds":{"type":"number"}},"required":["requests","windowSeconds"],"additionalProperties":false},{"type":"null"}]},"requiresApproval":{"type":"boolean"},"allowedParams":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rest":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string"},"parameters":{"$ref":"#/$defs/__schema0"}},"required":["method","path","parameters"],"additionalProperties":false},"policyInvalid":{"type":"boolean"}},"required":["name","readOnly","destructive","description"],"additionalProperties":false}},"resources":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"policyInvalid":{"type":"boolean"}},"required":["uri","name","description","mimeType"],"additionalProperties":false}},"prompts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"policyInvalid":{"type":"boolean"}},"required":["name","description"],"additionalProperties":false}},"custody":{"type":"string","enum":["service","connection"]},"provider":{"type":["string","null"]},"audience":{"type":["string","null"]},"maxScopes":{"type":"array","items":{"type":"string"}},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"header":{"type":"string"},"description":{"type":["string","null"]},"required":{"type":"boolean"}},"required":["name","header","description","required"],"additionalProperties":false}},"kind":{"type":"string","enum":["mcp","rest"]},"restAuth":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","enum":["header","query"]},"name":{"type":"string"},"prefix":{"type":["string","null"]}},"required":["location","name","prefix"],"additionalProperties":false},{"type":"null"}]}},"required":["serverId","name","url","transport","authType","enabled","description","tools","resources","prompts"],"additionalProperties":false},"chassis":{"type":"object","properties":{"synced":{"type":"boolean"},"error":{"type":["string","null"]},"keys":{"type":"object","properties":{"synced":{"type":"number"},"failed":{"type":"number"}},"required":["synced","failed"],"additionalProperties":false}},"required":["synced","error","keys"],"additionalProperties":false}},"required":["server","chassis"],"additionalProperties":false,"$defs":{"__schema0":{"type":"object","properties":{"type":{"type":"string","enum":["object","array","string","number","integer","boolean","null"]},"description":{"type":"string"},"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"required":{"type":"array","items":{"type":"string"}},"visible":{"type":"array","items":{"type":"string"}},"items":{"$ref":"#/$defs/__schema0"},"enum":{"type":"array","items":{}},"default":{}},"additionalProperties":{}}}}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"serverId":{"type":"string"},"kind":{"type":"string","enum":["mcp","rest"]},"name":{"type":"string"},"url":{"type":"string"},"transport":{"type":"string","enum":["http","sse"]},"authType":{"type":"string","enum":["none","api_key","bearer_token","oauth2"]},"enabled":{"type":"boolean"},"description":{"type":["string","null"]},"tools":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"resources":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"prompts":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"variables":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"null"}]},"custody":{"type":"string","enum":["service","connection"]},"provider":{"type":["string","null"]},"audience":{"type":["string","null"]},"maxScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"restAuth":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"credential":{"type":["string","null"]},"clearCredential":{"type":"boolean"}},"required":["serverId","name","url","transport","authType"]}}}}}},"/tools/servers/{id}/inspect":{"get":{"operationId":"tools.servers.inspect","summary":"Inspect one registered server from stored facts only: which grants reach it, its recent ledger activity and its name collisions.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"tools:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"server":{"type":"object","properties":{"serverId":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"transport":{"type":"string","enum":["http","sse"]},"authType":{"type":"string","enum":["none","api_key","bearer_token","oauth2"]},"enabled":{"type":"boolean"},"description":{"type":["string","null"]},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"readOnly":{"type":"boolean"},"destructive":{"type":"boolean"},"description":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"mask":{"type":"array","items":{"type":"string"}},"rateLimit":{"anyOf":[{"type":"object","properties":{"requests":{"type":"number"},"windowSeconds":{"type":"number"}},"required":["requests","windowSeconds"],"additionalProperties":false},{"type":"null"}]},"requiresApproval":{"type":"boolean"},"allowedParams":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rest":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string"},"parameters":{"$ref":"#/$defs/__schema0"}},"required":["method","path","parameters"],"additionalProperties":false},"policyInvalid":{"type":"boolean"}},"required":["name","readOnly","destructive","description"],"additionalProperties":false}},"resources":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"policyInvalid":{"type":"boolean"}},"required":["uri","name","description","mimeType"],"additionalProperties":false}},"prompts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"policyInvalid":{"type":"boolean"}},"required":["name","description"],"additionalProperties":false}},"custody":{"type":"string","enum":["service","connection"]},"provider":{"type":["string","null"]},"audience":{"type":["string","null"]},"maxScopes":{"type":"array","items":{"type":"string"}},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"header":{"type":"string"},"description":{"type":["string","null"]},"required":{"type":"boolean"}},"required":["name","header","description","required"],"additionalProperties":false}},"kind":{"type":"string","enum":["mcp","rest"]},"restAuth":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","enum":["header","query"]},"name":{"type":"string"},"prefix":{"type":["string","null"]}},"required":["location","name","prefix"],"additionalProperties":false},{"type":"null"}]}},"required":["serverId","name","url","transport","authType","enabled","description","tools","resources","prompts"],"additionalProperties":false},"reach":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["key","team"]},"principalId":{"type":"string"},"label":{"type":["string","null"]},"tools":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"readOnly":{"type":"boolean"},"synced":{"type":"boolean"},"syncError":{"type":["string","null"]}},"required":["kind","principalId","label","tools","readOnly","synced","syncError"],"additionalProperties":false}},"activity":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string"},"calls":{"type":"number"},"dispatched":{"type":"number"},"denied":{"type":"number"},"pending":{"type":"number"},"failed":{"type":"number"},"unknown":{"type":"number"},"costUsd":{"type":"number"},"unpricedCalls":{"type":"number"},"avgLatencyMs":{"type":["number","null"]},"p95LatencyMs":{"type":["number","null"]},"subjectName":{"type":["string","null"]}},"required":["group","calls","dispatched","denied","pending","failed","unknown","costUsd","unpricedCalls","avgLatencyMs","p95LatencyMs","subjectName"],"additionalProperties":false}},"activityDays":{"type":"number"},"ambiguous":{"type":"array","items":{"type":"string"}}},"required":["server","reach","activity","activityDays","ambiguous"],"additionalProperties":false,"$defs":{"__schema0":{"type":"object","properties":{"type":{"type":"string","enum":["object","array","string","number","integer","boolean","null"]},"description":{"type":"string"},"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"required":{"type":"array","items":{"type":"string"}},"visible":{"type":"array","items":{"type":"string"}},"items":{"$ref":"#/$defs/__schema0"},"enum":{"type":"array","items":{}},"default":{}},"additionalProperties":{}}}}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/teams":{"get":{"operationId":"teams.list","summary":"List the teams a key may be put in, each with its tool grant and its member count.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"tools:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"teams":{"type":"array","items":{"type":"object","properties":{"teamId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"members":{"type":"number"},"toolAccess":{"anyOf":[{"type":"object","properties":{"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"readOnly":{"type":"boolean"},"version":{"type":"number"},"syncedVersion":{"type":["number","null"]},"syncedAt":{"type":["string","null"]},"syncError":{"type":["string","null"]},"status":{"type":"string","enum":["none","drift","ready"]}},"required":["servers","tools","resources","prompts","groups","readOnly","version","syncedVersion","syncedAt","syncError","status"],"additionalProperties":false},{"type":"null"}]}},"required":["teamId","name","description","createdAt","updatedAt","members","toolAccess"],"additionalProperties":false}}},"required":["teams"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"teams.upsert","summary":"Create a team a key may be put in, or rename one. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"team":{"type":"object","properties":{"teamId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["teamId","name","description","createdAt","updatedAt"],"additionalProperties":false}},"required":["team"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"teamId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]}},"required":["teamId","name"]}}}}}},"/tools/groups":{"get":{"operationId":"tools.groups.list","summary":"List the tool groups: named bundles of servers, tools, resources and prompts that a grant may name.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"tools:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"groupId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string"}},"required":["groupId","name","description","servers","tools","resources","prompts","updatedAt"],"additionalProperties":false}}},"required":["groups"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"tools.groups.upsert","summary":"Create or replace a tool group; every grant that names it is bumped and re-pushed in the same request. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"group":{"type":"object","properties":{"groupId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string"}},"required":["groupId","name","description","servers","tools","resources","prompts","updatedAt"],"additionalProperties":false},"sync":{"type":"object","properties":{"synced":{"type":"number"},"failed":{"type":"number"},"affected":{"type":"number"}},"required":["synced","failed","affected"],"additionalProperties":false}},"required":["group","sync"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"groupId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}}},"required":["groupId","name"]}}}}}},"/tools/virtual-servers":{"get":{"operationId":"tools.virtual-servers.list","summary":"List the virtual servers: named toolsets an agent mounts as one endpoint. A mount only narrows a grant.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"tools:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"virtualServers":{"type":"array","items":{"type":"object","properties":{"serverId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"disclosure":{"type":"string","enum":["all","progressive"]},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["serverId","name","description","servers","tools","resources","prompts","groups","disclosure","enabled","createdAt","updatedAt"],"additionalProperties":false}},"gatewayUrl":{"type":["string","null"]}},"required":["virtualServers","gatewayUrl"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"tools.virtual-servers.upsert","summary":"Create or replace a virtual server: the toolset an agent mounts at /mcp/{serverId}. It only narrows a grant. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"virtualServer":{"type":"object","properties":{"serverId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"disclosure":{"type":"string","enum":["all","progressive"]},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["serverId","name","description","servers","tools","resources","prompts","groups","disclosure","enabled","createdAt","updatedAt"],"additionalProperties":false}},"required":["virtualServer"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"serverId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"disclosure":{"type":"string","enum":["all","progressive"]},"enabled":{"type":"boolean"}},"required":["serverId","name"]}}}}}},"/tools/variables":{"get":{"operationId":"tools.variables.read","summary":"Read a service-account key's server variables (a site, a workspace id), per server that declares them. Never a secret.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"tools:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"servers":{"type":"array","items":{"type":"object","properties":{"serverId":{"type":"string"},"name":{"type":"string"},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"required":{"type":"boolean"},"value":{"type":["string","null"]}},"required":["name","description","required","value"],"additionalProperties":false}}},"required":["serverId","name","variables"],"additionalProperties":false}}},"required":["servers"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"key_id","in":"query","required":true,"schema":{"type":"string","minLength":1}}]},"put":{"operationId":"tools.variables.set","summary":"Replace a service-account key's variables for one server, which chooses where its calls land. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"serverId":{"type":"string"},"set":{"type":"array","items":{"type":"string"}},"refused":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["serverId","set","refused"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keyId":{"type":"string","minLength":1},"serverId":{"type":"string","minLength":1},"values":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["keyId","serverId","values"]}}}}}},"/tools/calls":{"get":{"operationId":"tools.calls.list","summary":"List tool-call ledger rows, newest first: person, tool, decision, outcome, latency and cost, refused calls included. Never arguments or results.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"logs:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"ts":{"type":"string"},"requestLogId":{"type":["number","null"]},"keyId":{"type":"string"},"subjectType":{"type":"string","enum":["human","workload"]},"subjectId":{"type":"string"},"connectionId":{"type":["string","null"]},"server":{"type":"string"},"primitive":{"type":"string","enum":["tool","resource","prompt"]},"tool":{"type":"string"},"policyVersion":{"type":"number"},"decision":{"type":"string","enum":["allowed","denied","approval_pending","approved","rejected"]},"dispatchedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"outcome":{"anyOf":[{"type":"string","enum":["ok","failed","unknown"]},{"type":"null"}]},"latencyMs":{"type":["number","null"]},"costUsd":{"type":["number","null"]},"costSource":{"type":"string","enum":["chassis","declared","none"]},"guardFindings":{"type":"number"},"reason":{"type":["string","null"]},"mount":{"type":["string","null"]},"skillVersionId":{"type":["string","null"]},"sessionId":{"type":["string","null"]},"subjectName":{"type":["string","null"]},"subjectEmail":{"type":["string","null"]}},"required":["id","ts","requestLogId","keyId","subjectType","subjectId","connectionId","server","primitive","tool","policyVersion","decision","dispatchedAt","finishedAt","outcome","latencyMs","costUsd","costSource","guardFindings","reason","mount","skillVersionId","sessionId","subjectName","subjectEmail"],"additionalProperties":false}}},"required":["rows"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":200,"type":"integer","minimum":1,"maximum":500}},{"name":"decision","in":"query","required":false,"schema":{"type":"string","enum":["allowed","denied","approval_pending","approved","rejected"]}},{"name":"outcome","in":"query","required":false,"schema":{"type":"string","enum":["ok","failed","unknown"]}},{"name":"primitive","in":"query","required":false,"schema":{"type":"string","enum":["tool","resource","prompt"]}},{"name":"key_id","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}}]}},"/connections":{"get":{"operationId":"connections.list","summary":"List every upstream connection: whose it is, the provider, scopes, state and last use. Never a token.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"connections:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"connections":{"type":"array","items":{"type":"object","properties":{"connectionId":{"type":"string"},"subjectType":{"type":"string","enum":["human","workload"]},"subjectId":{"type":"string"},"subjectLabel":{"type":"string"},"provider":{"type":"string"},"providerName":{"type":"string"},"audience":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"state":{"type":"string","enum":["active","reauth_required","revoked"]},"stateReason":{"type":["string","null"]},"expiresAt":{"type":["string","null"]},"createdAt":{"type":"string"},"lastUsedAt":{"type":["string","null"]},"revokedAt":{"type":["string","null"]}},"required":["connectionId","subjectType","subjectId","subjectLabel","provider","providerName","audience","scopes","state","stateReason","expiresAt","createdAt","lastUsedAt","revokedAt"],"additionalProperties":false}}},"required":["connections"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"connections.start","summary":"Start a consent for a service-account key: answers the URL the caller's browser consents at. The gateway completes it. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"provider":{"type":"string","minLength":1},"keyId":{"type":"string","minLength":1},"scopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string"}]}},"required":["provider","keyId"]}}}}}},"/connections/providers":{"get":{"operationId":"connections.providers.list","summary":"List the OAuth providers a person may connect an account at, with their endpoints. Never the client secret.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"connections:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"displayName":{"type":"string"},"authorizationUrl":{"type":"string"},"tokenUrl":{"type":"string"},"revocationUrl":{"type":["string","null"]},"clientId":{"type":"string"},"hasSecret":{"type":"boolean"},"audience":{"type":"string"},"defaultScopes":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"updatedAt":{"type":"string"}},"required":["provider","displayName","authorizationUrl","tokenUrl","revocationUrl","clientId","hasSecret","audience","defaultScopes","enabled","updatedAt"],"additionalProperties":false}}},"required":["providers"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"connections.providers.create","summary":"Register an OAuth provider, its client secret sealed for the gateway. An existing id is a 409. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"provider":{"type":"string"},"displayName":{"type":"string"},"authorizationUrl":{"type":"string"},"tokenUrl":{"type":"string"},"revocationUrl":{"type":["string","null"]},"clientId":{"type":"string"},"audience":{"type":"string"},"defaultScopes":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"clientSecret":{"type":"string"}},"required":["provider","displayName","authorizationUrl","tokenUrl","clientId","audience"]}}}}}},"/tools/servers/{id}":{"put":{"operationId":"tools.servers.update","summary":"Edit, disable or enable a registered server; the body is merged onto the stored definition. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"server":{"type":"object","properties":{"serverId":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"transport":{"type":"string","enum":["http","sse"]},"authType":{"type":"string","enum":["none","api_key","bearer_token","oauth2"]},"enabled":{"type":"boolean"},"description":{"type":["string","null"]},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"readOnly":{"type":"boolean"},"destructive":{"type":"boolean"},"description":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"mask":{"type":"array","items":{"type":"string"}},"rateLimit":{"anyOf":[{"type":"object","properties":{"requests":{"type":"number"},"windowSeconds":{"type":"number"}},"required":["requests","windowSeconds"],"additionalProperties":false},{"type":"null"}]},"requiresApproval":{"type":"boolean"},"allowedParams":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rest":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string"},"parameters":{"$ref":"#/$defs/__schema0"}},"required":["method","path","parameters"],"additionalProperties":false},"policyInvalid":{"type":"boolean"}},"required":["name","readOnly","destructive","description"],"additionalProperties":false}},"resources":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"policyInvalid":{"type":"boolean"}},"required":["uri","name","description","mimeType"],"additionalProperties":false}},"prompts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"policyInvalid":{"type":"boolean"}},"required":["name","description"],"additionalProperties":false}},"custody":{"type":"string","enum":["service","connection"]},"provider":{"type":["string","null"]},"audience":{"type":["string","null"]},"maxScopes":{"type":"array","items":{"type":"string"}},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"header":{"type":"string"},"description":{"type":["string","null"]},"required":{"type":"boolean"}},"required":["name","header","description","required"],"additionalProperties":false}},"kind":{"type":"string","enum":["mcp","rest"]},"restAuth":{"anyOf":[{"type":"object","properties":{"location":{"type":"string","enum":["header","query"]},"name":{"type":"string"},"prefix":{"type":["string","null"]}},"required":["location","name","prefix"],"additionalProperties":false},{"type":"null"}]}},"required":["serverId","name","url","transport","authType","enabled","description","tools","resources","prompts"],"additionalProperties":false},"chassis":{"type":"object","properties":{"synced":{"type":"boolean"},"error":{"type":["string","null"]},"keys":{"type":"object","properties":{"synced":{"type":"number"},"failed":{"type":"number"}},"required":["synced","failed"],"additionalProperties":false}},"required":["synced","error","keys"],"additionalProperties":false}},"required":["server","chassis"],"additionalProperties":false,"$defs":{"__schema0":{"type":"object","properties":{"type":{"type":"string","enum":["object","array","string","number","integer","boolean","null"]},"description":{"type":"string"},"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"required":{"type":"array","items":{"type":"string"}},"visible":{"type":"array","items":{"type":"string"}},"items":{"$ref":"#/$defs/__schema0"},"enum":{"type":"array","items":{}},"default":{}},"additionalProperties":{}}}}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"serverId":{"type":"string"},"kind":{"type":"string","enum":["mcp","rest"]},"name":{"type":"string"},"url":{"type":"string"},"transport":{"type":"string","enum":["http","sse"]},"authType":{"type":"string","enum":["none","api_key","bearer_token","oauth2"]},"enabled":{"type":"boolean"},"description":{"type":["string","null"]},"tools":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"resources":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"prompts":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"variables":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"null"}]},"custody":{"type":"string","enum":["service","connection"]},"provider":{"type":["string","null"]},"audience":{"type":["string","null"]},"maxScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"restAuth":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"credential":{"type":["string","null"]},"clearCredential":{"type":"boolean"}}}}}}},"delete":{"operationId":"tools.servers.delete","summary":"Remove a registered server. Grants that name it stay, inert, and revive if the id returns. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"chassis":{"type":"object","properties":{"synced":{"type":"boolean"},"error":{"type":["string","null"]},"keys":{"type":"object","properties":{"synced":{"type":"number"},"failed":{"type":"number"}},"required":["synced","failed"],"additionalProperties":false}},"required":["synced","error","keys"],"additionalProperties":false}},"required":["ok","chassis"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/tools/servers/{id}/discover":{"get":{"operationId":"tools.servers.discover","summary":"List what a registered MCP server offers now, through the chassis WITH THE SERVICE CREDENTIAL, against what it declares. Writes nothing. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"serverId":{"type":"string"},"separator":{"type":"string"},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["served","undeclared","missing"]},"offered":{"anyOf":[{"type":"object","properties":{"chassisName":{"type":"string"},"description":{"type":["string","null"]},"params":{"type":"array","items":{"type":"string"}},"readOnlyHint":{"type":["boolean","null"]},"destructiveHint":{"type":["boolean","null"]}},"required":["chassisName","description","params","readOnlyHint","destructiveHint"],"additionalProperties":false},{"type":"null"}]},"declaredReadOnly":{"type":["boolean","null"]}},"required":["name","status","offered","declaredReadOnly"],"additionalProperties":false}},"unprefixed":{"type":"array","items":{"type":"string"}}},"required":["serverId","separator","tools","unprefixed"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/teams/{id}":{"delete":{"operationId":"teams.delete","summary":"Remove an EMPTY team with its tool grant. A team with member keys is a 409 with the count. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/teams/tools":{"post":{"operationId":"teams.tools.set","summary":"Set a team's tool grant, AND-ed with each member key's own, then push every member key. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"access":{"type":"object","properties":{"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"readOnly":{"type":"boolean"},"version":{"type":"number"},"syncedVersion":{"type":["number","null"]},"syncedAt":{"type":["string","null"]},"syncError":{"type":["string","null"]},"status":{"type":"string","enum":["none","drift","ready"]}},"required":["servers","tools","resources","prompts","groups","readOnly","version","syncedVersion","syncedAt","syncError","status"],"additionalProperties":false}},"required":["access"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"teamId":{"type":"string","minLength":1},"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"readOnly":{"type":"boolean"}},"required":["teamId","servers","tools","readOnly"]}}}}},"delete":{"operationId":"teams.tools.revoke","summary":"Remove a team's tool grant: every key in the team then has NO tools. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"team_id","in":"query","required":true,"schema":{"type":"string","minLength":1}}]}},"/teams/tools/resync":{"post":{"operationId":"teams.tools.resync","summary":"Push a team's stored grant to every member key again, after a failed sync. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"access":{"type":"object","properties":{"servers":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"readOnly":{"type":"boolean"},"version":{"type":"number"},"syncedVersion":{"type":["number","null"]},"syncedAt":{"type":["string","null"]},"syncError":{"type":["string","null"]},"status":{"type":"string","enum":["none","drift","ready"]}},"required":["servers","tools","resources","prompts","groups","readOnly","version","syncedVersion","syncedAt","syncError","status"],"additionalProperties":false}},"required":["access"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"teamId":{"type":"string","minLength":1}},"required":["teamId"]}}}}}},"/tools/groups/{id}":{"delete":{"operationId":"tools.groups.delete","summary":"Remove a tool group. Grants that name it keep the name, which grants nothing; each is re-pushed. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"sync":{"type":"object","properties":{"synced":{"type":"number"},"failed":{"type":"number"},"affected":{"type":"number"}},"required":["synced","failed","affected"],"additionalProperties":false}},"required":["ok","sync"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/tools/virtual-servers/{id}":{"delete":{"operationId":"tools.virtual-servers.delete","summary":"Remove a virtual server; its endpoint answers 404 from the gateway's next poll. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/tools/approvals":{"get":{"operationId":"tools.approvals.list","summary":"List the tool calls parked for an approval, newest first, with their ARGUMENTS while open. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"toolCallId":{"type":"number"},"keyId":{"type":"string"},"subjectType":{"type":"string","enum":["human","workload"]},"subjectId":{"type":"string"},"server":{"type":"string"},"tool":{"type":"string"},"argsHash":{"type":"string"},"arguments":{},"status":{"type":"string","enum":["pending","approved","consumed","rejected","cancelled","expired"]},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"decidedBy":{"type":["string","null"]},"decidedAt":{"type":["string","null"]},"consumedAt":{"type":["string","null"]},"reportedAt":{"type":["string","null"]},"subjectName":{"type":["string","null"]},"subjectEmail":{"type":["string","null"]},"decidedByName":{"type":["string","null"]},"selfDecided":{"type":"boolean"}},"required":["id","toolCallId","keyId","subjectType","subjectId","server","tool","argsHash","arguments","status","createdAt","expiresAt","decidedBy","decidedAt","consumedAt","reportedAt","subjectName","subjectEmail","decidedByName","selfDecided"],"additionalProperties":false}}},"required":["rows"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","pending","approved","consumed","rejected","cancelled","expired"]}},{"name":"limit","in":"query","required":false,"schema":{"default":200,"type":"integer","minimum":1,"maximum":500}}]}},"/tools/approvals/{id}":{"post":{"operationId":"tools.approvals.decide","summary":"Approve, reject or withdraw one parked tool call. Nothing runs here: the gateway runs the agent's identical retry. A row that already moved is a 409. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"approval":{"type":"object","properties":{"id":{"type":"string"},"toolCallId":{"type":"number"},"keyId":{"type":"string"},"subjectType":{"type":"string","enum":["human","workload"]},"subjectId":{"type":"string"},"server":{"type":"string"},"tool":{"type":"string"},"argsHash":{"type":"string"},"arguments":{},"status":{"type":"string","enum":["pending","approved","consumed","rejected","cancelled","expired"]},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"decidedBy":{"type":["string","null"]},"decidedAt":{"type":["string","null"]},"consumedAt":{"type":["string","null"]},"reportedAt":{"type":["string","null"]},"subjectName":{"type":["string","null"]},"subjectEmail":{"type":["string","null"]},"decidedByName":{"type":["string","null"]},"selfDecided":{"type":"boolean"}},"required":["id","toolCallId","keyId","subjectType","subjectId","server","tool","argsHash","arguments","status","createdAt","expiresAt","decidedBy","decidedAt","consumedAt","reportedAt","subjectName","subjectEmail","decidedByName","selfDecided"],"additionalProperties":false}},"required":["approval"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"decision":{"type":"string","enum":["approve","reject","cancel"]}},"required":["decision"]}}}}}},"/connections/{id}":{"delete":{"operationId":"connections.revoke","summary":"Revoke any connection locally; the gateway's sweep revokes it upstream. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/connections/providers/{id}":{"put":{"operationId":"connections.providers.update","summary":"Edit a provider's endpoints, client or secret; the body is merged onto the stored row. A changed audience needs the secret again. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"provider":{"type":"string"},"displayName":{"type":"string"},"authorizationUrl":{"type":"string"},"tokenUrl":{"type":"string"},"revocationUrl":{"type":["string","null"]},"clientId":{"type":"string"},"audience":{"type":"string"},"defaultScopes":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"clientSecret":{"type":"string"}}}}}}},"delete":{"operationId":"connections.providers.delete","summary":"Remove an OAuth provider. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/context-packs":{"get":{"operationId":"packs.list","summary":"List the context packs: access policy, published and retired versions with their hashes, assignments and the settings. Never a version's text or a draft.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"packs:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"packs":{"type":"array","items":{"type":"object","properties":{"packId":{"type":"string"},"tenant":{"type":"string"},"ownerUserId":{"type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"classification":{"type":"string","enum":["public","internal","confidential"]},"accessPolicy":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"subjectTypes":{"type":"array","items":{"type":"string","enum":["human","workload"]}}},"required":["keys","subjectTypes"],"additionalProperties":false},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"ownerEmail":{"type":["string","null"]},"versions":{"type":"array","items":{"type":"object","properties":{"versionId":{"type":"string"},"seq":{"type":"number"},"state":{"type":"string","enum":["draft","published","retired"]},"hash":{"type":"string"},"mimeType":{"type":"string"},"locale":{"type":"string"},"createdAt":{"type":"string"},"publishedAt":{"type":["string","null"]},"retiredAt":{"type":["string","null"]}},"required":["versionId","seq","state","hash","mimeType","locale","createdAt","publishedAt","retiredAt"],"additionalProperties":false}},"assignments":{"type":"array","items":{"type":"object","properties":{"assignmentId":{"type":"string"},"packId":{"type":"string"},"selectorKind":{"type":"string","enum":["any","key","user"]},"selectorId":{"type":["string","null"]},"route":{"type":"string"},"pinnedVersionId":{"type":["string","null"]},"priority":{"type":"number"},"budgetTokens":{"type":["number","null"]},"delivery":{"type":"string","enum":["whole","retrieve"]},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["assignmentId","packId","selectorKind","selectorId","route","pinnedVersionId","priority","budgetTokens","delivery","enabled","createdAt","updatedAt"],"additionalProperties":false}}},"required":["packId","tenant","ownerUserId","title","description","classification","accessPolicy","enabled","createdAt","updatedAt","ownerEmail","versions","assignments"],"additionalProperties":false}},"settings":{"type":"object","properties":{"enabled":{"type":"boolean"},"defaultBudgetTokens":{"type":["number","null"]},"reservedOutputTokens":{"type":"number"}},"required":["enabled","defaultBudgetTokens","reservedOutputTokens"],"additionalProperties":false}},"required":["packs","settings"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"packs.create","summary":"Create a context pack. It has no version and prepends nothing until one is published. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"pack":{"type":"object","properties":{"packId":{"type":"string"},"tenant":{"type":"string"},"ownerUserId":{"type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"classification":{"type":"string","enum":["public","internal","confidential"]},"accessPolicy":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"subjectTypes":{"type":"array","items":{"type":"string","enum":["human","workload"]}}},"required":["keys","subjectTypes"],"additionalProperties":false},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["packId","tenant","ownerUserId","title","description","classification","accessPolicy","enabled","createdAt","updatedAt"],"additionalProperties":false}},"required":["pack"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"packId":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"classification":{"type":"string","enum":["public","internal","confidential"]},"accessPolicy":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"subjectTypes":{"type":"array","items":{"type":"string","enum":["human","workload"]}}}},"enabled":{"type":"boolean"},"ownerUserId":{"type":["string","null"]}},"required":["packId","title"]}}}}},"put":{"operationId":"packs.settings.update","summary":"Change the context-pack settings: the master switch and the two budget numbers. The body is merged onto the stored settings. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"settings":{"type":"object","properties":{"enabled":{"type":"boolean"},"defaultBudgetTokens":{"type":["number","null"]},"reservedOutputTokens":{"type":"number"}},"required":["enabled","defaultBudgetTokens","reservedOutputTokens"],"additionalProperties":false}},"required":["settings"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"enabled":{"type":"boolean"},"defaultBudgetTokens":{"type":["number","null"]},"reservedOutputTokens":{"type":"number"}}}}}}}},"/context-packs/{id}/versions":{"get":{"operationId":"packs.versions.list","summary":"Read every version of one pack with its text, drafts and screening records included. A read of company material. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"versions":{"type":"array","items":{"type":"object","properties":{"versionId":{"type":"string"},"packId":{"type":"string"},"seq":{"type":"number"},"content":{"type":"string"},"mimeType":{"type":"string"},"locale":{"type":"string"},"hash":{"type":"string"},"state":{"type":"string","enum":["draft","published","retired"]},"createdByUserId":{"type":["string","null"]},"createdAt":{"type":"string"},"publishedByUserId":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"retiredAt":{"type":["string","null"]},"reviewRequestedByUserId":{"type":["string","null"]},"reviewRequestedAt":{"type":["string","null"]},"screening":{"anyOf":[{"type":"object","properties":{"screenedAt":{"type":"string"},"action":{"type":"string","enum":["allow","flag","block"]},"screened":{"type":"boolean"},"routes":{"type":"array","items":{"type":"string"}},"guards":{"type":"array","items":{"type":"string"}},"coveredBy":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"category":{"type":"string"}},"required":["guard","category"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"action":{"type":"string"},"category":{"type":["string","null"]},"ruleId":{"type":["string","null"]},"ruleType":{"type":["string","null"]},"routes":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["console","gateway"]}},"required":["guard","action","category","ruleId","ruleType","routes","source"],"additionalProperties":false}},"gateway":{"anyOf":[{"type":"object","properties":{"asked":{"type":"boolean","const":false}},"required":["asked"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":true}},"required":["asked","answered"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["asked","answered","error"],"additionalProperties":false}]}},"required":["screenedAt","action","screened","routes","guards","coveredBy","unavailable","findings","gateway"],"additionalProperties":false},{"type":"null"}]},"createdByEmail":{"type":["string","null"]},"reviewRequestedByEmail":{"type":["string","null"]},"publishedByEmail":{"type":["string","null"]}},"required":["versionId","packId","seq","content","mimeType","locale","hash","state","createdByUserId","createdAt","publishedByUserId","publishedAt","retiredAt","reviewRequestedByUserId","reviewRequestedAt","screening","createdByEmail","reviewRequestedByEmail","publishedByEmail"],"additionalProperties":false}}},"required":["versions"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"operationId":"packs.versions.create","summary":"Open a draft version of a pack. A draft is editable and served by nothing. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"version":{"type":"object","properties":{"versionId":{"type":"string"},"packId":{"type":"string"},"seq":{"type":"number"},"content":{"type":"string"},"mimeType":{"type":"string"},"locale":{"type":"string"},"hash":{"type":"string"},"state":{"type":"string","enum":["draft","published","retired"]},"createdByUserId":{"type":["string","null"]},"createdAt":{"type":"string"},"publishedByUserId":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"retiredAt":{"type":["string","null"]},"reviewRequestedByUserId":{"type":["string","null"]},"reviewRequestedAt":{"type":["string","null"]},"screening":{"anyOf":[{"type":"object","properties":{"screenedAt":{"type":"string"},"action":{"type":"string","enum":["allow","flag","block"]},"screened":{"type":"boolean"},"routes":{"type":"array","items":{"type":"string"}},"guards":{"type":"array","items":{"type":"string"}},"coveredBy":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"category":{"type":"string"}},"required":["guard","category"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"action":{"type":"string"},"category":{"type":["string","null"]},"ruleId":{"type":["string","null"]},"ruleType":{"type":["string","null"]},"routes":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["console","gateway"]}},"required":["guard","action","category","ruleId","ruleType","routes","source"],"additionalProperties":false}},"gateway":{"anyOf":[{"type":"object","properties":{"asked":{"type":"boolean","const":false}},"required":["asked"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":true}},"required":["asked","answered"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["asked","answered","error"],"additionalProperties":false}]}},"required":["screenedAt","action","screened","routes","guards","coveredBy","unavailable","findings","gateway"],"additionalProperties":false},{"type":"null"}]}},"required":["versionId","packId","seq","content","mimeType","locale","hash","state","createdByUserId","createdAt","publishedByUserId","publishedAt","retiredAt","reviewRequestedByUserId","reviewRequestedAt","screening"],"additionalProperties":false}},"required":["version"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"content":{"type":"string"},"mimeType":{"type":"string"},"locale":{"type":"string"}},"required":["content"]}}}}}},"/context-packs/{id}":{"put":{"operationId":"packs.update","summary":"Edit a pack's title, classification, access policy, owner or switch. A PARTIAL body: Disable is one field. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"pack":{"type":"object","properties":{"packId":{"type":"string"},"tenant":{"type":"string"},"ownerUserId":{"type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"classification":{"type":"string","enum":["public","internal","confidential"]},"accessPolicy":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"subjectTypes":{"type":"array","items":{"type":"string","enum":["human","workload"]}}},"required":["keys","subjectTypes"],"additionalProperties":false},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["packId","tenant","ownerUserId","title","description","classification","accessPolicy","enabled","createdAt","updatedAt"],"additionalProperties":false}},"required":["pack"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"packId":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"classification":{"type":"string","enum":["public","internal","confidential"]},"accessPolicy":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"subjectTypes":{"type":"array","items":{"type":"string","enum":["human","workload"]}}}},"enabled":{"type":"boolean"},"ownerUserId":{"type":["string","null"]}}}}}}},"delete":{"operationId":"packs.delete","summary":"Remove a pack with its versions and assignments. Disabling it is the reversible form. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/context-packs/{id}/versions/{versionId}":{"put":{"operationId":"packs.versions.update","summary":"Edit a draft, ask for its review, publish it (screened first; a block or an unanswered guard refuses) or retire a published version. A published version never changes. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"version":{"type":"object","properties":{"versionId":{"type":"string"},"packId":{"type":"string"},"seq":{"type":"number"},"content":{"type":"string"},"mimeType":{"type":"string"},"locale":{"type":"string"},"hash":{"type":"string"},"state":{"type":"string","enum":["draft","published","retired"]},"createdByUserId":{"type":["string","null"]},"createdAt":{"type":"string"},"publishedByUserId":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"retiredAt":{"type":["string","null"]},"reviewRequestedByUserId":{"type":["string","null"]},"reviewRequestedAt":{"type":["string","null"]},"screening":{"anyOf":[{"type":"object","properties":{"screenedAt":{"type":"string"},"action":{"type":"string","enum":["allow","flag","block"]},"screened":{"type":"boolean"},"routes":{"type":"array","items":{"type":"string"}},"guards":{"type":"array","items":{"type":"string"}},"coveredBy":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"category":{"type":"string"}},"required":["guard","category"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"action":{"type":"string"},"category":{"type":["string","null"]},"ruleId":{"type":["string","null"]},"ruleType":{"type":["string","null"]},"routes":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["console","gateway"]}},"required":["guard","action","category","ruleId","ruleType","routes","source"],"additionalProperties":false}},"gateway":{"anyOf":[{"type":"object","properties":{"asked":{"type":"boolean","const":false}},"required":["asked"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":true}},"required":["asked","answered"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["asked","answered","error"],"additionalProperties":false}]}},"required":["screenedAt","action","screened","routes","guards","coveredBy","unavailable","findings","gateway"],"additionalProperties":false},{"type":"null"}]}},"required":["versionId","packId","seq","content","mimeType","locale","hash","state","createdByUserId","createdAt","publishedByUserId","publishedAt","retiredAt","reviewRequestedByUserId","reviewRequestedAt","screening"],"additionalProperties":false}},"required":["version"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"state":{"type":"string","enum":["published","retired"]},"review":{"type":"boolean"},"content":{"type":"string"},"mimeType":{"type":"string"},"locale":{"type":"string"}}}}}}},"delete":{"operationId":"packs.versions.delete","summary":"Delete a draft. A published or retired version is history and stays: retire it instead. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"}}]}},"/context-packs/{id}/assignments":{"post":{"operationId":"packs.assignments.create","summary":"Assign a pack to a (selector, route): where it is offered. Who may see it is the pack's own access policy. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assignment":{"type":"object","properties":{"assignmentId":{"type":"string"},"packId":{"type":"string"},"selectorKind":{"type":"string","enum":["any","key","user"]},"selectorId":{"type":["string","null"]},"route":{"type":"string"},"pinnedVersionId":{"type":["string","null"]},"priority":{"type":"number"},"budgetTokens":{"type":["number","null"]},"delivery":{"type":"string","enum":["whole","retrieve"]},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["assignmentId","packId","selectorKind","selectorId","route","pinnedVersionId","priority","budgetTokens","delivery","enabled","createdAt","updatedAt"],"additionalProperties":false}},"required":["assignment"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"selectorKind":{"type":"string","enum":["any","key","user"]},"selectorId":{"type":["string","null"]},"route":{"type":"string"},"pinnedVersionId":{"type":["string","null"]},"priority":{"type":"number"},"budgetTokens":{"type":["number","null"]},"delivery":{"type":"string","enum":["whole","retrieve"]},"enabled":{"type":"boolean"}},"required":["selectorKind","route"]}}}}}},"/context-packs/{id}/assignments/{assignmentId}":{"put":{"operationId":"packs.assignments.update","summary":"Edit an assignment in place. A PARTIAL body: Disable is one field. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"assignment":{"type":"object","properties":{"assignmentId":{"type":"string"},"packId":{"type":"string"},"selectorKind":{"type":"string","enum":["any","key","user"]},"selectorId":{"type":["string","null"]},"route":{"type":"string"},"pinnedVersionId":{"type":["string","null"]},"priority":{"type":"number"},"budgetTokens":{"type":["number","null"]},"delivery":{"type":"string","enum":["whole","retrieve"]},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["assignmentId","packId","selectorKind","selectorId","route","pinnedVersionId","priority","budgetTokens","delivery","enabled","createdAt","updatedAt"],"additionalProperties":false}},"required":["assignment"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assignmentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"selectorKind":{"type":"string","enum":["any","key","user"]},"selectorId":{"type":["string","null"]},"route":{"type":"string"},"pinnedVersionId":{"type":["string","null"]},"priority":{"type":"number"},"budgetTokens":{"type":["number","null"]},"delivery":{"type":"string","enum":["whole","retrieve"]},"enabled":{"type":"boolean"}}}}}}},"delete":{"operationId":"packs.assignments.delete","summary":"Remove an assignment. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assignmentId","in":"path","required":true,"schema":{"type":"string"}}]}},"/skills":{"get":{"operationId":"skills.list","summary":"List the company skills: who may select each, and every published or retired version's title, digest and declared requirements. Never a procedure's text, a draft or a review comment.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"skills:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string"},"tenant":{"type":"string"},"ownerUserId":{"type":["string","null"]},"accessPolicy":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"subjectTypes":{"type":"array","items":{"type":"string","enum":["human","workload"]}}},"required":["keys","subjectTypes"],"additionalProperties":false},"enabled":{"type":"boolean"},"invalid":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"promptName":{"type":"string"},"ownerEmail":{"type":["string","null"]},"versions":{"type":"array","items":{"type":"object","properties":{"versionId":{"type":"string"},"seq":{"type":"number"},"title":{"type":"string"},"digest":{"type":"string"},"state":{"type":"string","enum":["draft","published","retired"]},"requires":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}}},"required":["tools","resources","prompts"],"additionalProperties":false},"compatibility":{"type":"object","properties":{"clients":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]}},"required":["clients","notes"],"additionalProperties":false},"reviewed":{"type":"array","items":{"type":"object","properties":{"primitive":{"type":"string","enum":["tool","resource","prompt"]},"name":{"type":"string"},"readOnly":{"type":"boolean"},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"custody":{"type":"string","enum":["service","connection"]}},"required":["primitive","name","readOnly","requiredScopes","custody"],"additionalProperties":false}},"selfReviewed":{"type":"boolean"},"publishedAt":{"type":["string","null"]},"publishedByEmail":{"type":["string","null"]},"retiredAt":{"type":["string","null"]},"invalid":{"type":"boolean"}},"required":["versionId","seq","title","digest","state","requires","compatibility","reviewed","selfReviewed","publishedAt","publishedByEmail","retiredAt"],"additionalProperties":false}},"servedVersionId":{"type":["string","null"]},"rollbackVersionId":{"type":["string","null"]}},"required":["skillId","tenant","ownerUserId","accessPolicy","enabled","createdAt","updatedAt","promptName","ownerEmail","versions","servedVersionId","rollbackVersionId"],"additionalProperties":false}},"settings":{"type":"object","properties":{"allowSelfPublish":{"type":"boolean"}},"required":["allowSelfPublish"],"additionalProperties":false}},"required":["skills","settings"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"skills.create","summary":"Create a skill. It has no version and is selectable by nobody until one is published. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"skill":{"type":"object","properties":{"skillId":{"type":"string"},"tenant":{"type":"string"},"ownerUserId":{"type":["string","null"]},"accessPolicy":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"subjectTypes":{"type":"array","items":{"type":"string","enum":["human","workload"]}}},"required":["keys","subjectTypes"],"additionalProperties":false},"enabled":{"type":"boolean"},"invalid":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["skillId","tenant","ownerUserId","accessPolicy","enabled","createdAt","updatedAt"],"additionalProperties":false}},"required":["skill"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"skillId":{"type":"string"},"accessPolicy":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"subjectTypes":{"type":"array","items":{"type":"string","enum":["human","workload"]}}}},"enabled":{"type":"boolean"},"ownerUserId":{"type":["string","null"]}},"required":["skillId"]}}}}},"put":{"operationId":"skills.settings.update","summary":"Set the owner's switch: whether an admin may publish their own skill without a second reviewer. Owner only. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"owner","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"settings":{"type":"object","properties":{"allowSelfPublish":{"type":"boolean"}},"required":["allowSelfPublish"],"additionalProperties":false}},"required":["settings"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"allowSelfPublish":{"type":"boolean"}},"required":["allowSelfPublish"]}}}}}},"/skills/{id}/versions":{"get":{"operationId":"skills.versions.list","summary":"Read every version of one skill with its procedure, drafts and review comments included. A read of company material. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"versions":{"type":"array","items":{"type":"object","properties":{"versionId":{"type":"string"},"skillId":{"type":"string"},"seq":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"content":{"type":"string"},"requires":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}}},"required":["tools","resources","prompts"],"additionalProperties":false},"compatibility":{"type":"object","properties":{"clients":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]}},"required":["clients","notes"],"additionalProperties":false},"digest":{"type":"string"},"state":{"type":"string","enum":["draft","published","retired"]},"reviewed":{"type":"array","items":{"type":"object","properties":{"primitive":{"type":"string","enum":["tool","resource","prompt"]},"name":{"type":"string"},"readOnly":{"type":"boolean"},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"custody":{"type":"string","enum":["service","connection"]}},"required":["primitive","name","readOnly","requiredScopes","custody"],"additionalProperties":false}},"publishedAt":{"type":["string","null"]},"publishedByEmail":{"type":["string","null"]},"invalid":{"type":"boolean"},"createdByUserId":{"type":["string","null"]},"createdAt":{"type":"string"},"lastEditedByUserId":{"type":["string","null"]},"updatedAt":{"type":"string"},"reviewRequestedByUserId":{"type":["string","null"]},"reviewRequestedAt":{"type":["string","null"]},"reviewDigest":{"type":["string","null"]},"screening":{"anyOf":[{"type":"object","properties":{"screenedAt":{"type":"string"},"action":{"type":"string","enum":["allow","flag","block"]},"screened":{"type":"boolean"},"routes":{"type":"array","items":{"type":"string"}},"guards":{"type":"array","items":{"type":"string"}},"coveredBy":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"category":{"type":"string"}},"required":["guard","category"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"action":{"type":"string"},"category":{"type":["string","null"]},"ruleId":{"type":["string","null"]},"ruleType":{"type":["string","null"]},"routes":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["console","gateway"]}},"required":["guard","action","category","ruleId","ruleType","routes","source"],"additionalProperties":false}},"gateway":{"anyOf":[{"type":"object","properties":{"asked":{"type":"boolean","const":false}},"required":["asked"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":true}},"required":["asked","answered"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["asked","answered","error"],"additionalProperties":false}]}},"required":["screenedAt","action","screened","routes","guards","coveredBy","unavailable","findings","gateway"],"additionalProperties":false},{"type":"null"}]},"publishedByUserId":{"type":["string","null"]},"retiredByUserId":{"type":["string","null"]},"retiredAt":{"type":["string","null"]},"reviewerUserId":{"type":["string","null"]},"changesRequestedAt":{"type":["string","null"]},"changesRequestedContent":{"type":["string","null"]},"selfReviewed":{"type":"boolean"},"contributorUserIds":{"type":"array","items":{"type":"string"}},"createdByEmail":{"type":["string","null"]},"lastEditedByEmail":{"type":["string","null"]},"reviewRequestedByEmail":{"type":["string","null"]},"reviewerEmail":{"type":["string","null"]},"retiredByEmail":{"type":["string","null"]},"contributorEmails":{"type":"array","items":{"type":"string"}},"comments":{"type":"array","items":{"type":"object","properties":{"commentId":{"type":"string"},"versionId":{"type":"string"},"digest":{"type":"string"},"line":{"type":["number","null"]},"quote":{"type":["string","null"]},"body":{"type":"string"},"authorUserId":{"type":["string","null"]},"authorEmail":{"type":["string","null"]},"state":{"type":"string","enum":["open","resolved"]},"reply":{"type":["string","null"]},"resolvedByUserId":{"type":["string","null"]},"resolvedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["commentId","versionId","digest","line","quote","body","authorUserId","authorEmail","state","reply","resolvedByUserId","resolvedAt","createdAt"],"additionalProperties":false}},"reviewText":{"type":"string"},"undeclaredMentions":{"type":"array","items":{"type":"string"}}},"required":["versionId","skillId","seq","title","description","content","requires","compatibility","digest","state","reviewed","publishedAt","publishedByEmail","createdByUserId","createdAt","lastEditedByUserId","updatedAt","reviewRequestedByUserId","reviewRequestedAt","reviewDigest","screening","publishedByUserId","retiredByUserId","retiredAt","reviewerUserId","changesRequestedAt","changesRequestedContent","selfReviewed","contributorUserIds","createdByEmail","lastEditedByEmail","reviewRequestedByEmail","reviewerEmail","retiredByEmail","contributorEmails","comments","reviewText","undeclaredMentions"],"additionalProperties":false}},"choices":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}}},"required":["tools","resources","prompts"],"additionalProperties":false},"reviewers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"}},"required":["id","email","name"],"additionalProperties":false}}},"required":["versions","choices","reviewers"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"operationId":"skills.versions.create","summary":"Open a draft version of a skill, from fields or from an earlier version's text. The opener is its author and may not approve it. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"version":{"type":"object","properties":{"versionId":{"type":"string"},"skillId":{"type":"string"},"seq":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"content":{"type":"string"},"requires":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}}},"required":["tools","resources","prompts"],"additionalProperties":false},"compatibility":{"type":"object","properties":{"clients":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]}},"required":["clients","notes"],"additionalProperties":false},"digest":{"type":"string"},"state":{"type":"string","enum":["draft","published","retired"]},"reviewed":{"type":"array","items":{"type":"object","properties":{"primitive":{"type":"string","enum":["tool","resource","prompt"]},"name":{"type":"string"},"readOnly":{"type":"boolean"},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"custody":{"type":"string","enum":["service","connection"]}},"required":["primitive","name","readOnly","requiredScopes","custody"],"additionalProperties":false}},"publishedAt":{"type":["string","null"]},"publishedByEmail":{"type":["string","null"]},"invalid":{"type":"boolean"},"createdByUserId":{"type":["string","null"]},"createdAt":{"type":"string"},"lastEditedByUserId":{"type":["string","null"]},"updatedAt":{"type":"string"},"reviewRequestedByUserId":{"type":["string","null"]},"reviewRequestedAt":{"type":["string","null"]},"reviewDigest":{"type":["string","null"]},"screening":{"anyOf":[{"type":"object","properties":{"screenedAt":{"type":"string"},"action":{"type":"string","enum":["allow","flag","block"]},"screened":{"type":"boolean"},"routes":{"type":"array","items":{"type":"string"}},"guards":{"type":"array","items":{"type":"string"}},"coveredBy":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"category":{"type":"string"}},"required":["guard","category"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"action":{"type":"string"},"category":{"type":["string","null"]},"ruleId":{"type":["string","null"]},"ruleType":{"type":["string","null"]},"routes":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["console","gateway"]}},"required":["guard","action","category","ruleId","ruleType","routes","source"],"additionalProperties":false}},"gateway":{"anyOf":[{"type":"object","properties":{"asked":{"type":"boolean","const":false}},"required":["asked"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":true}},"required":["asked","answered"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["asked","answered","error"],"additionalProperties":false}]}},"required":["screenedAt","action","screened","routes","guards","coveredBy","unavailable","findings","gateway"],"additionalProperties":false},{"type":"null"}]},"publishedByUserId":{"type":["string","null"]},"retiredByUserId":{"type":["string","null"]},"retiredAt":{"type":["string","null"]},"reviewerUserId":{"type":["string","null"]},"changesRequestedAt":{"type":["string","null"]},"changesRequestedContent":{"type":["string","null"]},"selfReviewed":{"type":"boolean"},"contributorUserIds":{"type":"array","items":{"type":"string"}}},"required":["versionId","skillId","seq","title","description","content","requires","compatibility","digest","state","reviewed","publishedAt","publishedByEmail","createdByUserId","createdAt","lastEditedByUserId","updatedAt","reviewRequestedByUserId","reviewRequestedAt","reviewDigest","screening","publishedByUserId","retiredByUserId","retiredAt","reviewerUserId","changesRequestedAt","changesRequestedContent","selfReviewed","contributorUserIds"],"additionalProperties":false}},"required":["version"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"fromVersionId":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"content":{"type":"string"},"requires":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}}}},"compatibility":{"type":"object","properties":{"clients":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]}}}}}}}}}},"/skills/{id}":{"put":{"operationId":"skills.update","summary":"Edit who may select a skill, whether it is on, or who owns it. A PARTIAL body; no review, because none of it is text an agent reads. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"skill":{"type":"object","properties":{"skillId":{"type":"string"},"tenant":{"type":"string"},"ownerUserId":{"type":["string","null"]},"accessPolicy":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"subjectTypes":{"type":"array","items":{"type":"string","enum":["human","workload"]}}},"required":["keys","subjectTypes"],"additionalProperties":false},"enabled":{"type":"boolean"},"invalid":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["skillId","tenant","ownerUserId","accessPolicy","enabled","createdAt","updatedAt"],"additionalProperties":false}},"required":["skill"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"accessPolicy":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}},"subjectTypes":{"type":"array","items":{"type":"string","enum":["human","workload"]}}}},"enabled":{"type":"boolean"},"ownerUserId":{"type":["string","null"]}}}}}}},"delete":{"operationId":"skills.delete","summary":"Remove a skill with no published or retired version. One with history is named by the tool-call ledger: disable it instead (409). Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/skills/{id}/versions/{versionId}":{"put":{"operationId":"skills.versions.update","summary":"Edit a draft, name its reviewer or withdraw the review, self-publish it under the owner's switch (screened), or retire a published version. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"version":{"type":"object","properties":{"versionId":{"type":"string"},"skillId":{"type":"string"},"seq":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"content":{"type":"string"},"requires":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}}},"required":["tools","resources","prompts"],"additionalProperties":false},"compatibility":{"type":"object","properties":{"clients":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]}},"required":["clients","notes"],"additionalProperties":false},"digest":{"type":"string"},"state":{"type":"string","enum":["draft","published","retired"]},"reviewed":{"type":"array","items":{"type":"object","properties":{"primitive":{"type":"string","enum":["tool","resource","prompt"]},"name":{"type":"string"},"readOnly":{"type":"boolean"},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"custody":{"type":"string","enum":["service","connection"]}},"required":["primitive","name","readOnly","requiredScopes","custody"],"additionalProperties":false}},"publishedAt":{"type":["string","null"]},"publishedByEmail":{"type":["string","null"]},"invalid":{"type":"boolean"},"createdByUserId":{"type":["string","null"]},"createdAt":{"type":"string"},"lastEditedByUserId":{"type":["string","null"]},"updatedAt":{"type":"string"},"reviewRequestedByUserId":{"type":["string","null"]},"reviewRequestedAt":{"type":["string","null"]},"reviewDigest":{"type":["string","null"]},"screening":{"anyOf":[{"type":"object","properties":{"screenedAt":{"type":"string"},"action":{"type":"string","enum":["allow","flag","block"]},"screened":{"type":"boolean"},"routes":{"type":"array","items":{"type":"string"}},"guards":{"type":"array","items":{"type":"string"}},"coveredBy":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"category":{"type":"string"}},"required":["guard","category"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"action":{"type":"string"},"category":{"type":["string","null"]},"ruleId":{"type":["string","null"]},"ruleType":{"type":["string","null"]},"routes":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["console","gateway"]}},"required":["guard","action","category","ruleId","ruleType","routes","source"],"additionalProperties":false}},"gateway":{"anyOf":[{"type":"object","properties":{"asked":{"type":"boolean","const":false}},"required":["asked"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":true}},"required":["asked","answered"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["asked","answered","error"],"additionalProperties":false}]}},"required":["screenedAt","action","screened","routes","guards","coveredBy","unavailable","findings","gateway"],"additionalProperties":false},{"type":"null"}]},"publishedByUserId":{"type":["string","null"]},"retiredByUserId":{"type":["string","null"]},"retiredAt":{"type":["string","null"]},"reviewerUserId":{"type":["string","null"]},"changesRequestedAt":{"type":["string","null"]},"changesRequestedContent":{"type":["string","null"]},"selfReviewed":{"type":"boolean"},"contributorUserIds":{"type":"array","items":{"type":"string"}}},"required":["versionId","skillId","seq","title","description","content","requires","compatibility","digest","state","reviewed","publishedAt","publishedByEmail","createdByUserId","createdAt","lastEditedByUserId","updatedAt","reviewRequestedByUserId","reviewRequestedAt","reviewDigest","screening","publishedByUserId","retiredByUserId","retiredAt","reviewerUserId","changesRequestedAt","changesRequestedContent","selfReviewed","contributorUserIds"],"additionalProperties":false}},"required":["version"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"state":{"type":"string","enum":["published","retired"]},"mode":{"type":"string"},"expectedDigest":{"type":"string"},"review":{"type":"boolean"},"reviewerUserId":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"content":{"type":"string"},"requires":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}}}},"compatibility":{"type":"object","properties":{"clients":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]}}}}}}}}},"delete":{"operationId":"skills.versions.delete","summary":"Delete a draft and its comments. A published or retired version is history and stays. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"}}]}},"/skills/{id}/versions/{versionId}/review":{"post":{"operationId":"skills.versions.review","summary":"The named reviewer approves a draft (which publishes it, screened) or sends it back with comments. Only THE reviewer, never a contributor. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"version":{"type":"object","properties":{"versionId":{"type":"string"},"skillId":{"type":"string"},"seq":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"content":{"type":"string"},"requires":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}}},"required":["tools","resources","prompts"],"additionalProperties":false},"compatibility":{"type":"object","properties":{"clients":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]}},"required":["clients","notes"],"additionalProperties":false},"digest":{"type":"string"},"state":{"type":"string","enum":["draft","published","retired"]},"reviewed":{"type":"array","items":{"type":"object","properties":{"primitive":{"type":"string","enum":["tool","resource","prompt"]},"name":{"type":"string"},"readOnly":{"type":"boolean"},"requiredScopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"custody":{"type":"string","enum":["service","connection"]}},"required":["primitive","name","readOnly","requiredScopes","custody"],"additionalProperties":false}},"publishedAt":{"type":["string","null"]},"publishedByEmail":{"type":["string","null"]},"invalid":{"type":"boolean"},"createdByUserId":{"type":["string","null"]},"createdAt":{"type":"string"},"lastEditedByUserId":{"type":["string","null"]},"updatedAt":{"type":"string"},"reviewRequestedByUserId":{"type":["string","null"]},"reviewRequestedAt":{"type":["string","null"]},"reviewDigest":{"type":["string","null"]},"screening":{"anyOf":[{"type":"object","properties":{"screenedAt":{"type":"string"},"action":{"type":"string","enum":["allow","flag","block"]},"screened":{"type":"boolean"},"routes":{"type":"array","items":{"type":"string"}},"guards":{"type":"array","items":{"type":"string"}},"coveredBy":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"category":{"type":"string"}},"required":["guard","category"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"action":{"type":"string"},"category":{"type":["string","null"]},"ruleId":{"type":["string","null"]},"ruleType":{"type":["string","null"]},"routes":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["console","gateway"]}},"required":["guard","action","category","ruleId","ruleType","routes","source"],"additionalProperties":false}},"gateway":{"anyOf":[{"type":"object","properties":{"asked":{"type":"boolean","const":false}},"required":["asked"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":true}},"required":["asked","answered"],"additionalProperties":false},{"type":"object","properties":{"asked":{"type":"boolean","const":true},"answered":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["asked","answered","error"],"additionalProperties":false}]}},"required":["screenedAt","action","screened","routes","guards","coveredBy","unavailable","findings","gateway"],"additionalProperties":false},{"type":"null"}]},"publishedByUserId":{"type":["string","null"]},"retiredByUserId":{"type":["string","null"]},"retiredAt":{"type":["string","null"]},"reviewerUserId":{"type":["string","null"]},"changesRequestedAt":{"type":["string","null"]},"changesRequestedContent":{"type":["string","null"]},"selfReviewed":{"type":"boolean"},"contributorUserIds":{"type":"array","items":{"type":"string"}}},"required":["versionId","skillId","seq","title","description","content","requires","compatibility","digest","state","reviewed","publishedAt","publishedByEmail","createdByUserId","createdAt","lastEditedByUserId","updatedAt","reviewRequestedByUserId","reviewRequestedAt","reviewDigest","screening","publishedByUserId","retiredByUserId","retiredAt","reviewerUserId","changesRequestedAt","changesRequestedContent","selfReviewed","contributorUserIds"],"additionalProperties":false},"comments":{"type":"array","items":{"type":"object","properties":{"commentId":{"type":"string"},"versionId":{"type":"string"},"digest":{"type":"string"},"line":{"type":["number","null"]},"quote":{"type":["string","null"]},"body":{"type":"string"},"authorUserId":{"type":["string","null"]},"authorEmail":{"type":["string","null"]},"state":{"type":"string","enum":["open","resolved"]},"reply":{"type":["string","null"]},"resolvedByUserId":{"type":["string","null"]},"resolvedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["commentId","versionId","digest","line","quote","body","authorUserId","authorEmail","state","reply","resolvedByUserId","resolvedAt","createdAt"],"additionalProperties":false}}},"required":["version"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"action":{"type":"string","enum":["approve","requestChanges"]},"expectedDigest":{"type":"string"},"comments":{"type":"array","items":{"type":"object","properties":{"line":{"type":["number","null"]},"body":{"type":"string"}},"required":["body"]}}},"required":["action"]}}}}}},"/skills/{id}/versions/{versionId}/comments/{commentId}":{"put":{"operationId":"skills.comments.resolve","summary":"Resolve a review comment on a draft, with an optional reply. Only the draft's authors or the comment's writer. Resolving is never approval. Human session only.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"comment":{"type":"object","properties":{"commentId":{"type":"string"},"versionId":{"type":"string"},"digest":{"type":"string"},"line":{"type":["number","null"]},"quote":{"type":["string","null"]},"body":{"type":"string"},"authorUserId":{"type":["string","null"]},"authorEmail":{"type":["string","null"]},"state":{"type":"string","enum":["open","resolved"]},"reply":{"type":["string","null"]},"resolvedByUserId":{"type":["string","null"]},"resolvedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["commentId","versionId","digest","line","quote","body","authorUserId","authorEmail","state","reply","resolvedByUserId","resolvedAt","createdAt"],"additionalProperties":false}},"required":["comment"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reply":{"type":["string","null"]}}}}}}}},"/alerts/channels":{"get":{"operationId":"alerts.channels.list","summary":"List the budget alert channels. A webhook target is masked; the URL is a secret.","security":[{"bearerAuth":[]}],"x-required-role":"owner","x-required-scope":"alerts:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"channels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["webhook","email"]},"target":{"type":"string"},"enabled":{"type":"boolean"},"minLevel":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","type","target","enabled","minLevel","createdAt"],"additionalProperties":false}},"emailConfigured":{"type":"boolean"}},"required":["channels","emailConfigured"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"post":{"operationId":"alerts.channels.create","summary":"Add a budget alert channel: a webhook or email recipients, at the 80% or 100% band.","security":[{"bearerAuth":[]}],"x-required-role":"owner","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"channel":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["webhook","email"]},"target":{"type":"string"},"enabled":{"type":"boolean"},"minLevel":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","type","target","enabled","minLevel","createdAt"],"additionalProperties":false}},"required":["channel"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"type":"string","enum":["webhook","email"]},"target":{"type":"string","minLength":1},"minLevel":{"default":80,"anyOf":[{"type":"number","const":80},{"type":"number","const":100}]},"enabled":{"default":true,"type":"boolean"}},"required":["type","target"]}}}}}},"/alerts/channels/{id}":{"patch":{"operationId":"alerts.channels.update","summary":"Enable, disable, re-level or retarget one alert channel. 404 for an unknown channel.","security":[{"bearerAuth":[]}],"x-required-role":"owner","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"channel":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["webhook","email"]},"target":{"type":"string"},"enabled":{"type":"boolean"},"minLevel":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","type","target","enabled","minLevel","createdAt"],"additionalProperties":false}},"required":["channel"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"enabled":{"type":"boolean"},"minLevel":{"anyOf":[{"type":"number","const":80},{"type":"number","const":100}]},"target":{"type":"string","minLength":1}}}}}}},"delete":{"operationId":"alerts.channels.delete","summary":"Delete one alert channel. Deleting an absent channel succeeds.","security":[{"bearerAuth":[]}],"x-required-role":"owner","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"x-retry-safe":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/alerts/check":{"post":{"operationId":"alerts.check","summary":"Evaluate every budget against the alert bands now, and deliver each new crossing once. Safe to repeat.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"alerts:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"channels":{"type":"number"},"subjects":{"type":"number"},"fired":{"type":"number"},"deliveries":{"type":"number"},"failures":{"type":"number"}},"required":["channels","subjects","fired","deliveries","failures"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-retry-safe":true}},"/reports/{id}":{"get":{"operationId":"reports.read","summary":"Read one report's definition: a built-in id, or a saved report's uuid the caller may see. The question, never the figures.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"report":{"type":"object","properties":{"kind":{"type":"string","enum":["built_in","saved"]},"id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"spec":{"type":"object","properties":{"source":{"type":"string","enum":["requests","tool_calls","agent_metrics","outcomes"]},"dimensions":{"maxItems":2,"type":"array","items":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]}},"measures":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"string","enum":["requests","input_tokens","output_tokens","total_tokens","cached_tokens","cost_usd","unpriced_requests","users","sessions","active_hours","latency_avg_ms","latency_p95_ms","ttft_avg_ms","cost_share","request_share","cost_per_user","requests_per_user","cost_per_1k_requests","tokens_per_request","cost_per_1m_tokens","cost_per_1k_sessions","cost_per_active_hour","cache_hit_rate","cost_decomposition","calls","ok","failed","unknown","denied","pending","unpriced_calls","cost_per_ok_call","operations","estimated_cost_usd","merged_prs","reverted_prs","revert_rate","reviews","joined_prs","cost_per_merged_pr"]}},"filters":{"type":"object","propertyNames":{"type":"string","enum":["client","model","route","subject","key","channel","tag","session","server","tool","repository","day","week","month"]},"additionalProperties":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"range":{"anyOf":[{"type":"string","enum":["7d","30d","mtd","last_month"]},{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"],"additionalProperties":false}]},"compare":{"type":"string","enum":["none","previous_period"]},"view":{"type":"string","enum":["table","bar","line","stacked","waterfall"]}},"required":["source","dimensions","measures","filters","range","compare","view"],"additionalProperties":false},"ownerEmail":{"type":["string","null"]},"visibility":{"type":"string","enum":["private","role:viewer","role:admin","role:owner"]},"pinned":{"type":"boolean"},"editable":{"type":"boolean"},"updatedAt":{"type":["string","null"]}},"required":["kind","id","title","description","spec","ownerEmail","visibility","pinned","editable","updatedAt"],"additionalProperties":false}},"required":["report"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"operationId":"reports.delete","summary":"Delete a saved report the caller owns. Another person's report, or none, is 404.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"reports:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/config/routes/{name}/utterances":{"get":{"operationId":"config.utterances.read","summary":"Read one route's classifier examples. 404 for an unknown route.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"config:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"utterances":{"type":"array","items":{"type":"string"}}},"required":["utterances"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}]},"put":{"operationId":"config.utterances.set","summary":"Replace one route's classifier examples. The gateway rebuilds its embedding index. 404 for an unknown route.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"config:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"utterances":{"type":"array","items":{"type":"string"}}},"required":["ok","utterances"],"additionalProperties":false}}},"headers":{"ETag":{"description":"Current `config_version`, quoted — pass it back as `If-Match` on the next config write.","schema":{"type":"string"}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"412":{"description":"Precondition failed — the config changed since the declared version; nothing was applied. Body carries `currentVersion`."},"428":{"description":"Precondition required — `If-Match` was not supplied."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-concurrency":"config-version","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-Match","in":"header","required":true,"description":"The `config_version` this edit is based on (the `ETag` from a prior read), quoted — e.g. `\"7\"`. The write is applied only if that is still the stored version. `*` applies unconditionally, overwriting any concurrent change.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"utterances":{"type":"array","items":{"type":"string"}}},"required":["utterances"]}}}}}},"/capture/plaintext/purge":{"post":{"operationId":"capture.plaintext.purge","summary":"Delete the captured bodies stored before encryption. Their request metadata stays. Irreversible; `dryRun` counts only.","security":[{"bearerAuth":[]}],"x-required-role":"owner","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"dryRun":{"type":"boolean"},"rows":{"type":"number"},"deleted":{"type":"number"},"remaining":{"type":"number"}},"required":["dryRun","rows","deleted","remaining"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"dryRun":{"default":false,"type":"boolean"}}}}}}}},"/guardrails":{"get":{"operationId":"guardrails.read","summary":"Read the screening rules: the master switch, every rule with its scope and mode, soft-deny and stream screening.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"guardrails:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"guardrails":{"type":"object","properties":{"enabled":{"type":"boolean"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"stages":{"type":"array","items":{"type":"string","enum":["request","response","tool_call","tool_result"]}},"mode":{"type":"string","enum":["off","flag","block","escalate"]},"routes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"keys":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"tags":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"tools":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"routeModes":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","enum":["off","flag","block","escalate"]}},{"type":"null"}]},"keyModes":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","enum":["off","flag","block","escalate"]}},{"type":"null"}]},"after":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"patterns":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"name":{"type":"string"},"pattern":{"type":"string"}},"required":["name","pattern"],"additionalProperties":false}]}},"entropy":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"threshold":{"type":"number"},"minLength":{"type":"number"}},"required":["enabled","threshold","minLength"],"additionalProperties":false},{"type":"null"}]},"normalizePersian":{"type":"boolean"},"model":{"type":["string","null"]},"categories":{"type":"array","items":{"type":"string"}},"failClosed":{"type":"boolean"},"threshold":{"type":["number","null"]}},"required":["id","name","type","stages","mode"],"additionalProperties":false}},"softDeny":{"anyOf":[{"type":"object","properties":{"routes":{"type":"array","items":{"type":"string"}},"keys":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["routes","keys","message"],"additionalProperties":false},{"type":"null"}]},"streamScreening":{"anyOf":[{"type":"object","properties":{"routes":{"type":"array","items":{"type":"string"}},"keys":{"type":"array","items":{"type":"string"}},"maxBytes":{"type":["number","null"]},"maxMs":{"type":["number","null"]},"onExceeded":{"type":"string","enum":["open","closed"]}},"required":["routes","keys","maxBytes","maxMs","onExceeded"],"additionalProperties":false},{"type":"null"}]}},"required":["enabled","rules"],"additionalProperties":false}},"required":["guardrails"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"put":{"operationId":"guardrails.update","summary":"Replace the screening rules. The gateway hot-reloads them. A rule that cannot run is refused, never trimmed.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"enabled":{"type":"boolean"},"rules":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"softDeny":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"streamScreening":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["enabled","rules"]}}}}}},"/guardrails/activity":{"get":{"operationId":"guardrails.activity","summary":"Count the requests each guardrail rule acted on, per stage and action, over a window (default: 30 days).","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"guardrails:activity:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":["string","null"]},"guard":{"type":"string"},"ruleType":{"type":["string","null"]},"stage":{"type":"string"},"action":{"type":"string"},"requests":{"type":"number"},"lastSeen":{"type":"string"}},"required":["ruleId","guard","ruleType","stage","action","requests","lastSeen"],"additionalProperties":false}},"days":{"type":"number"}},"required":["rows","days"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"parameters":[{"name":"days","in":"query","required":false,"schema":{"default":30,"type":"integer","minimum":1,"maximum":365}}]}},"/guardrails/test":{"post":{"operationId":"guardrails.test","summary":"Screen a sample against the rules for a route, key and tags, storing nothing. Budgeted per caller (429); each trial is audited without its text.","security":[{"bearerAuth":[]}],"x-required-role":"admin","x-required-scope":"guardrails:test","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"action":{"type":"string"},"stage":{"type":"string","enum":["request","response"]},"route":{"type":"string"},"key":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"screensRemaining":{"type":"number"},"guards":{"type":"array","items":{"type":"string"}},"coveredBy":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"category":{"type":"string"}},"required":["guard","category"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"action":{"type":"string"},"category":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["guard","action","category","reason"],"additionalProperties":false}},"remote":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"type":{"type":"string"}},"required":["guard","type"],"additionalProperties":false}},"gateway":{"anyOf":[{"anyOf":[{"type":"object","properties":{"action":{"type":"string"},"screened":{"type":"boolean"},"guards":{"type":"array","items":{"type":"string"}},"coveredBy":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"category":{"type":"string"}},"required":["guard","category"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"action":{"type":"string"},"category":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["guard","action","category","reason"],"additionalProperties":false}},"keyId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"keyMismatch":{"type":"array","items":{"type":"object","properties":{"guard":{"type":"string"},"previewed":{"type":"string","enum":["off","flag","block","escalate"]},"actual":{"type":"string","enum":["off","flag","block","escalate"]}},"required":["guard","previewed","actual"],"additionalProperties":false}}},"required":["action","screened","guards","coveredBy","unavailable","findings","keyId","tags","keyMismatch"],"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},{"type":"null"}]},"softDeny":{"type":"boolean"}},"required":["action","stage","route","key","tags","screensRemaining","guards","coveredBy","unavailable","findings","remote","gateway","softDeny"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string"},"stage":{"default":"request","type":"string","enum":["request","response"]},"route":{"type":"string","minLength":1},"key":{"default":"","type":"string"},"tags":{"default":[],"type":"array","items":{"type":"string"}}},"required":["text","route"]}}}}}},"/retention":{"get":{"operationId":"retention.read","summary":"Read the retention policy (days kept per table; 0 = forever) and the last purge pass.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"retention:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"retention":{"type":"object","properties":{"enabled":{"type":"boolean"},"manualEnabled":{"type":"boolean"},"schedule":{"type":"object","properties":{"enabled":{"type":"boolean"},"intervalMinutes":{"type":"number"},"pausedUntil":{"type":["string","null"]}},"required":["enabled","intervalMinutes","pausedUntil"],"additionalProperties":false},"rules":{"type":"object","properties":{"request_payloads":{"type":"object","properties":{"enabled":{"type":"boolean"},"days":{"type":"number"}},"required":["enabled","days"],"additionalProperties":false},"request_logs":{"type":"object","properties":{"enabled":{"type":"boolean"},"days":{"type":"number"}},"required":["enabled","days"],"additionalProperties":false},"otel_metric_points":{"type":"object","properties":{"enabled":{"type":"boolean"},"days":{"type":"number"}},"required":["enabled","days"],"additionalProperties":false},"hook_events":{"type":"object","properties":{"enabled":{"type":"boolean"},"days":{"type":"number"}},"required":["enabled","days"],"additionalProperties":false},"tool_calls":{"type":"object","properties":{"enabled":{"type":"boolean"},"days":{"type":"number"}},"required":["enabled","days"],"additionalProperties":false},"idempotency_keys":{"type":"object","properties":{"enabled":{"type":"boolean"},"days":{"type":"number"}},"required":["enabled","days"],"additionalProperties":false},"rate_limit_buckets":{"type":"object","properties":{"enabled":{"type":"boolean"},"days":{"type":"number"}},"required":["enabled","days"],"additionalProperties":false},"copilot_actions":{"type":"object","properties":{"enabled":{"type":"boolean"},"days":{"type":"number"}},"required":["enabled","days"],"additionalProperties":false}},"required":["request_payloads","request_logs","otel_metric_points","hook_events","tool_calls","idempotency_keys","rate_limit_buckets","copilot_actions"],"additionalProperties":false},"batchSize":{"type":"number"}},"required":["enabled","manualEnabled","schedule","rules","batchSize"],"additionalProperties":false},"lastRun":{"anyOf":[{"type":"object","properties":{"job":{"type":"string"},"leaseUntil":{"type":["string","null"]},"lastStartedAt":{"type":["string","null"]},"lastFinishedAt":{"type":["string","null"]},"lastStatus":{"anyOf":[{"type":"string","enum":["ok","partial","failed"]},{"type":"null"}]},"lastDetail":{"type":["string","null"]},"lastCounts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}}},"required":["job","leaseUntil","lastStartedAt","lastFinishedAt","lastStatus","lastDetail","lastCounts"],"additionalProperties":false},{"type":"null"}]}},"required":["retention","lastRun"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"put":{"operationId":"retention.update","summary":"Replace the retention policy. Owner only; audited before and after.","security":[{"bearerAuth":[]}],"x-required-role":"owner","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"enabled":{"type":"boolean"},"manualEnabled":{"type":"boolean"},"schedule":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"rules":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"batchSize":{"type":"number"}},"required":["enabled","manualEnabled","schedule","rules"]}}}}}},"/retention/run":{"post":{"operationId":"retention.run","summary":"Run a purge pass under the current policy now, or count one (`dryRun`). Irreversible. 409 when the policy blocks a manual run.","security":[{"bearerAuth":[]}],"x-required-role":"admin","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"dryRun":{"type":"boolean"},"blocked":{"type":["string","null"]},"status":{"type":"string","enum":["ok","partial","failed"]},"targets":{"type":"array","items":{"type":"object","properties":{"target":{"type":"string"},"rows":{"type":"number"},"skipped":{"type":["string","null"]},"error":{"type":["string","null"]},"truncated":{"type":"boolean"}},"required":["target","rows","skipped","error","truncated"],"additionalProperties":false}},"rows":{"type":"number"}},"required":["dryRun","blocked","status","targets","rows"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"dryRun":{"default":false,"type":"boolean"}}}}}}}},"/subscription-lane":{"get":{"operationId":"subscription-lane.read","summary":"Read whether a claude.ai subscription credential may cross the gateway, and what each mode does.","security":[{"bearerAuth":[]}],"x-required-role":"viewer","x-required-scope":"subscription_lane:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionLane":{"type":"object","properties":{"mode":{"type":"string","enum":["off","allow","require_key"]}},"required":["mode"],"additionalProperties":false},"reason":{"type":"string"},"modes":{"type":"array","items":{"type":"object","properties":{"mode":{"type":"string","enum":["off","allow","require_key"]},"reason":{"type":"string"}},"required":["mode","reason"],"additionalProperties":false}}},"required":["subscriptionLane","reason","modes"],"additionalProperties":false}}}},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role or scope insufficient."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}}},"put":{"operationId":"subscription-lane.update","summary":"Set the subscription lane: off, allow, or require_key. Owner only; the gateway applies it on its next config poll.","security":[{"bearerAuth":[]}],"x-required-role":"owner","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"subscriptionLane":{"type":"object","properties":{"mode":{"type":"string","enum":["off","allow","require_key"]}},"required":["mode"],"additionalProperties":false}},"required":["ok","subscriptionLane"],"additionalProperties":false}}}},"400":{"description":"Invalid request — schema violation or a rejected value."},"401":{"description":"Unauthenticated — missing or invalid credentials."},"403":{"description":"Forbidden — role insufficient, or the caller is an automation token: only a person may call this."},"429":{"description":"Rate limit exceeded for this token. Body carries `retryAfterSeconds`; the `Retry-After` header carries the same value."}},"x-human-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"mode":{"type":"string","enum":["off","allow","require_key"]}},"required":["mode"]}}}}}}}}