vh/ratatoskr
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
14bbc2b48edef1bef19d4d3d862d67e6ffa7dc1f
ratatoskr/docs/conversation-api-openapi.json
T
vh 14bbc2b48e docs(canonical): add client-spec-v2 pin + sync worldtree conversation-api canonicals 
Operator decision A (client-spec tracking): add a first-class pin for
docs/conversation-api-client-spec-v2.md (v2.1, sha 1ff1d73a — the
client-facing spec our #371 parity pass shaped), vendored as a consumer
copy, tolerate_drift=true (prose reference; OpenAPI+SSE stay the gates).

canonical_sync is whole-manifest (no per-pin scope), so it also brought
two independently-drifted pins current:
- OpenAPI hard-gate 36148179 (2.3.0) -> 1c801547. Additive-only within
  the FROZEN v1 wire (Worldtree #326) — no code/SDK breakage; the SDK
  targets 2.3.0 and still works against the newer additive surface.
- conversation-api-spec.md (full prose) -> f6e964ec (v1.3+).

canonical_drift now exits 0. FOLLOW-UP (non-urgent): the OpenAPI moved,
so a coverage-map re-audit against the new surface would surface any new
in-scope I/O points worth consuming (ratatoskr v1 = full WT I/O coverage).
Release-only cadence: no tag.
2026-08-01 16:58:39 -07:00

8196 lines
253 KiB
JSON
Raw Blame History

{
"components": {
"schemas": {
"AuthoredTurnResponse": {
"description": "#347 — the authored-write ack. Provenance is audit-only and NEVER on this\npayload (INV-347-7). ``content_chars`` is the CHARACTER count (may differ from\nthe UTF-8 byte length the request is bounded against — INV-347-12).",
"properties": {
"author": {
"title": "Author",
"type": "string"
},
"content_chars": {
"title": "Content Chars",
"type": "integer"
},
"injected_at": {
"title": "Injected At",
"type": "string"
},
"phase": {
"title": "Phase",
"type": "string"
},
"seq": {
"title": "Seq",
"type": "integer"
},
"session_id": {
"title": "Session Id",
"type": "string"
},
"turn_id": {
"title": "Turn Id",
"type": "integer"
}
},
"required": [
"turn_id",
"session_id",
"author",
"phase",
"seq",
"injected_at",
"content_chars"
],
"title": "AuthoredTurnResponse",
"type": "object"
},
"BifrostBindingRequest": {
"additionalProperties": false,
"description": "Bifrost binding parameters for session-create (issue #160).",
"properties": {
"endpoint_url": {
"title": "Endpoint Url",
"type": "string"
},
"scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Scope"
}
},
"required": [
"endpoint_url"
],
"title": "BifrostBindingRequest",
"type": "object"
},
"BifrostEndpointOverride": {
"description": "Per-message Bifrost endpoint override (issue #166, bifrost v0.2 spec § 9).\n\nEnables stateless one-off consumer-MCP calls without binding a Bifrost\nendpoint to the whole session. A new BifrostClient is instantiated per\nmessage; state never bleeds into the session-bound client.",
"properties": {
"consumer_id": {
"description": "Heimdall user_id whose registered key + algorithm to use",
"minLength": 1,
"title": "Consumer Id",
"type": "string"
},
"endpoint_url": {
"description": "https URL of the override target's MCP server",
"title": "Endpoint Url",
"type": "string"
},
"scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Scope"
}
},
"required": [
"endpoint_url",
"consumer_id"
],
"title": "BifrostEndpointOverride",
"type": "object"
},
"BifrostInspectionResponse": {
"additionalProperties": false,
"properties": {
"capabilities_granted": {
"items": {
"type": "string"
},
"title": "Capabilities Granted",
"type": "array"
},
"connected": {
"title": "Connected",
"type": "boolean"
},
"consumer_id": {
"title": "Consumer Id",
"type": "string"
},
"endpoint_url": {
"title": "Endpoint Url",
"type": "string"
},
"tools": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Tools",
"type": "array"
}
},
"required": [
"endpoint_url",
"consumer_id",
"connected",
"capabilities_granted",
"tools"
],
"title": "BifrostInspectionResponse",
"type": "object"
},
"Body_create_upload_uploads_post": {
"properties": {
"file": {
"contentMediaType": "application/octet-stream",
"title": "File",
"type": "string"
}
},
"required": [
"file"
],
"title": "Body_create_upload_uploads_post",
"type": "object"
},
"BulkIssueRequest": {
"additionalProperties": false,
"properties": {
"issuances": {
"items": {
"$ref": "#/components/schemas/IssueKeyRequest"
},
"title": "Issuances",
"type": "array"
}
},
"required": [
"issuances"
],
"title": "BulkIssueRequest",
"type": "object"
},
"BulkRevokeRequest": {
"additionalProperties": false,
"properties": {
"key_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Key Ids"
},
"user_prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Prefix"
}
},
"title": "BulkRevokeRequest",
"type": "object"
},
"BulkRotateRequest": {
"additionalProperties": false,
"properties": {
"grace_seconds": {
"anyOf": [
{
"maximum": 86400.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Grace Seconds"
},
"key_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Key Ids"
},
"user_prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Prefix"
}
},
"title": "BulkRotateRequest",
"type": "object"
},
"ConsumerAgentCreateRequest": {
"additionalProperties": false,
"description": "POST /agents/define payload (#181).\n\nLayer fields (``persona`` / ``motivational`` / ``valence`` /\n``memory``) are schema-reserved with ``null`` default. Non-null\nvalues return 422 ``layer_deferred`` so consumers can code against\nthe final shape; Phase 2.1+ flips activations on without a\nschema-breaking change.",
"properties": {
"agent_name": {
"title": "Agent Name",
"type": "string"
},
"memory": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Memory"
},
"motivational": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Motivational"
},
"persona": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Persona"
},
"role": {
"title": "Role",
"type": "string"
},
"system_prompt": {
"title": "System Prompt",
"type": "string"
},
"valence": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Valence"
}
},
"required": [
"agent_name",
"system_prompt",
"role"
],
"title": "ConsumerAgentCreateRequest",
"type": "object"
},
"CreateCharacterRequest": {
"description": "Issue #153: POST /characters body — character + optional initial state.",
"properties": {
"character": {
"additionalProperties": true,
"title": "Character",
"type": "object"
},
"state": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "State"
}
},
"required": [
"character"
],
"title": "CreateCharacterRequest",
"type": "object"
},
"CreateSessionRequest": {
"additionalProperties": false,
"properties": {
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent Id"
},
"bifrost": {
"anyOf": [
{
"$ref": "#/components/schemas/BifrostBindingRequest"
},
{
"type": "null"
}
]
},
"character_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Character Id"
},
"config": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Config"
},
"end_user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "End User Id"
},
"persona_seed": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Persona Seed"
},
"record_tool_intermediates": {
"default": false,
"title": "Record Tool Intermediates",
"type": "boolean"
}
},
"title": "CreateSessionRequest",
"type": "object"
},
"ErrorCode": {
"enum": [
"auth_missing",
"auth_invalid",
"auth_user_disabled",
"auth_key_disabled",
"auth_key_superseded",
"auth_scope_denied",
"user_suspended",
"user_not_found",
"invalid_tier",
"session_not_found",
"session_not_bifrost_bound",
"session_retired",
"generation_active",
"agent_not_available",
"turn_not_found",
"turn_finished",
"key_not_found",
"key_revoked",
"key_already_superseded",
"last_event_id_invalid",
"buffer_expired",
"cursor_invalid",
"rate_limited",
"validation_failed",
"content_too_long",
"not_ready",
"method_not_allowed",
"malformed_request",
"search_query_invalid",
"upload_too_large",
"quota_exceeded",
"mime_type_disallowed",
"upload_expired",
"upload_not_found",
"agent_lacks_upload_support",
"character_not_found",
"ttl_too_large",
"state_schema_outdated",
"llm_output_truncated",
"context_overflow",
"model_unavailable",
"provider_timeout",
"llm_output_invalid",
"bifrost_handshake_failed",
"bifrost_consumer_not_found",
"tier_mismatch",
"invalid_judgment_kind",
"bin_unsupported_v1",
"max_tokens_too_low_for_gap_list",
"selene_unreachable",
"agent_name_invalid",
"agent_name_taken",
"agent_quota_exceeded",
"system_prompt_too_large",
"model_not_available",
"layer_deferred",
"field_not_mutable",
"tier3_user_id_unsupported",
"end_user_id_required",
"end_user_id_reserved",
"auth_revoked",
"persona_ocean_required",
"persona_ocean_out_of_range",
"persona_notes_too_large",
"persona_seed_invalid",
"memory_stm_capacity_out_of_range",
"memory_stm_token_budget_out_of_range",
"embedder_version_mismatch",
"embed_batch_too_large",
"persona_layer_inactive",
"memory_context_embedding_dim_mismatch",
"motivational_id_collision",
"motivational_goal_invalid_type",
"motivational_salience_out_of_range",
"motivational_description_too_short",
"motivational_missing_required_field",
"persona_not_configured",
"bulk_prefix_too_short",
"bulk_batch_too_large",
"internal_error"
],
"title": "ErrorCode",
"type": "string"
},
"ErrorDetail": {
"description": "The `detail` object every Conversation-API error response carries.",
"properties": {
"error_code": {
"$ref": "#/components/schemas/ErrorCode",
"description": "Stable snake_case error identifier (errors.ErrorCode)."
},
"errors": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Per-field validation errors; present only on validation_failed (422).",
"title": "Errors"
},
"message": {
"description": "Human-readable error message.",
"title": "Message",
"type": "string"
}
},
"required": [
"error_code",
"message"
],
"title": "ErrorDetail",
"type": "object"
},
"ErrorResponse": {
"description": "The unified error body for every 4xx/5xx Conversation-API response.",
"properties": {
"detail": {
"$ref": "#/components/schemas/ErrorDetail"
}
},
"required": [
"detail"
],
"title": "ErrorResponse",
"type": "object"
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"title": "Detail",
"type": "array"
}
},
"title": "HTTPValidationError",
"type": "object"
},
"IssueKeyRequest": {
"additionalProperties": false,
"properties": {
"label": {
"title": "Label",
"type": "string"
},
"tier": {
"anyOf": [
{
"enum": [
"user",
"free",
"pro",
"admin",
"readonly-admin"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Tier"
},
"user_id": {
"title": "User Id",
"type": "string"
}
},
"required": [
"user_id",
"label"
],
"title": "IssueKeyRequest",
"type": "object"
},
"JudgmentRequest": {
"description": "Request body for POST /judgments.",
"properties": {
"bible": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bible"
},
"composite_token_count": {
"description": "Caller-estimated composite token count",
"minimum": 0.0,
"title": "Composite Token Count",
"type": "integer"
},
"has_bible": {
"default": false,
"title": "Has Bible",
"type": "boolean"
},
"instruction": {
"default": "",
"title": "Instruction",
"type": "string"
},
"judgment_kind": {
"description": "pairwise | binary | likert | scalar | gap_list",
"title": "Judgment Kind",
"type": "string"
},
"max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Tokens"
},
"response_a": {
"default": "",
"title": "Response A",
"type": "string"
},
"response_b": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Response B"
},
"rubric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rubric"
}
},
"required": [
"judgment_kind",
"composite_token_count"
],
"title": "JudgmentRequest",
"type": "object"
},
"PersonaLifecycleRequest": {
"description": "Body for POST /admin/persona/{archive,erase} (#215).\n\n``agent_id`` truthiness selects the target: a non-empty agent_id operates on\nthe single ``(agent_id, end_user_id)`` partition; absent / null / empty-string\noperates on all agents for the user (INV-215-2 / INV-MODEL-2).",
"properties": {
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent Id"
},
"end_user_id": {
"minLength": 1,
"title": "End User Id",
"type": "string"
}
},
"required": [
"end_user_id"
],
"title": "PersonaLifecycleRequest",
"type": "object"
},
"RotateKeyRequest": {
"properties": {
"grace_seconds": {
"anyOf": [
{
"maximum": 86400.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Grace window in seconds. None uses the server default (300). 0 = hard cut; 86400 = 24h max.",
"title": "Grace Seconds"
}
},
"title": "RotateKeyRequest",
"type": "object"
},
"SendMessageRequest": {
"additionalProperties": false,
"properties": {
"bifrost": {
"anyOf": [
{
"$ref": "#/components/schemas/BifrostEndpointOverride"
},
{
"type": "null"
}
]
},
"content": {
"title": "Content",
"type": "string"
},
"memory_context": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Memory Context"
},
"role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Role"
},
"sender_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sender Id"
},
"upload_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Upload Ids"
}
},
"required": [
"content"
],
"title": "SendMessageRequest",
"type": "object"
},
"SessionToolsResponse": {
"additionalProperties": false,
"properties": {
"agent_id": {
"title": "Agent Id",
"type": "string"
},
"bifrost_tools": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Bifrost Tools",
"type": "array"
},
"builtin_tools": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Builtin Tools",
"type": "array"
}
},
"required": [
"agent_id",
"builtin_tools",
"bifrost_tools"
],
"title": "SessionToolsResponse",
"type": "object"
},
"UpdateSessionRequest": {
"additionalProperties": false,
"properties": {
"archived": {
"default": false,
"title": "Archived",
"type": "boolean"
},
"metadata": {
"additionalProperties": true,
"default": {},
"title": "Metadata",
"type": "object"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"tags": {
"default": [],
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
}
},
"title": "UpdateSessionRequest",
"type": "object"
},
"UserTierChangeRequest": {
"description": "Issue #174: body for POST /admin/users/{user_id}/tier.",
"properties": {
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reason"
},
"tier": {
"title": "Tier",
"type": "string"
}
},
"required": [
"tier"
],
"title": "UserTierChangeRequest",
"type": "object"
},
"ValidationError": {
"properties": {
"ctx": {
"title": "Context",
"type": "object"
},
"input": {
"title": "Input"
},
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"title": "Location",
"type": "array"
},
"msg": {
"title": "Message",
"type": "string"
},
"type": {
"title": "Error Type",
"type": "string"
}
},
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError",
"type": "object"
}
},
"securitySchemes": {
"HTTPBearer": {
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"description": "Multi-turn conversation interface for Worldtree agents.",
"title": "Worldtree Conversation API",
"version": "2.4.0"
},
"openapi": "3.1.0",
"paths": {
"/admin/events": {
"get": {
"description": "SSE stream broadcasting all conv-api lifecycle events to admin consumers.\n\nRequires admin.events.read scope. Last-Event-ID header resumes from\na buffered offset; out-of-buffer reconnects receive system.replay_gap.",
"operationId": "admin_events_admin_events_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Admin Events"
}
},
"/admin/keys": {
"get": {
"description": "List all API keys (active + revoked), sorted by created_at desc.\n\nNever includes the cleartext key value.",
"operationId": "list_keys_admin_keys_get",
"parameters": [
{
"in": "query",
"name": "user_prefix",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Prefix"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Response List Keys Admin Keys Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "List Keys"
},
"post": {
"description": "Issue a new API key for a user.\n\nReturns the cleartext key exactly once — it is NEVER re-derivable.\nCaller is responsible for securing the response body; configure\nreverse proxy log redaction for this endpoint.",
"operationId": "issue_key_admin_keys_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueKeyRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Issue Key Admin Keys Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Issue Key"
}
},
"/admin/keys/bulk": {
"delete": {
"operationId": "bulk_revoke_keys_admin_keys_bulk_delete",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkRevokeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Bulk Revoke Keys Admin Keys Bulk Delete",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Bulk Revoke Keys"
},
"post": {
"operationId": "bulk_issue_keys_admin_keys_bulk_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkIssueRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Bulk Issue Keys Admin Keys Bulk Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Bulk Issue Keys"
}
},
"/admin/keys/bulk/rotate": {
"post": {
"operationId": "bulk_rotate_keys_admin_keys_bulk_rotate_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkRotateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Bulk Rotate Keys Admin Keys Bulk Rotate Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Bulk Rotate Keys"
}
},
"/admin/keys/{key_id}": {
"delete": {
"description": "Revoke an API key by key_id.\n\nIdempotent: revoking an already-revoked key returns 200 with outcome=no_op.\nReturns 404 if key_id never existed.",
"operationId": "revoke_key_admin_keys__key_id__delete",
"parameters": [
{
"in": "path",
"name": "key_id",
"required": true,
"schema": {
"title": "Key Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Revoke Key Admin Keys Key Id Delete",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Revoke Key"
}
},
"/admin/keys/{key_id}/rotate": {
"post": {
"description": "Atomically rotate an API key, issuing a new key while the old one\nremains valid for a configurable grace window.\n\nReturns the cleartext of the new key exactly once — configure reverse-proxy\nlog redaction for this endpoint, same as POST /admin/keys.\n\ngrace_seconds=0 is \"compromise mode\" — the old key is immediately invalid\non its next auth attempt. In-flight SSE/WebSocket streams are NOT\nforce-disconnected (auth is enforced at request boundary only).",
"operationId": "rotate_key_admin_keys__key_id__rotate_post",
"parameters": [
{
"in": "path",
"name": "key_id",
"required": true,
"schema": {
"title": "Key Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/RotateKeyRequest"
},
{
"type": "null"
}
],
"title": "Body"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Rotate Key Admin Keys Key Id Rotate Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Rotate Key"
}
},
"/admin/persona/archive": {
"post": {
"description": "Archive persona state for one (agent, user) pair or all agents for a\nuser (#215). Forward-only: no thaw endpoint (archived->active deferred).",
"operationId": "admin_persona_archive_admin_persona_archive_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PersonaLifecycleRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Admin Persona Archive Admin Persona Archive Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Admin Persona Archive"
}
},
"/admin/persona/erase": {
"post": {
"description": "Hard-erase persona state for one (agent, user) pair or all agents for a\nuser (#215). Terminal — INV-172-12.",
"operationId": "admin_persona_erase_admin_persona_erase_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PersonaLifecycleRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Admin Persona Erase Admin Persona Erase Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Admin Persona Erase"
}
},
"/admin/sessions/{session_id}/bifrost": {
"get": {
"description": "Inspect a Bifrost-bound session's connection state + post-filter tool list.\n\nReturns 404 ``session_not_found`` for a missing session and 404\n``session_not_bifrost_bound`` for an existing session with no live\n``_bifrost_clients`` entry (covers never-bound sessions AND restored\nsessions whose live client is gone post-restart — the connection\nmetadata fields cannot be reconstructed from persisted state alone).\n\nGraceful-on-stale: when a live client is registered but its TCP\nconnection has died, ``connected: false`` with the cached\npost-filter tool list is returned. No re-handshake is attempted —\nthis endpoint is read-only.",
"operationId": "admin_session_bifrost_admin_sessions__session_id__bifrost_get",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BifrostInspectionResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Admin Session Bifrost"
}
},
"/admin/sessions/{session_id}/retire": {
"post": {
"operationId": "admin_session_retire_admin_sessions__session_id__retire_post",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
}
],
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Admin Session Retire Admin Sessions Session Id Retire Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Admin Session Retire"
}
},
"/admin/sessions/{session_id}/tools": {
"get": {
"description": "Inspect the full post-merge tool list the agent sees at turn-fire time.\n\n``bifrost_tools`` mirrors the actual turn-time merge predicate at\n``service.py:1743`` (live client AND persisted tools); otherwise ``[]``.\nPer-message override tools (#166) are turn-scoped and never appear here.",
"operationId": "admin_session_tools_admin_sessions__session_id__tools_get",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionToolsResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Admin Session Tools"
}
},
"/admin/usage": {
"get": {
"operationId": "admin_usage_admin_usage_get",
"parameters": [
{
"in": "query",
"name": "window",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Window"
}
},
{
"in": "query",
"name": "user_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
}
},
{
"in": "query",
"name": "user_prefix",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Prefix"
}
},
{
"in": "query",
"name": "breakdown",
"required": false,
"schema": {
"default": false,
"title": "Breakdown",
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Admin Usage Admin Usage Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Admin Usage"
}
},
"/admin/users/{user_id}/tier": {
"post": {
"description": "Mutate a user's tier (issue #174).\n\nDrives license-state transitions: `user → suspended` denies access via\nempty-scope policy; `suspended → user` (or whatever prior tier) restores\nit. Tier history is in the audit log; the user record carries only the\ncurrent tier (no previous_tier column — INV-174-8).\n\nClosed-set validation per INV-174-1 — hard-coded vocabulary so a typo\nin policies.yaml can't silently expand the accepted set.",
"operationId": "change_user_tier_admin_users__user_id__tier_post",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserTierChangeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Change User Tier Admin Users User Id Tier Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Change User Tier"
}
},
"/agents": {
"get": {
"description": "List all available agents.",
"operationId": "list_agents_agents_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Response List Agents Agents Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "List Agents"
}
},
"/agents/define": {
"post": {
"description": "Create a Tier 3 consumer-defined agent (#181).\n\nPersists to the ``consumer_agents`` table with the calling key's\n``owner_key_hash``; grants the owner the per-resource\n``agents.call:<user_id>:<agent_name>`` scope; emits an\n``agents.define`` audit event. 422/403/409/429 paths per contract.",
"operationId": "define_consumer_agent_agents_define_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsumerAgentCreateRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Define Consumer Agent Agents Define Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Define Consumer Agent"
}
},
"/agents/{agent_id}": {
"delete": {
"description": "Owner-initiated hard-delete of a Tier 3 agent (#181).\n\nBypasses the 24h grace (operator intent explicit) — distinct from\nthe key-revocation cascade which uses soft-delete-with-grace.",
"operationId": "delete_consumer_agent_agents__agent_id__delete",
"parameters": [
{
"in": "path",
"name": "agent_id",
"required": true,
"schema": {
"title": "Agent Id",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Delete Consumer Agent"
},
"get": {
"description": "Get a single agent's info by id (#169).\n\nPolymorphic response shape:\n\n* Tier 1/2 agents (no colon in agent_id) → AgentInfoResponse\n (identity + persona + ui_hints).\n* Tier 3 consumer-defined agents (``<user_id>:<agent_name>``) →\n ConsumerAgentResponse (the same shape POST /agents/define returns).\n Gated on caller ownership of the row; non-owners receive 404 to\n avoid leaking existence across users.\n\nContract anchor: INV-181-12 forbids LISTING Tier 3 agents via\nGET /agents (plural). The by-id endpoint here is a LOOKUP, not a\nlisting, so owner-scoped Tier 3 access is permitted. Surfaced by\nskaldsong-dev's bootstrap flow (althing thread 01KSF23CEW8AEK7WHH55YDZM2W,\n2026-05-25): the prior over-application of the listing filter to\nthe by-id endpoint left consumers without a way to verify their\nown Tier 3 agent's existence.",
"operationId": "get_agent_agents__agent_id__get",
"parameters": [
{
"in": "path",
"name": "agent_id",
"required": true,
"schema": {
"title": "Agent Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Get Agent Agents Agent Id Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Get Agent"
},
"patch": {
"description": "PATCH a Tier 3 agent (#181, Phase 2.0 minimal).\n\nOnly ``system_prompt`` and ``model`` are mutable. Payload-shape\nvalidation (extra=forbid + layer-field check) runs BEFORE the DB\nlookup so an immutable-field PATCH against a missing agent still\nsurfaces 422 ``field_not_mutable`` (not 404). Active sessions\ncontinue using their cached AgentContext.",
"operationId": "patch_consumer_agent_agents__agent_id__patch",
"parameters": [
{
"in": "path",
"name": "agent_id",
"required": true,
"schema": {
"title": "Agent Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Patch Consumer Agent Agents Agent Id Patch",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Patch Consumer Agent"
}
},
"/agents/{agent_id}/persona_state": {
"get": {
"description": "Return the agent's current persona snapshot (issue #204).\n\nRoute ordering per INV-204-7: auth -> Tier 3 short-circuit ->\nTier 1/2 existence -> persona-enabled -> snapshot.",
"operationId": "get_agent_persona_state_agents__agent_id__persona_state_get",
"parameters": [
{
"in": "path",
"name": "agent_id",
"required": true,
"schema": {
"title": "Agent Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Get Agent Persona State Agents Agent Id Persona State Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Get Agent Persona State"
}
},
"/capabilities": {
"get": {
"description": "Return per-template metadata for ephemeral templates.\n\nCallable by any authenticated user (not gated on instantiate:echo scope).\nThe response is forward-compatible — additional templates appear as sibling\nkeys under ephemeral_templates.",
"operationId": "get_capabilities_capabilities_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Get Capabilities Capabilities Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Get Capabilities"
}
},
"/characters": {
"post": {
"description": "Create a transient character (issue #153). Character lives in-memory\nonly; consumer owns the canonical character JSON.",
"operationId": "create_character_characters_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCharacterRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Create Character Characters Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Create Character"
}
},
"/characters/{character_id}": {
"delete": {
"description": "Delete a transient character (issue #153). Binding sessions detach.",
"operationId": "delete_character_characters__character_id__delete",
"parameters": [
{
"in": "path",
"name": "character_id",
"required": true,
"schema": {
"title": "Character Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Delete Character Characters Character Id Delete",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Delete Character"
}
},
"/characters/{character_id}/state": {
"get": {
"description": "Export a character's runtime state (issue #153).",
"operationId": "get_character_state_characters__character_id__state_get",
"parameters": [
{
"in": "path",
"name": "character_id",
"required": true,
"schema": {
"title": "Character Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Get Character State Characters Character Id State Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Get Character State"
}
},
"/embed": {
"post": {
"description": "Phase 2.1 (#186 INV-186-19, #189 INV-189-10) — embed text(s) with the\npinned embedder.\n\nThe response carries the embedder version in BOTH the body\n(`embedder_version`) and the `X-Worldtree-Embedder-Version` response\nheader; the two MUST agree per turn. 503 if the embedder is not wired\non this service (deployment hasn't completed the Phase 2.1 wiring yet).",
"operationId": "embed_embed_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Payload",
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Embed"
}
},
"/healthz": {
"get": {
"description": "Liveness probe — always 200 if the request reaches the handler.",
"operationId": "healthz_healthz_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": {
"type": "string"
},
"title": "Response Healthz Healthz Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"summary": "Healthz"
}
},
"/judgments": {
"post": {
"description": "Synchronous judgment endpoint for cross-process consumers.\n\nRequires Heimdall scope `domari:invoke`. Returns DomariResponse JSON.\nNo session lifecycle — request-response semantics only.",
"operationId": "post_judgment_judgments_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JudgmentRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Post Judgment Judgments Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Post Judgment"
}
},
"/me": {
"get": {
"description": "Return the authenticated principal's identity and key metadata.\n\nNo rate-limit check (naturally exempt — the per-user budget check is a\nper-handler call inside send_message, not middleware). No audit emission.",
"operationId": "me_me_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Me Me Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Me"
}
},
"/me/usage": {
"get": {
"operationId": "me_usage_me_usage_get",
"parameters": [
{
"in": "query",
"name": "window",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Window"
}
},
{
"in": "query",
"name": "breakdown",
"required": false,
"schema": {
"default": false,
"title": "Breakdown",
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Me Usage Me Usage Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Me Usage"
}
},
"/models/available-for-characters": {
"get": {
"description": "Return the catalog ids bound to the character model role.",
"operationId": "list_models_available_for_characters_models_available_for_characters_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response List Models Available For Characters Models Available For Characters Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "List Models Available For Characters"
}
},
"/pending": {
"get": {
"description": "List active Bus-v2 pending tasks across all sessions for the authenticated user.\n\nRate-limit exempt (INV-068). Requires ``pending.read`` scope.\nTasks with no originator_user_id are excluded. Cross-user data\nis filtered at the bus layer — only tasks submitted with the\ncaller's user_id appear.",
"operationId": "user_pending_pending_get",
"parameters": [
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response User Pending Pending Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "User Pending"
}
},
"/readyz": {
"get": {
"description": "Readiness probe — 200 when ready, 503 with reason otherwise.",
"operationId": "readyz_readyz_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": {
"type": "string"
},
"title": "Response Readyz Readyz Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"summary": "Readyz"
}
},
"/search": {
"get": {
"description": "Cross-session full-text message search backed by SQLite FTS5.",
"operationId": "search_messages_search_get",
"parameters": [
{
"in": "query",
"name": "q",
"required": true,
"schema": {
"maxLength": 200,
"minLength": 1,
"title": "Q",
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor"
}
},
{
"in": "query",
"name": "session_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Session Id"
}
},
{
"in": "query",
"name": "after",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "After"
}
},
{
"in": "query",
"name": "before",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Before"
}
},
{
"in": "query",
"name": "role",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"user",
"assistant"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Role"
}
},
{
"in": "query",
"name": "include_archived",
"required": false,
"schema": {
"default": true,
"title": "Include Archived",
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Search Messages Search Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Search Messages"
}
},
"/sessions": {
"get": {
"description": "List sessions (scoped to authenticated user), paginated by cursor.",
"operationId": "list_sessions_sessions_get",
"parameters": [
{
"in": "query",
"name": "include_archived",
"required": false,
"schema": {
"default": false,
"title": "Include Archived",
"type": "boolean"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response List Sessions Sessions Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "List Sessions"
},
"post": {
"description": "Create a new conversation session.",
"operationId": "create_session_sessions_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSessionRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Create Session Sessions Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Create Session"
}
},
"/sessions/{session_id}": {
"delete": {
"description": "End a session.",
"operationId": "delete_session_sessions__session_id__delete",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Delete Session"
},
"get": {
"description": "Get session info.",
"operationId": "get_session_sessions__session_id__get",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Get Session Sessions Session Id Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Get Session"
},
"patch": {
"description": "Update one or more fields on a session. Empty body is a no-op. Returns updated to_info().",
"operationId": "update_session_sessions__session_id__patch",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSessionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Update Session Sessions Session Id Patch",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Update Session"
}
},
"/sessions/{session_id}/history": {
"post": {
"description": "#347 — write one model-visible turn into a session's ledger AS the bound\nagent, WITHOUT a generation and WITHOUT lived-turn side effects.\n\nHide-existence ordering (INV-347-13): the ``session.history.write`` grant is\nchecked FIRST — before session resolution, before ANY body parse/validation,\nbefore the active-generation guard. An ungranted caller receives ONLY the\nhide-404 (byte-identical to session-not-found, INV-347-1) — never a\n422/409/403 that would distinguish feature-absent from session-absent.",
"operationId": "authored_history_write_sessions__session_id__history_post",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthoredTurnResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Authored History Write"
}
},
"/sessions/{session_id}/messages": {
"get": {
"description": "Return paginated message history for a session.",
"operationId": "get_messages_sessions__session_id__messages_get",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Get Messages Sessions Session Id Messages Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Get Messages"
},
"post": {
"description": "Send a message and stream the agent's response as SSE.\n\nEach SSE ``data`` field is a JSON object with a ``type`` key.\nThe stream ends after a ``done`` or ``error`` event.\n\nIf ``Last-Event-ID`` header is present, resumes an in-flight turn\n(replay + live drain) instead of starting a new one.",
"operationId": "send_message_sessions__session_id__messages_post",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendMessageRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Send Message"
}
},
"/sessions/{session_id}/pending": {
"get": {
"description": "List active Bus-v2 pending tasks for a session (INV-065..INV-071).\n\nRate-limit exempt (INV-068). Requires ``pending.read`` scope.\nReturns ``{items, next_cursor}`` — ``next_cursor`` is null on the last page.",
"operationId": "session_pending_sessions__session_id__pending_get",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Session Pending Sessions Session Id Pending Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Session Pending"
}
},
"/sessions/{session_id}/persona_state": {
"post": {
"description": "Phase 2.1 (#186 INV-186-7, #189 INV-189-9) — set per-session persona baseline.\n\nCross-owner sessions 404 (existence-hiding per #183 INV-183-1). Success\nreturns 204 No Content with NO audit emission — operator-set baselines\nare session-scoped runtime overlays, not security-relevant events.",
"operationId": "set_persona_state_sessions__session_id__persona_state_post",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Payload",
"type": "object"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Set Persona State"
}
},
"/sessions/{session_id}/tool-events": {
"get": {
"description": "Issue #123: paginated tool-call metadata for sessions opted-in via record_tool_intermediates.",
"operationId": "list_tool_events_sessions__session_id__tool_events_get",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response List Tool Events Sessions Session Id Tool Events Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "List Tool Events"
}
},
"/sessions/{session_id}/tools": {
"get": {
"description": "Issue #183: owner-scoped session-tools introspection. Same response\nshape as ``/admin/sessions/<id>/tools`` and same merge predicate;\nowner-gated (``session.user_id == ctx.user_id``) rather than admin-\nscope-gated so Tier 3 owners can debug their own sessions without\nneeding admin keys. INV-183-1 / INV-183-3 / INV-183-4 / INV-183-6.",
"operationId": "get_session_tools_sessions__session_id__tools_get",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionToolsResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Get Session Tools"
}
},
"/sessions/{session_id}/turns/{turn_id}/cancel": {
"post": {
"description": "Cancel an in-flight turn (idempotent; ≤100ms p99 per INV-010..014).\n\nReturns 200 with ``{turn_id, cancelled, reason, partial_message_id}``\non success and idempotent no-ops. Maps unknown sessions, unknown\nturns, and ownership mismatches to 404 (INV-009 — never leak existence).",
"operationId": "cancel_turn_endpoint_sessions__session_id__turns__turn_id__cancel_post",
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"title": "Session Id",
"type": "string"
}
},
{
"in": "path",
"name": "turn_id",
"required": true,
"schema": {
"title": "Turn Id",
"type": "integer"
}
},
{
"in": "query",
"name": "persist_partial",
"required": false,
"schema": {
"default": false,
"title": "Persist Partial",
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Cancel Turn Endpoint Sessions Session Id Turns Turn Id Cancel Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Cancel Turn Endpoint"
}
},
"/uploads": {
"get": {
"description": "List uploads for the authenticated user (paginated).",
"operationId": "list_uploads_uploads_get",
"parameters": [
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response List Uploads Uploads Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "List Uploads"
},
"post": {
"description": "Upload a file. Returns the upload metadata envelope.",
"operationId": "create_upload_uploads_post",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_create_upload_uploads_post"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Create Upload Uploads Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Create Upload"
}
},
"/uploads/{upload_id}": {
"delete": {
"description": "Revoke an upload (idempotent soft-delete).",
"operationId": "delete_upload_uploads__upload_id__delete",
"parameters": [
{
"in": "path",
"name": "upload_id",
"required": true,
"schema": {
"title": "Upload Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Delete Upload Uploads Upload Id Delete",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Delete Upload"
},
"get": {
"description": "Return upload metadata (not content bytes).",
"operationId": "get_upload_uploads__upload_id__get",
"parameters": [
{
"in": "path",
"name": "upload_id",
"required": true,
"schema": {
"title": "Upload Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Get Upload Uploads Upload Id Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"412": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Get Upload"
}
}
}
}
Reference in New Issue View Git Blame Copy Permalink