{ "openapi": "3.1.0", "info": { "title": "Stateful Responses", "version": "0.4.107" }, "paths": { "/health": { "get": { "tags": [ "Operations" ], "summary": "Health Check", "description": "Health check endpoint with optional broker connectivity check.", "operationId": "health_check_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/": { "get": { "tags": [ "Operations" ], "summary": "Root", "description": "Root endpoint.", "operationId": "root__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Root Get" } } } } } } }, "/models": { "get": { "tags": [ "Models" ], "summary": "Get Models Endpoint", "description": "Proxy GET /models to the configured models-available URL.", "operationId": "get_models_endpoint_models_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/responses": { "post": { "tags": [ "Responses" ], "summary": "Post Responses Endpoint", "description": "Handle POST /v1/responses - with history reconstruction and storage.\n\nIf previous_response_id is provided, reconstructs the conversation history\nand includes it in the request to the backend. Stores the request-response\npair for future history reconstruction.\n\nInstructions resolution priority:\n1. prompt.id (render template with variables)\n2. explicit instructions field\n3. inherited from previous_response_id\n4. default_system_prompt from config\n\nSupports both streaming (stream=true) and non-streaming modes.\nSupports background mode (background=true) returning 202.", "operationId": "post_responses_endpoint_v1_responses_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseRequest" } } }, "required": true }, "responses": { "200": { "description": "When `stream=false` (default), returns a JSON response. When `stream=true`, returns Server-Sent Events.", "headers": { "x-aleph-context-budget": { "description": "Context-window usage of the model that produced this response: `used=N; limit=N; pct=N` \u2014 tokens used (usage.total_tokens), the model's configured context limit, and integer percent (floor division, not clamped at 100). Absent when the model has no usable context limit or the response is not completed. Streaming responses carry the same data as a synthetic `aleph.context_budget` SSE event instead.", "schema": { "type": "string", "example": "used=29491; limit=32000; pct=92" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream following the OpenAI Responses API format.\n\nEach event is sent as `data: {json}\\n\\n` with the following event types:\n\n- `response.created` \u2014 initial response object (status: in_progress)\n- `response.in_progress` \u2014 status update\n- `response.output_item.added` \u2014 new output item added\n- `response.content_part.added` \u2014 new content part added\n- `response.output_text.delta` \u2014 incremental text delta\n- `response.completed` \u2014 final event with complete response object\n\nWhen the model has a configured context limit, a vendor-extension event `aleph.context_budget` with `data: {\"used\": N, \"limit\": N, \"pct\": N}` is emitted immediately before `response.completed`. Clients that do not recognise the event name can ignore it.\n\nThe stream ends with `data: [DONE]\\n\\n`." } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Content Too Large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "description": "Too Early", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "Not Implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/responses/compact": { "post": { "tags": [ "Responses" ], "summary": "Post Compact Endpoint", "description": "Handle POST /v1/responses/compact.\n\nLoads the chain anchored at ``previous_response_id``, asks the inference\nbackend (via the same scheduler used by /v1/responses) to summarise it\nusing the fixed summarisation prompt, persists the result via\nCompactionPort, and returns the synthetic CompactedResponse.\n\nPer the ADR: 404 on ownership/missing, 413 on > 10 MiB output,\n502/504 on backend failure, 501 when compaction storage is not\nconfigured. target_size_pct is resolved here from ContextConfig so\nthe domain service stays free of application-layer imports.", "operationId": "post_compact_endpoint_v1_responses_compact_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompactRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompactedResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Content Too Large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "description": "Too Early", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "Not Implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/responses/{response_id}": { "get": { "tags": [ "Responses" ], "summary": "Get Responses Endpoint", "description": "Handle GET /v1/responses/{response_id} - retrieve stored response.\n\nSupports both streaming and non-streaming retrieval.\nFor req_* IDs (background requests), checks pending status first.", "operationId": "get_responses_endpoint_v1_responses__response_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Response Id" } }, { "name": "stream", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Stream" } }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include soft-deleted responses. Admin-only; returns 403 for non-admin callers.", "default": false, "title": "Include Deleted" }, "description": "Include soft-deleted responses. Admin-only; returns 403 for non-admin callers." } ], "responses": { "200": { "description": "When `stream=false` (default), returns a JSON response. When `stream=true`, returns Server-Sent Events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream following the OpenAI Responses API format.\n\nEach event is sent as `data: {json}\\n\\n` with the following event types:\n\n- `response.created` \u2014 initial response object (status: in_progress)\n- `response.in_progress` \u2014 status update\n- `response.output_item.added` \u2014 new output item added\n- `response.content_part.added` \u2014 new content part added\n- `response.output_text.delta` \u2014 incremental text delta\n- `response.completed` \u2014 final event with complete response object\n\nWhen the model has a configured context limit, a vendor-extension event `aleph.context_budget` with `data: {\"used\": N, \"limit\": N, \"pct\": N}` is emitted immediately before `response.completed`. Clients that do not recognise the event name can ignore it.\n\nThe stream ends with `data: [DONE]\\n\\n`." } } }, "headers": { "x-aleph-context-budget": { "description": "Context-window usage of the model that produced this response: `used=N; limit=N; pct=N` \u2014 tokens used (usage.total_tokens), the model's configured context limit, and integer percent (floor division, not clamped at 100). Absent when the model has no usable context limit or the response is not completed. Streaming responses carry the same data as a synthetic `aleph.context_budget` SSE event instead.", "schema": { "type": "string", "example": "used=29491; limit=32000; pct=92" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "delete": { "tags": [ "Responses" ], "summary": "Delete Response Endpoint", "description": "Handle DELETE /v1/responses/{response_id} - delete stored response.\n\nIf the answer is not found, return 200 anyways.", "operationId": "delete_response_endpoint_v1_responses__response_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Response Id" } }, { "name": "hard_delete", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Hard Delete" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "patch": { "tags": [ "Responses" ], "summary": "Update Response Endpoint", "description": "Handle PATCH /v1/responses/{response_id} - update a stored response.", "operationId": "update_response_endpoint_v1_responses__response_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Response Id" } }, { "name": "recovery_from_delete", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Recovery From Delete" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } } }, "/v1/responses/{response_id}/cancel": { "post": { "tags": [ "Responses" ], "summary": "Cancel Response Endpoint", "description": "Handle POST /v1/responses/{response_id}/cancel - cancel a background request.\n\nMirrors the OpenAI Responses ``cancel`` method: only requests created with\n``background=true`` (addressed by their ``req_*`` ID) may be cancelled.\nIdempotent for already-terminal requests.", "operationId": "cancel_response_endpoint_v1_responses__response_id__cancel_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Response Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } } }, "/v1/check": { "post": { "tags": [ "Guardrails" ], "summary": "Post Check Endpoint", "description": "Check content against guardrails for an application.\n\nThe v1 shape: v2-only fields such as ``streaming_allowed`` are dropped.", "operationId": "post_check_endpoint_v1_check_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Content Too Large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "description": "Too Early", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "Not Implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v2/check": { "post": { "tags": [ "Guardrails" ], "summary": "Post Check V2 Endpoint", "description": "Check content against guardrails, reporting ``streaming_allowed`` too.", "operationId": "post_check_v2_endpoint_v2_check_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResponseV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Content Too Large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "description": "Too Early", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "Not Implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/conversations": { "post": { "tags": [ "Conversations" ], "summary": "Create Conversation Endpoint", "description": "Create a new conversation.", "operationId": "create_conversation_endpoint_v1_conversations_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CreateConversationRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "get": { "tags": [ "Conversations" ], "summary": "List Conversations Endpoint", "description": "List conversations for the authenticated user.\n\nAdmin access: when the caller is an admin, ALL users' conversations are\nreturned (titles, metadata, timestamps). This is a privileged operation.", "operationId": "list_conversations_endpoint_v1_conversations_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "title": "Order" } }, { "name": "metadata.application", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Metadata.Application" } }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include soft-deleted conversations. Admin-only; returns 403 for non-admin callers.", "default": false, "title": "Include Deleted" }, "description": "Include soft-deleted conversations. Admin-only; returns 403 for non-admin callers." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationListResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } } }, "/v1/conversations/{conversation_id}": { "get": { "tags": [ "Conversations" ], "summary": "Get Conversation Endpoint", "description": "Retrieve a conversation by ID.\n\nAdmin access: when the caller is an admin, ownership checks are bypassed,\nallowing cross-user retrieval.", "operationId": "get_conversation_endpoint_v1_conversations__conversation_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include soft-deleted conversations. Admin-only; returns 403 for non-admin callers.", "default": false, "title": "Include Deleted" }, "description": "Include soft-deleted conversations. Admin-only; returns 403 for non-admin callers." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "post": { "tags": [ "Conversations" ], "summary": "Update Conversation Endpoint", "description": "Update conversation metadata.\n\nAdmin access: when the caller is an admin, ownership checks are bypassed,\nallowing cross-user metadata updates.", "operationId": "update_conversation_endpoint_v1_conversations__conversation_id__post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversationRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "delete": { "tags": [ "Conversations" ], "summary": "Delete Conversation Endpoint", "description": "Delete a conversation and all its history entries.\n\nSoft-delete by default. When ``hard_delete=True`` and the caller is an\nadmin, the conversation and all associated history entries are permanently\nremoved from the database.\n\nAdmin access: when the caller is an admin, ownership checks are bypassed,\nallowing cross-user deletion.", "operationId": "delete_conversation_endpoint_v1_conversations__conversation_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "hard_delete", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Hard Delete" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "patch": { "tags": [ "Conversations" ], "summary": "Recover Conversation Endpoint", "description": "Handle PATCH /v1/conversations/{conversation_id} - recover a soft-deleted conversation.", "operationId": "recover_conversation_endpoint_v1_conversations__conversation_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "recovery_from_delete", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Recovery From Delete" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } } }, "/v1/conversations/{conversation_id}/responses": { "get": { "tags": [ "Conversations" ], "summary": "List Conversation Responses Endpoint", "description": "List all responses in a conversation.\n\nAdmin access: when the caller is an admin, ownership checks are bypassed,\nallowing cross-user retrieval of conversation responses.", "operationId": "list_conversation_responses_endpoint_v1_conversations__conversation_id__responses_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "default": "asc", "title": "Order" } }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include soft-deleted responses. Admin-only; returns 403 for non-admin callers.", "default": false, "title": "Include Deleted" }, "description": "Include soft-deleted responses. Admin-only; returns 403 for non-admin callers." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponsesList" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } } }, "/v1/skill-create": { "post": { "tags": [ "Skills" ], "summary": "Create Skill From Response Endpoint", "description": "Synthesize a skill from an existing response.\n\nReconstructs the context behind ``response_id`` and asks the inference\nbackend \u2014 via the normal response path (``process_response``) \u2014 to author a\nJSON skill payload using the server-owned synthesis prompt. The skill port\nthen validates and stores the result as a new skill, identical in shape to\n``POST /v1/skills``.", "operationId": "create_skill_from_response_endpoint_v1_skill_create_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCreateFromResponseRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Content Too Large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "description": "Too Early", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "Not Implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/skills": { "post": { "tags": [ "Skills" ], "summary": "Create Skill Endpoint", "description": "Create a skill from a multipart bundle (directory parts or a zip).", "operationId": "create_skill_endpoint_v1_skills_post", "security": [ { "HTTPBearer": [] } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "get": { "tags": [ "Skills" ], "summary": "List Skills Endpoint", "description": "List skills visible to the caller, optionally filtered by name glob.", "operationId": "list_skills_endpoint_v1_skills_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Glob pattern (case-insensitive) to filter by name.", "title": "Name" }, "description": "Glob pattern (case-insensitive) to filter by name." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillListResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } } }, "/v1/skills/{skill_id}/versions": { "post": { "tags": [ "Skills" ], "summary": "Create Skill Version Endpoint", "description": "Create a new version of a skill from a multipart bundle.", "operationId": "create_skill_version_endpoint_v1_skills__skill_id__versions_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersion" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "get": { "tags": [ "Skills" ], "summary": "List Skill Versions Endpoint", "description": "List all versions of a skill, ascending by version.\n\nActivation is per-skill, so every version in the list carries the same\nper-caller ``is_active`` (one activation lookup for the whole list).", "operationId": "list_skill_versions_endpoint_v1_skills__skill_id__versions_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersionListResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } } }, "/v1/skills/{skill_id}/activate": { "post": { "tags": [ "Skills" ], "summary": "Activate Skill Endpoint", "description": "Toggle the caller's activation of a skill (turn it on or off).\n\n``{\"active\": true}`` enables the skill for the authenticated caller (an\nidempotent upsert); ``{\"active\": false}`` disables it (an idempotent\ndelete). The user is always the authenticated caller, never client-supplied.\n\nAuthorization is view-only: the caller must be able to *view* the skill\n(owned or shared into their scope). ``get_skill_metadata`` enforces that and\nyields the skill for the response \u2014 a caller who cannot view it gets the\nexisting 404 ``skill_not_found`` path (no existence leak). A viewer may\nalways toggle their own activation; the owner may disable their own skill.", "operationId": "activate_skill_endpoint_v1_skills__skill_id__activate_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillActivateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } } }, "/v1/skills/{skill_id}/versions/{version}": { "get": { "tags": [ "Skills" ], "summary": "Get Skill Version Endpoint", "description": "Retrieve a specific version's content.\n\nBy default returns that version's ``SKILL.md`` manifest as ``text/markdown``.\nWith ``full_content=true`` returns all files of that version packaged as an\n``application/zip`` archive. Mirrors ``GET /v1/skills/{skill_id}`` but pinned\nto the requested ``version`` rather than the skill's default.", "operationId": "get_skill_version_endpoint_v1_skills__skill_id__versions__version__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version" } }, { "name": "full_content", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, return every file of this version as a zip archive instead of the SKILL.md text.", "default": false, "title": "Full Content" }, "description": "When true, return every file of this version as a zip archive instead of the SKILL.md text." } ], "responses": { "200": { "description": "The version's SKILL.md as text/markdown, or \u2014 with full_content=true \u2014 all files of that version as an application/zip archive.", "content": { "application/json": { "schema": {} }, "text/markdown": {}, "application/zip": {} } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "delete": { "tags": [ "Skills" ], "summary": "Delete Skill Version Endpoint", "description": "Delete a version, applying OpenAI's delete-rules semantics.\n\nReturns ``204`` when the whole skill was removed (last version), or the\nupdated skill when other versions remain.", "operationId": "delete_skill_version_endpoint_v1_skills__skill_id__versions__version__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version" } } ], "responses": { "200": { "description": "The version was deleted and the updated skill is returned because other versions remain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" }, "204": { "description": "The last version was deleted, so the whole skill was removed. No content is returned." } } } }, "/v1/skills/{skill_id}": { "get": { "tags": [ "Skills" ], "summary": "Get Skill Endpoint", "description": "Retrieve a skill's content by ID.\n\nAlways serves the skill's ``default_version``: by default its ``SKILL.md``\nmanifest as ``text/markdown``, or \u2014 with ``full_content=true`` \u2014 all files\nof the default version packaged as an ``application/zip`` archive. Use\n``GET /v1/skills/{skill_id}/versions/{version}`` to fetch a specific\nversion's content.", "operationId": "get_skill_endpoint_v1_skills__skill_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "full_content", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, return every file of the skill's default version as a zip archive instead of the SKILL.md text.", "default": false, "title": "Full Content" }, "description": "When true, return every file of the skill's default version as a zip archive instead of the SKILL.md text." } ], "responses": { "200": { "description": "The skill's SKILL.md as text/markdown, or \u2014 with full_content=true \u2014 all files of the default version as an application/zip archive.", "content": { "application/json": { "schema": {} }, "text/markdown": {}, "application/zip": {} } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "post": { "tags": [ "Skills" ], "summary": "Set Default Skill Version Endpoint", "description": "Set the default version of a skill.", "operationId": "set_default_skill_version_endpoint_v1_skills__skill_id__post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultVersionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "patch": { "tags": [ "Skills" ], "summary": "Patch Skill Endpoint", "description": "Replace the content of a skill's default version in place.\n\nStructurally identical to ``POST /v1/skills`` \u2014 a multipart bundle upload\n(directory parts or a zip) \u2014 but instead of creating a new skill or version\nit overwrites the skill's current default version: both its SKILL.md front\nmatter (manifest) and the stored file bytes. It does NOT create a new\nversion; use ``POST /v1/skills/{skill_id}/versions`` for that.", "operationId": "patch_skill_endpoint_v1_skills__skill_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "delete": { "tags": [ "Skills" ], "summary": "Delete Skill Endpoint", "description": "Delete a skill and cascade to all versions and files.", "operationId": "delete_skill_endpoint_v1_skills__skill_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } } ], "responses": { "204": { "description": "The skill and all its versions and files were deleted. No content is returned." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } } }, "/share/{component}": { "post": { "tags": [ "Share" ], "summary": "Share Grant Endpoint", "description": "POST /share/{component} \u2014 grant (or widen) access to an object.\n\nGated by ``can_share`` and the escalation ladder in the domain layer; every\nACL write goes through the :class:`AuthorizationPort`. Audited on all paths.", "operationId": "share_grant_endpoint_share__component__post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "component", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareGrantRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "get": { "tags": [ "Share" ], "summary": "Share List Endpoint", "description": "GET /share/{component} \u2014 list shares visible to the caller.\n\nWithout ``object_id``: every object of this component shared with the caller\n(via ``list_objects``). With ``object_id``: the full ACL of that object,\ngated by ``can_share`` (owner or tenant admin). Audited on all paths.", "operationId": "share_list_endpoint_share__component__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "component", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "object_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Object Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "delete": { "tags": [ "Share" ], "summary": "Share Revoke Endpoint", "description": "DELETE /share/{component} \u2014 revoke a share rule for an object.\n\nGated by ``can_share`` (same as grant); rejects over-broad deletes. Every\nACL delete goes through the :class:`AuthorizationPort`. Audited on all paths.", "operationId": "share_revoke_endpoint_share__component__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "component", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareRevokeRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } } }, "/admin/retention-policies": { "post": { "tags": [ "Retention" ], "summary": "Create Retention Policy Endpoint", "description": "Create a retention policy for the caller's (or target) application-id.", "operationId": "create_retention_policy_endpoint_admin_retention_policies_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Content Too Large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "description": "Too Early", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "Not Implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/admin/retention-policies/{application_id}": { "get": { "tags": [ "Retention" ], "summary": "Get Retention Policy Endpoint", "description": "Return the effective retention policy for an application-id.", "operationId": "get_retention_policy_endpoint_admin_retention_policies__application_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Application Id" } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include the precedence breakdown when true.", "default": false, "title": "Detail" }, "description": "Include the precedence breakdown when true." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "put": { "tags": [ "Retention" ], "summary": "Update Retention Policy Endpoint", "description": "Partially update an application-id's retention policy.", "operationId": "update_retention_policy_endpoint_admin_retention_policies__application_id__put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Application Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } }, "delete": { "tags": [ "Retention" ], "summary": "Delete Retention Policy Endpoint", "description": "Delete an application-id's retention policy for the caller's tier.", "operationId": "delete_retention_policy_endpoint_admin_retention_policies__application_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Application Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Found" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Content Too Large" }, "422": { "description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically." }, "425": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too Early" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not Implemented" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Gateway Timeout" } } } } }, "components": { "schemas": { "AssignableRoles": { "type": "string", "enum": [ "owner", "editor", "viewer", "shared_in_app", "pharia-ai-admin" ], "title": "AssignableRoles", "description": "Assignable roles on the skill / tenant / organization types.\n\nThese are the only relations that may be written as tuples. The computed\npermissions (``can_admin``, ``can_view``, etc.) are never written as\ntuples, only queried via :meth:`AuthorizationPort.check`." }, "CheckContext": { "properties": { "checkpoint": { "$ref": "#/components/schemas/Checkpoint" }, "user_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Prompt" } }, "additionalProperties": false, "type": "object", "required": [ "checkpoint" ], "title": "CheckContext", "description": "Framing information for a check, carried alongside the content.\n\n``checkpoint`` is the checkpoint being evaluated. ``user_prompt`` is the\nreal user turn that preceded the content under check, when the caller\nhas one. For an ``output`` check it drives the Llama Guard agent-response\nframing: with a ``user_prompt``, the conversation holds a user turn then\nan agent turn; without one, the agent turn alone." }, "CheckRequest": { "properties": { "application_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Application Id" }, "check_type": { "$ref": "#/components/schemas/Checkpoint" }, "input": { "type": "string", "title": "Input" }, "context": { "anyOf": [ { "$ref": "#/components/schemas/CheckContext" }, { "type": "null" } ] }, "images": { "items": { "$ref": "#/components/schemas/GuardrailImage" }, "type": "array", "title": "Images" }, "unreferenced_image_count": { "type": "integer", "minimum": 0.0, "title": "Unreferenced Image Count", "default": 0 }, "if_unconfigured": { "type": "string", "enum": [ "error", "allow" ], "title": "If Unconfigured", "default": "error" } }, "type": "object", "required": [ "check_type", "input" ], "title": "CheckRequest", "description": "Inbound request to check content against guardrails." }, "CheckResponse": { "properties": { "safe": { "type": "boolean", "title": "Safe" }, "violations": { "items": { "$ref": "#/components/schemas/Violation" }, "type": "array", "title": "Violations" }, "action": { "$ref": "#/components/schemas/GuardrailAction", "default": "block" }, "evaluated": { "type": "boolean", "title": "Evaluated", "default": true }, "configured_checkpoints": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Checkpoint" }, "type": "array" }, { "type": "null" } ], "title": "Configured Checkpoints" } }, "type": "object", "required": [ "safe", "violations" ], "title": "CheckResponse", "description": "Result of a guardrail check." }, "CheckResponseV2": { "properties": { "safe": { "type": "boolean", "title": "Safe" }, "violations": { "items": { "$ref": "#/components/schemas/Violation" }, "type": "array", "title": "Violations" }, "action": { "$ref": "#/components/schemas/GuardrailAction", "default": "block" }, "evaluated": { "type": "boolean", "title": "Evaluated", "default": true }, "configured_checkpoints": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Checkpoint" }, "type": "array" }, { "type": "null" } ], "title": "Configured Checkpoints" }, "streaming_allowed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Streaming Allowed" } }, "type": "object", "required": [ "safe", "violations" ], "title": "CheckResponseV2", "description": "Result of a guardrail check, with ``streaming_allowed``." }, "Checkpoint": { "type": "string", "enum": [ "input", "output" ], "title": "Checkpoint", "description": "A point in the request lifecycle a guardrail policy can check.\n\nThe single registry every ``check_types`` key and ``CheckRequest.check_type``\nmust belong to. Adding a checkpoint (``tool_input``, ``tool_output``, ...)\nmeans adding one member here plus its effect-table row, not new branching\nat each call site." }, "CompactRequest": { "properties": { "previous_response_id": { "type": "string", "minLength": 1, "title": "Previous Response Id" } }, "type": "object", "required": [ "previous_response_id" ], "title": "CompactRequest", "description": "Request body for ``POST /v1/responses/compact``.\n\nv1 only accepts ``previous_response_id``. The stateless explicit-input\nvariant is deferred to a future ADR." }, "CompactedResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "integer", "title": "Created At", "description": "Unix epoch seconds." }, "object": { "type": "string", "const": "response.compaction", "title": "Object", "default": "response.compaction" }, "output": { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputItemMessage" }, { "$ref": "#/components/schemas/InputItemReasoning" }, { "$ref": "#/components/schemas/InputItemFunctionCall" }, { "$ref": "#/components/schemas/InputItemFunctionCallOutput" }, { "$ref": "#/components/schemas/InputItemShellCall" }, { "$ref": "#/components/schemas/InputItemShellCallOutput" }, { "$ref": "#/components/schemas/InputItemMcpApprovalRequest" }, { "$ref": "#/components/schemas/InputItemMcpApprovalResponses" }, { "$ref": "#/components/schemas/InputItemMcpListTools" }, { "$ref": "#/components/schemas/InputItemMcpCall" }, { "$ref": "#/components/schemas/InputItemFileSearchCall" }, { "$ref": "#/components/schemas/InputItemWebSearchCall" }, { "$ref": "#/components/schemas/InputItemCompaction" } ], "description": "Input item type, used to determine the input item schema", "discriminator": { "propertyName": "type", "mapping": { "compaction": "#/components/schemas/InputItemCompaction", "file_search_call": "#/components/schemas/InputItemFileSearchCall", "function_call": "#/components/schemas/InputItemFunctionCall", "function_call_output": "#/components/schemas/InputItemFunctionCallOutput", "mcp_approval_request": "#/components/schemas/InputItemMcpApprovalRequest", "mcp_approval_response": "#/components/schemas/InputItemMcpApprovalResponses", "mcp_call": "#/components/schemas/InputItemMcpCall", "mcp_list_tools": "#/components/schemas/InputItemMcpListTools", "message": "#/components/schemas/InputItemMessage", "reasoning": "#/components/schemas/InputItemReasoning", "shell_call": "#/components/schemas/InputItemShellCall", "shell_call_output": "#/components/schemas/InputItemShellCallOutput", "web_search_call": "#/components/schemas/InputItemWebSearchCall" } } }, "type": "array", "title": "Output" }, "usage": { "$ref": "#/components/schemas/UsageInfo" } }, "type": "object", "required": [ "id", "created_at", "output", "usage" ], "title": "CompactedResponse", "description": "Server-shaped compaction response, mirroring OpenAI's compaction object.\n\nThe ``id`` is derived from the persisted row's natural key at\nserialisation time (see ``derive_compaction_id``); it is not stored.\n``output`` contains the synthetic ``compaction`` input-item. The\n``encrypted_content`` field name matches OpenAI; the value is\nplaintext today (real envelope encryption is its own ADR)." }, "ContentItem": { "properties": { "type": { "type": "string", "title": "Type", "default": "output_text" }, "text": { "type": "string", "title": "Text" }, "annotations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Annotations" } }, "type": "object", "required": [ "text" ], "title": "ContentItem", "description": "Content item in response output.\n\nPer Open Responses spec:\n- type: output_text, refusal, etc.\n- text: the actual content\n- annotations: optional metadata" }, "ConversationListResponse": { "properties": { "object": { "type": "string", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/ConversationResponse" }, "type": "array", "title": "Data" }, "has_more": { "type": "boolean", "title": "Has More" }, "first_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Id" }, "last_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Id" } }, "type": "object", "required": [ "data", "has_more" ], "title": "ConversationListResponse", "description": "Paginated response for listing conversations." }, "ConversationRef": { "properties": { "id": { "type": "string", "title": "Id" } }, "type": "object", "required": [ "id" ], "title": "ConversationRef", "description": "Minimal conversation reference embedded in response objects." }, "ConversationResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "object": { "type": "string", "title": "Object", "default": "conversation" }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metadata" }, "created_at": { "type": "integer", "title": "Created At" }, "updated_at": { "type": "integer", "title": "Updated At" } }, "type": "object", "required": [ "id", "created_at", "updated_at" ], "title": "ConversationResponse", "description": "API response schema for conversations \u2014 excludes internal fields." }, "ConversationResponseItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "The unique ID of the response." }, "object": { "type": "string", "title": "Object", "description": "The object type.", "default": "response" }, "created_at": { "type": "integer", "title": "Created At", "description": "The Unix timestamp (in seconds) for when the response was created." }, "completed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completed At", "description": "The Unix timestamp (in seconds) for when the response was completed." }, "status": { "type": "string", "title": "Status", "description": "The status of the response.", "default": "completed" }, "incomplete_details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Incomplete Details", "description": "Details about why the response was incomplete, if applicable." }, "model": { "type": "string", "title": "Model", "description": "The model that generated this response." }, "previous_response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Response Id", "description": "The ID of the previous response in the conversation chain, if any." }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Additional instructions used to guide the model for this response." }, "output": { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputItemMessage" }, { "$ref": "#/components/schemas/InputItemReasoning" }, { "$ref": "#/components/schemas/InputItemFunctionCall" }, { "$ref": "#/components/schemas/InputItemFunctionCallOutput" }, { "$ref": "#/components/schemas/InputItemShellCall" }, { "$ref": "#/components/schemas/InputItemShellCallOutput" }, { "$ref": "#/components/schemas/InputItemMcpApprovalRequest" }, { "$ref": "#/components/schemas/InputItemMcpApprovalResponses" }, { "$ref": "#/components/schemas/InputItemMcpListTools" }, { "$ref": "#/components/schemas/InputItemMcpCall" }, { "$ref": "#/components/schemas/InputItemFileSearchCall" }, { "$ref": "#/components/schemas/InputItemWebSearchCall" }, { "$ref": "#/components/schemas/InputItemCompaction" } ], "description": "Input item type, used to determine the input item schema", "discriminator": { "propertyName": "type", "mapping": { "compaction": "#/components/schemas/InputItemCompaction", "file_search_call": "#/components/schemas/InputItemFileSearchCall", "function_call": "#/components/schemas/InputItemFunctionCall", "function_call_output": "#/components/schemas/InputItemFunctionCallOutput", "mcp_approval_request": "#/components/schemas/InputItemMcpApprovalRequest", "mcp_approval_response": "#/components/schemas/InputItemMcpApprovalResponses", "mcp_call": "#/components/schemas/InputItemMcpCall", "mcp_list_tools": "#/components/schemas/InputItemMcpListTools", "message": "#/components/schemas/InputItemMessage", "reasoning": "#/components/schemas/InputItemReasoning", "shell_call": "#/components/schemas/InputItemShellCall", "shell_call_output": "#/components/schemas/InputItemShellCallOutput", "web_search_call": "#/components/schemas/InputItemWebSearchCall" } } }, "type": "array", "title": "Output", "description": "The output items generated by the model." }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Error", "description": "The error that occurred, if the response failed." }, "tools": { "items": { "oneOf": [ { "$ref": "#/components/schemas/Function" }, { "$ref": "#/components/schemas/MCPTool" }, { "$ref": "#/components/schemas/FileSearchTool" }, { "$ref": "#/components/schemas/ShellTool" }, { "$ref": "#/components/schemas/WebSearchTool" } ], "description": "Tool type, used to determine the tool schema", "discriminator": { "propertyName": "type", "mapping": { "file_search": "#/components/schemas/FileSearchTool", "function": "#/components/schemas/Function", "mcp": "#/components/schemas/MCPTool", "shell": "#/components/schemas/ShellTool", "web_search": "#/components/schemas/WebSearchTool" } } }, "type": "array", "title": "Tools", "description": "The tools available to the model during response generation." }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "auto", "required", "none" ] }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Tool Choice", "description": "Controls which tool the model should use, if any." }, "truncation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Truncation", "description": "How the input was truncated when it exceeded the model context window." }, "parallel_tool_calls": { "type": "boolean", "title": "Parallel Tool Calls", "description": "Whether the model was allowed to call multiple tools in parallel.", "default": true }, "text": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Text", "description": "Configuration options for text output." }, "top_p": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Top P", "description": "The nucleus sampling parameter used for this response." }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Temperature", "description": "The sampling temperature used for this response." }, "presence_penalty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Presence Penalty", "description": "Penalizes new tokens based on whether they appear in the text so far." }, "frequency_penalty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Frequency Penalty", "description": "Penalizes new tokens based on their frequency in the text so far." }, "top_logprobs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Top Logprobs", "description": "Number of most likely tokens returned at each position." }, "reasoning": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Reasoning", "description": "Reasoning configuration and outputs produced for this response." }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/UsageInfo" }, { "type": "null" } ], "description": "Token usage statistics for the response.", "default": { "input_tokens": 0, "output_tokens": 0, "total_tokens": 0 } }, "max_output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Output Tokens", "description": "The maximum number of tokens the model was allowed to generate." }, "max_tool_calls": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Tool Calls", "description": "The maximum number of tool calls the model was allowed to make." }, "store": { "type": "boolean", "title": "Store", "description": "Whether this response was stored for later retrieval.", "default": true }, "background": { "type": "boolean", "title": "Background", "description": "Whether this request was run in the background.", "default": false }, "service_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Tier", "description": "The service tier used for this response." }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Key-value pairs for storing additional information about the response." }, "prompt_cache_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt Cache Key", "description": "A key used to read from or write to the prompt cache." }, "conversation": { "anyOf": [ { "$ref": "#/components/schemas/ConversationRef" }, { "type": "null" } ], "description": "The conversation this response belongs to, if any." }, "safety_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Safety Identifier", "description": "A stable identifier used for safety monitoring and abuse detection." }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "32-character lowercase hex OpenTelemetry trace ID for the generation request. Server-populated from the active span when the generated response is completed. Null on incomplete, failed, cancelled, in-progress, synthetic, historical, and tracing-disabled responses." }, "ancestor_ids": { "items": { "type": "string" }, "type": "array", "title": "Ancestor Ids" }, "depth": { "type": "integer", "title": "Depth" }, "request_input": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Request Input" } }, "type": "object", "required": [ "id", "created_at", "model", "output", "ancestor_ids", "depth", "request_input" ], "title": "ConversationResponseItem", "description": "Full response plus tree metadata and user input for conversation listing." }, "ConversationResponsesList": { "properties": { "object": { "type": "string", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/ConversationResponseItem" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "ConversationResponsesList", "description": "Response for listing all responses in a conversation." }, "CreateConversationRequest": { "properties": { "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata" } }, "type": "object", "title": "CreateConversationRequest", "description": "Request body for creating a conversation." }, "ErrorDetail": { "properties": { "message": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Type" }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Param" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code" } }, "type": "object", "required": [ "message", "type" ], "title": "ErrorDetail", "description": "Structured error detail matching the OpenAI Responses API convention." }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse", "description": "Structured error envelope." }, "ExpiryAction": { "type": "string", "enum": [ "soft-delete", "hard-delete" ], "title": "ExpiryAction", "description": "What happens to a record when its retention period elapses." }, "FileSearchAttachment": { "properties": { "searchStoreId": { "type": "string", "title": "Searchstoreid" }, "fileId": { "type": "string", "title": "Fileid" }, "documentId": { "type": "string", "title": "Documentid" }, "fileName": { "type": "string", "title": "Filename" } }, "type": "object", "required": [ "searchStoreId", "fileId", "documentId", "fileName" ], "title": "FileSearchAttachment", "description": "Uploaded Sherlock document reference carried in a ``file_search`` tool.\n\nPhoenix currently sends camelCase attachment refs. Stateful accepts both\ncamelCase and snake_case so callers do not have to care which side of the\nPython boundary they are on." }, "FileSearchTool": { "properties": { "type": { "type": "string", "const": "file_search", "title": "Type", "description": "Tool type, must be 'file_search'" }, "attachments": { "items": { "$ref": "#/components/schemas/FileSearchAttachment" }, "type": "array", "title": "Attachments" }, "citations": { "type": "boolean", "title": "Citations", "default": true }, "search_store_ids": { "items": { "type": "string" }, "type": "array", "title": "Search Store Ids" } }, "type": "object", "required": [ "type" ], "title": "FileSearchTool", "description": "Aleph/OpenResponses hosted file-search tool definition.\n\nA single hosted tool can scope search/read to either uploaded documents\n(``attachments``) and/or whole knowledge-base stores (``search_store_ids``)." }, "Function": { "properties": { "type": { "type": "string", "const": "function", "title": "Type", "description": "Tool type, must be 'function'" }, "name": { "type": "string", "title": "Name", "description": "Name of the function tool" }, "parameters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Parameters" }, "strict": { "type": "boolean", "title": "Strict", "default": true }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "type": "object", "required": [ "type", "name" ], "title": "Function", "description": "Function tool definition (client-executed)." }, "GuardrailAction": { "type": "string", "enum": [ "allow", "label", "block" ], "title": "GuardrailAction", "description": "What happens to a message a guardrail flagged.\n\n``ALLOW`` passes it to the model untouched. ``LABEL`` passes it together\nwith a notice naming the flagged categories, so the model can decline or\nanswer only the harmless part. ``BLOCK`` stops the request before it\nreaches the model." }, "GuardrailImage": { "properties": { "search_store_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "title": "Search Store Id" }, "file_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "title": "File Id" } }, "additionalProperties": false, "type": "object", "required": [ "search_store_id", "file_id" ], "title": "GuardrailImage", "description": "An image to check, named by where it already lives in the Data Platform.\n\nThe caller never sends image bytes: it names the search store and file the\nimage was stored in, and an image provider fetches it from there with the\ncaller's token." }, "ImageDetail": { "type": "string", "enum": [ "low", "high", "auto" ], "title": "ImageDetail", "description": "Requested vision fidelity for an ``input_image`` part.\n\nForwarded verbatim to the backend; ``auto`` lets the backend decide." }, "InputImageContentPart": { "properties": { "type": { "type": "string", "const": "input_image", "title": "Type" }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image Url" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Id" }, "detail": { "$ref": "#/components/schemas/ImageDetail", "default": "auto" } }, "type": "object", "required": [ "type" ], "title": "InputImageContentPart", "description": "A typed ``input_image`` content part on an input message.\n\nWire-compatible with OpenAI's ``InputImageContent`` (``type``, ``image_url``,\n``file_id``, ``detail``). Exactly one of ``image_url`` / ``file_id`` must be\nsupplied (see :meth:`_validate_source`):\n\n- a ``data:`` ``image_url`` is the case-1 direct-upload signal (inline\n base64 bytes the input protocol uploads to the Data Platform);\n- a ``file_id`` is case-2 (a reference to a pre-existing Data Platform file).\n\nA **non-**``data:`` ``image_url`` (a fully-qualified external URL) is out of\nscope and rejected with :class:`NotImplementedError`; see\n``spec/09-image-inputs.md`` Non-goals. We never fetch arbitrary caller URLs.\n\nAfter ingestion by the input protocol (see ``spec/09-image-inputs.md`` \u00a75),\n``file_id`` carries a structured :class:`~stateful_responses.domain.images.ImageFileReference`\n(encoded JSON), never inline bytes." }, "InputItemCompaction": { "properties": { "type": { "type": "string", "const": "compaction", "title": "Type" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "Identifier of the compaction item." }, "encrypted_content": { "type": "string", "maxLength": 10485760, "title": "Encrypted Content", "description": "The (potentially encrypted) content of the compaction summary." } }, "type": "object", "required": [ "type", "encrypted_content" ], "title": "InputItemCompaction", "description": "Compaction item \u2014 opaque summary blob, mirrors OpenAI's `/v1/responses/compact` shape." }, "InputItemFileSearchCall": { "properties": { "type": { "type": "string", "const": "file_search_call", "title": "Type" }, "id": { "type": "string", "pattern": "^fs_[a-zA-Z0-9_\\-.:]+$", "title": "Id", "description": "Unique identifier for the file search call" }, "status": { "type": "string", "enum": [ "in_progress", "searching", "completed", "incomplete", "failed" ], "title": "Status" }, "queries": { "items": { "type": "string" }, "type": "array", "title": "Queries" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" } }, "type": "object", "required": [ "type", "status" ], "title": "InputItemFileSearchCall", "description": "Hosted file-search call/result output item.\n\nMirrors OpenAI/OpenResponses ``file_search_call`` enough for upstream\nPydanticAI clients to map it as a native tool call while allowing Sherlock\nresult extensions in ``results``." }, "InputItemFunctionCall": { "properties": { "type": { "type": "string", "const": "function_call", "title": "Type" }, "id": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-.:]+$", "title": "Id", "description": "Unique identifier for the function call" }, "call_id": { "type": "string", "title": "Call Id" }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, { "type": "null" } ], "title": "Status" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "arguments": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Arguments" } }, "type": "object", "required": [ "type", "id", "call_id" ], "title": "InputItemFunctionCall", "description": "Input item for function call (history reconstruction)." }, "InputItemFunctionCallOutput": { "properties": { "type": { "type": "string", "const": "function_call_output", "title": "Type" }, "call_id": { "type": "string", "title": "Call Id" }, "id": { "anyOf": [ { "type": "string", "pattern": "^fco_[a-zA-Z0-9_\\-.:]+$" }, { "type": "null" } ], "title": "Id", "description": "Unique identifier for the function call output" }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, { "type": "null" } ], "title": "Status" }, "output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output" } }, "type": "object", "required": [ "type", "call_id" ], "title": "InputItemFunctionCallOutput", "description": "Input item for function call (history reconstruction)." }, "InputItemMcpApprovalRequest": { "properties": { "type": { "type": "string", "const": "mcp_approval_request", "title": "Type" }, "id": { "type": "string", "pattern": "^mcpr_[a-zA-Z0-9_\\-.:]+$", "title": "Id", "description": "Unique identifier for the approval request" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "server_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Server Label" }, "arguments": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Arguments" } }, "type": "object", "required": [ "type", "id" ], "title": "InputItemMcpApprovalRequest" }, "InputItemMcpApprovalResponses": { "properties": { "type": { "type": "string", "const": "mcp_approval_response", "title": "Type" }, "id": { "type": "string", "pattern": "^mcpa_[a-zA-Z0-9_\\-.:]+$", "title": "Id", "description": "Unique identifier for the approval response" }, "approval_request_id": { "type": "string", "title": "Approval Request Id" }, "approve": { "type": "boolean", "title": "Approve" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Why the call was not approved. Filled in by the service when the user sent a new message instead of answering." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "arguments": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Arguments" } }, "type": "object", "required": [ "type", "id", "approval_request_id", "approve" ], "title": "InputItemMcpApprovalResponses" }, "InputItemMcpCall": { "properties": { "type": { "type": "string", "const": "mcp_call", "title": "Type" }, "id": { "type": "string", "pattern": "^mcp_[a-zA-Z0-9_\\-.:]+$", "title": "Id", "description": "Unique identifier for the MCP call" }, "name": { "type": "string", "title": "Name" }, "arguments": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Arguments" }, "server_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Server Label" }, "output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/McpToolExecutionError" }, { "type": "null" } ], "description": "Set when the tool ran and failed. Null on success." } }, "type": "object", "required": [ "type", "id", "name" ], "title": "InputItemMcpCall" }, "InputItemMcpListTools": { "properties": { "type": { "type": "string", "const": "mcp_list_tools", "title": "Type" }, "id": { "type": "string", "pattern": "^mcpl_[a-zA-Z0-9_\\-.:]+$", "title": "Id", "description": "Unique identifier for the MCP list tools" }, "server_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Server Label" }, "tools": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Tools" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "type", "id" ], "title": "InputItemMcpListTools" }, "InputItemMessage": { "properties": { "type": { "type": "string", "const": "message", "title": "Type" }, "id": { "anyOf": [ { "type": "string", "pattern": "^msg_[a-zA-Z0-9_\\-.:]+$" }, { "type": "null" } ], "title": "Id", "description": "Unique identifier for messages" }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, { "type": "null" } ], "title": "Status" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "items": { "$ref": "#/components/schemas/ContentItem" }, "type": "array" }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentPart" }, { "$ref": "#/components/schemas/InputImageContentPart" } ], "description": "A typed input content part (input_text/input_image).", "discriminator": { "propertyName": "type", "mapping": { "input_image": "#/components/schemas/InputImageContentPart", "input_text": "#/components/schemas/InputTextContentPart" } } }, "type": "array" }, { "type": "null" } ], "title": "Content" } }, "type": "object", "required": [ "type" ], "title": "InputItemMessage", "description": "Input item for structured input.\n\nPer Open Responses spec, supports:\n- message type: role + content\n- function_call type: call_id + name + arguments (for history)\n- function_call_output type: call_id + output (tool results)\n\nFields:\n- id: unique identifier (optional on input, populated on output)\n- status: in_progress, completed, incomplete (optional on input)" }, "InputItemReasoning": { "properties": { "type": { "type": "string", "const": "reasoning", "title": "Type" }, "id": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-.:]+$", "title": "Id", "description": "Unique identifier for reasoning messages" }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, { "type": "null" } ], "title": "Status" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "items": { "$ref": "#/components/schemas/ContentItem" }, "type": "array" }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentPart" }, { "$ref": "#/components/schemas/InputImageContentPart" } ], "description": "A typed input content part (input_text/input_image).", "discriminator": { "propertyName": "type", "mapping": { "input_image": "#/components/schemas/InputImageContentPart", "input_text": "#/components/schemas/InputTextContentPart" } } }, "type": "array" }, { "type": "null" } ], "title": "Content" }, "summary": { "items": { "$ref": "#/components/schemas/ReasoningSummaryItem" }, "type": "array", "title": "Summary", "description": "Reasoning summary items returned by the downstream service." } }, "type": "object", "required": [ "type", "id" ], "title": "InputItemReasoning", "description": "Input item for reasoning type messages." }, "InputItemShellCall": { "properties": { "type": { "type": "string", "const": "shell_call", "title": "Type" }, "id": { "type": "string", "title": "Id", "description": "Unique identifier for the shell call" }, "call_id": { "type": "string", "title": "Call Id" }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, { "type": "null" } ], "title": "Status" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "arguments": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Arguments" } }, "type": "object", "required": [ "type", "id", "call_id" ], "title": "InputItemShellCall", "description": "Input item for shell tool call (history reconstruction)." }, "InputItemShellCallOutput": { "properties": { "type": { "type": "string", "const": "shell_call_output", "title": "Type" }, "call_id": { "type": "string", "title": "Call Id" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "Unique identifier for the shell call output" }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, { "type": "null" } ], "title": "Status" }, "output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output" } }, "type": "object", "required": [ "type", "call_id" ], "title": "InputItemShellCallOutput", "description": "Input item for shell tool call output (history reconstruction)." }, "InputItemWebSearchCall": { "properties": { "type": { "type": "string", "const": "web_search_call", "title": "Type" }, "id": { "type": "string", "pattern": "^ws_[a-zA-Z0-9_-]+$", "title": "Id", "description": "Unique identifier for the web search call" }, "status": { "type": "string", "enum": [ "in_progress", "searching", "completed", "failed" ], "title": "Status" }, "action": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Action", "description": "How the model invoked the tool, e.g. {\"type\": \"search\", \"query\": ...}" }, "results": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results" } }, "type": "object", "required": [ "type", "status" ], "title": "InputItemWebSearchCall", "description": "Hosted web-search call/result output item.\n\nMirrors OpenAI/OpenResponses ``web_search_call`` enough for upstream\nclients to map it as a native tool call while embedding the LinkUp\nresults directly in ``results``." }, "InputTextContentPart": { "properties": { "type": { "type": "string", "const": "input_text", "title": "Type" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "type", "text" ], "title": "InputTextContentPart", "description": "A typed ``input_text`` content part on an input message.\n\nMirrors OpenAI's ``InputTextContent`` (see ``openapi.yaml``): the textual\ncounterpart to :class:`InputImageContentPart` in a multimodal message's\n``content`` list." }, "MCPTool": { "properties": { "type": { "type": "string", "const": "mcp", "title": "Type", "description": "Tool type, must be 'mcp'" }, "server_url": { "type": "string", "title": "Server Url", "description": "URL for the server to call when executing the tool" }, "require_approval": { "type": "string", "enum": [ "always", "never" ], "title": "Require Approval", "description": "Whether the server requires approval before calling the tool. 'always' means approval is required, 'never' means no approval needed.", "default": "always" }, "server_label": { "type": "string", "title": "Server Label", "description": "Label for the tool to be used by the server" }, "allowed_tools": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Tools", "description": "Optional dict or array of allowed tools that the server can call, keyed by tool name. This can be used to specify which tools the server is allowed to call, and can include additional configuration for each tool." }, "authorization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization", "description": "Optional authorization information for the server to use when calling the tool. This can include API keys, tokens, or other credentials needed to access the tool." }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Headers", "description": "Optional headers to include when the server calls the tool. This can be used to provide additional context or information needed for the tool execution." }, "server_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Server Description", "description": "Optional description for the server to understand the tool's purpose" }, "on_unavailable": { "type": "string", "enum": [ "fail", "skip" ], "title": "On Unavailable", "description": "What to do when the server's tools cannot be listed. 'fail' fails the response. 'skip' records the error on the mcp_list_tools item and answers without this server's tools. Not part of the OpenAI API.", "default": "fail" } }, "type": "object", "required": [ "type", "server_url", "server_label" ], "title": "MCPTool", "description": "MCP hosted tool definition (server-executed)." }, "McpToolExecutionError": { "properties": { "type": { "type": "string", "const": "mcp_tool_execution_error", "title": "Type", "default": "mcp_tool_execution_error" }, "content": { "type": "string", "title": "Content" } }, "type": "object", "required": [ "content" ], "title": "McpToolExecutionError", "description": "The tool's own error, in the shape the OpenAI SDK's mcp_call uses." }, "ObjectType": { "type": "string", "enum": [ "skill", "skill_version", "application" ], "title": "ObjectType" }, "PromptConfig": { "properties": { "id": { "type": "string", "title": "Id" }, "variables": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Variables" } }, "type": "object", "required": [ "id" ], "title": "PromptConfig", "description": "Prompt template configuration." }, "PublicScope": { "type": "string", "enum": [ "org", "tenant", "everyone", "app" ], "title": "PublicScope", "description": "Public-visibility scopes accepted by the ``/share`` API request body.\n\nThis is the *externally documented* contract\n(``docs/planning/openfga-skills-authz.md``, \"CRUD: /share/skills\":\n``public_scope: \"org\" | \"tenant\" | \"everyone\" | \"app\"``) \u2014 deliberately\ndistinct from the internal :class:`UserType`, which names OpenFGA subject types\n(``organization`` / ``tenant`` / ``public`` / ``application``). Keeping them\nseparate stops the internal enum leaking into the public API;\n:meth:`to_user_type` maps a scope onto the userset :class:`UserType` the domain\nlayer expects.\n\n``app`` makes a skill viewable (read-only) to everyone connecting through the\ncaller's *own* application; it is OpenFGA-only (the Postgres owner/public subset\nrejects it)." }, "ReasoningSummaryItem": { "properties": { "type": { "type": "string", "const": "summary_text", "title": "Type" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "type", "text" ], "title": "ReasoningSummaryItem", "description": "Summary item for reasoning output messages." }, "ResponseRequest": { "properties": { "model": { "type": "string", "title": "Model", "description": "The model to use for this request." }, "input": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputItemMessage" }, { "$ref": "#/components/schemas/InputItemReasoning" }, { "$ref": "#/components/schemas/InputItemFunctionCall" }, { "$ref": "#/components/schemas/InputItemFunctionCallOutput" }, { "$ref": "#/components/schemas/InputItemShellCall" }, { "$ref": "#/components/schemas/InputItemShellCallOutput" }, { "$ref": "#/components/schemas/InputItemMcpApprovalRequest" }, { "$ref": "#/components/schemas/InputItemMcpApprovalResponses" }, { "$ref": "#/components/schemas/InputItemMcpListTools" }, { "$ref": "#/components/schemas/InputItemMcpCall" }, { "$ref": "#/components/schemas/InputItemFileSearchCall" }, { "$ref": "#/components/schemas/InputItemWebSearchCall" }, { "$ref": "#/components/schemas/InputItemCompaction" } ], "description": "Input item type, used to determine the input item schema", "discriminator": { "propertyName": "type", "mapping": { "compaction": "#/components/schemas/InputItemCompaction", "file_search_call": "#/components/schemas/InputItemFileSearchCall", "function_call": "#/components/schemas/InputItemFunctionCall", "function_call_output": "#/components/schemas/InputItemFunctionCallOutput", "mcp_approval_request": "#/components/schemas/InputItemMcpApprovalRequest", "mcp_approval_response": "#/components/schemas/InputItemMcpApprovalResponses", "mcp_call": "#/components/schemas/InputItemMcpCall", "mcp_list_tools": "#/components/schemas/InputItemMcpListTools", "message": "#/components/schemas/InputItemMessage", "reasoning": "#/components/schemas/InputItemReasoning", "shell_call": "#/components/schemas/InputItemShellCall", "shell_call_output": "#/components/schemas/InputItemShellCallOutput", "web_search_call": "#/components/schemas/InputItemWebSearchCall" } } }, "type": "array" } ], "title": "Input", "description": "Context for the model. May be a string or an array of input items." }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Additional instructions to guide the model for this request." }, "previous_response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Response Id", "description": "The ID of the response to use as the prior turn." }, "prompt": { "anyOf": [ { "$ref": "#/components/schemas/PromptConfig" }, { "type": "null" } ] }, "temperature": { "anyOf": [ { "type": "number", "maximum": 2.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Temperature", "description": "Sampling temperature between 0 and 2." }, "top_p": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Top P", "description": "Nucleus sampling parameter, between 0 and 1." }, "max_output_tokens": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Max Output Tokens", "description": "The maximum number of tokens the model may generate." }, "stream": { "type": "boolean", "title": "Stream", "description": "Whether to stream response events as server-sent events.", "default": false }, "stop": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Stop" }, "modify_request": { "type": "boolean", "title": "Modify Request", "default": true }, "conversation": { "anyOf": [ { "$ref": "#/components/schemas/ConversationRef" }, { "type": "null" } ] }, "tools": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/Function" }, { "$ref": "#/components/schemas/MCPTool" }, { "$ref": "#/components/schemas/FileSearchTool" }, { "$ref": "#/components/schemas/ShellTool" }, { "$ref": "#/components/schemas/WebSearchTool" } ], "description": "Tool type, used to determine the tool schema", "discriminator": { "propertyName": "type", "mapping": { "file_search": "#/components/schemas/FileSearchTool", "function": "#/components/schemas/Function", "mcp": "#/components/schemas/MCPTool", "shell": "#/components/schemas/ShellTool", "web_search": "#/components/schemas/WebSearchTool" } } }, "type": "array" }, { "type": "null" } ], "title": "Tools", "description": "A list of tools that the model may call while generating the response." }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "auto", "required", "none" ] }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Tool Choice", "description": "Controls which tool the model should use, if any." }, "parallel_tool_calls": { "type": "boolean", "title": "Parallel Tool Calls", "description": "Whether the model may call multiple tools in parallel.", "default": true }, "include": { "anyOf": [ { "items": { "type": "string", "enum": [ "message.output_text.logprobs", "reasoning.encrypted_content" ] }, "type": "array" }, { "type": "null" } ], "title": "Include" }, "store": { "type": "boolean", "title": "Store", "description": "Whether to store the response so it can be retrieved later.", "default": true }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Key-value pairs for storing additional information about the object." }, "truncation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Truncation", "description": "Controls how the service truncates input exceeding the context window." }, "text": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Text", "description": "Configuration options for text output." }, "presence_penalty": { "anyOf": [ { "type": "number", "maximum": 2.0, "minimum": -2.0 }, { "type": "null" } ], "title": "Presence Penalty", "description": "Penalizes new tokens based on whether they appear in the text so far." }, "frequency_penalty": { "anyOf": [ { "type": "number", "maximum": 2.0, "minimum": -2.0 }, { "type": "null" } ], "title": "Frequency Penalty", "description": "Penalizes new tokens based on their frequency in the text so far." }, "top_logprobs": { "anyOf": [ { "type": "integer", "maximum": 20.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Top Logprobs", "description": "Number of most likely tokens to return at each position." }, "max_tool_calls": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Max Tool Calls", "description": "The maximum number of tool calls the model may make." }, "service_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Tier", "description": "The service tier to use for this request." }, "background": { "type": "boolean", "title": "Background", "description": "Whether to run the request in the background and return immediately.", "default": false }, "reasoning": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Reasoning", "description": "Configuration options for reasoning behavior." } }, "type": "object", "required": [ "model", "input" ], "title": "ResponseRequest", "description": "Request for Open Responses API.\n\nSupports MCP hosted tools (server-executed)." }, "ResponseResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "The unique ID of the response." }, "object": { "type": "string", "title": "Object", "description": "The object type.", "default": "response" }, "created_at": { "type": "integer", "title": "Created At", "description": "The Unix timestamp (in seconds) for when the response was created." }, "completed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completed At", "description": "The Unix timestamp (in seconds) for when the response was completed." }, "status": { "type": "string", "title": "Status", "description": "The status of the response.", "default": "completed" }, "incomplete_details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Incomplete Details", "description": "Details about why the response was incomplete, if applicable." }, "model": { "type": "string", "title": "Model", "description": "The model that generated this response." }, "previous_response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Response Id", "description": "The ID of the previous response in the conversation chain, if any." }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Additional instructions used to guide the model for this response." }, "output": { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputItemMessage" }, { "$ref": "#/components/schemas/InputItemReasoning" }, { "$ref": "#/components/schemas/InputItemFunctionCall" }, { "$ref": "#/components/schemas/InputItemFunctionCallOutput" }, { "$ref": "#/components/schemas/InputItemShellCall" }, { "$ref": "#/components/schemas/InputItemShellCallOutput" }, { "$ref": "#/components/schemas/InputItemMcpApprovalRequest" }, { "$ref": "#/components/schemas/InputItemMcpApprovalResponses" }, { "$ref": "#/components/schemas/InputItemMcpListTools" }, { "$ref": "#/components/schemas/InputItemMcpCall" }, { "$ref": "#/components/schemas/InputItemFileSearchCall" }, { "$ref": "#/components/schemas/InputItemWebSearchCall" }, { "$ref": "#/components/schemas/InputItemCompaction" } ], "description": "Input item type, used to determine the input item schema", "discriminator": { "propertyName": "type", "mapping": { "compaction": "#/components/schemas/InputItemCompaction", "file_search_call": "#/components/schemas/InputItemFileSearchCall", "function_call": "#/components/schemas/InputItemFunctionCall", "function_call_output": "#/components/schemas/InputItemFunctionCallOutput", "mcp_approval_request": "#/components/schemas/InputItemMcpApprovalRequest", "mcp_approval_response": "#/components/schemas/InputItemMcpApprovalResponses", "mcp_call": "#/components/schemas/InputItemMcpCall", "mcp_list_tools": "#/components/schemas/InputItemMcpListTools", "message": "#/components/schemas/InputItemMessage", "reasoning": "#/components/schemas/InputItemReasoning", "shell_call": "#/components/schemas/InputItemShellCall", "shell_call_output": "#/components/schemas/InputItemShellCallOutput", "web_search_call": "#/components/schemas/InputItemWebSearchCall" } } }, "type": "array", "title": "Output", "description": "The output items generated by the model." }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Error", "description": "The error that occurred, if the response failed." }, "tools": { "items": { "oneOf": [ { "$ref": "#/components/schemas/Function" }, { "$ref": "#/components/schemas/MCPTool" }, { "$ref": "#/components/schemas/FileSearchTool" }, { "$ref": "#/components/schemas/ShellTool" }, { "$ref": "#/components/schemas/WebSearchTool" } ], "description": "Tool type, used to determine the tool schema", "discriminator": { "propertyName": "type", "mapping": { "file_search": "#/components/schemas/FileSearchTool", "function": "#/components/schemas/Function", "mcp": "#/components/schemas/MCPTool", "shell": "#/components/schemas/ShellTool", "web_search": "#/components/schemas/WebSearchTool" } } }, "type": "array", "title": "Tools", "description": "The tools available to the model during response generation." }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "auto", "required", "none" ] }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Tool Choice", "description": "Controls which tool the model should use, if any." }, "truncation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Truncation", "description": "How the input was truncated when it exceeded the model context window." }, "parallel_tool_calls": { "type": "boolean", "title": "Parallel Tool Calls", "description": "Whether the model was allowed to call multiple tools in parallel.", "default": true }, "text": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Text", "description": "Configuration options for text output." }, "top_p": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Top P", "description": "The nucleus sampling parameter used for this response." }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Temperature", "description": "The sampling temperature used for this response." }, "presence_penalty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Presence Penalty", "description": "Penalizes new tokens based on whether they appear in the text so far." }, "frequency_penalty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Frequency Penalty", "description": "Penalizes new tokens based on their frequency in the text so far." }, "top_logprobs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Top Logprobs", "description": "Number of most likely tokens returned at each position." }, "reasoning": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Reasoning", "description": "Reasoning configuration and outputs produced for this response." }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/UsageInfo" }, { "type": "null" } ], "description": "Token usage statistics for the response.", "default": { "input_tokens": 0, "output_tokens": 0, "total_tokens": 0 } }, "max_output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Output Tokens", "description": "The maximum number of tokens the model was allowed to generate." }, "max_tool_calls": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Tool Calls", "description": "The maximum number of tool calls the model was allowed to make." }, "store": { "type": "boolean", "title": "Store", "description": "Whether this response was stored for later retrieval.", "default": true }, "background": { "type": "boolean", "title": "Background", "description": "Whether this request was run in the background.", "default": false }, "service_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Tier", "description": "The service tier used for this response." }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Key-value pairs for storing additional information about the response." }, "prompt_cache_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt Cache Key", "description": "A key used to read from or write to the prompt cache." }, "conversation": { "anyOf": [ { "$ref": "#/components/schemas/ConversationRef" }, { "type": "null" } ], "description": "The conversation this response belongs to, if any." }, "safety_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Safety Identifier", "description": "A stable identifier used for safety monitoring and abuse detection." }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "32-character lowercase hex OpenTelemetry trace ID for the generation request. Server-populated from the active span when the generated response is completed. Null on incomplete, failed, cancelled, in-progress, synthetic, historical, and tracing-disabled responses." } }, "type": "object", "required": [ "id", "created_at", "model", "output" ], "title": "ResponseResponse", "description": "Response from Open Responses API.\n\nAll fields marked as required in the OpenResponses spec are present here.\nNullable fields default to None and are serialized as null (not omitted)." }, "RetentionPolicyCreateRequest": { "properties": { "application_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Application Id" }, "retention_period": { "type": "string", "title": "Retention Period" }, "expiry_action": { "$ref": "#/components/schemas/ExpiryAction", "default": "soft-delete" }, "grace_period": { "type": "string", "title": "Grace Period", "default": "7d" }, "hard_delete_after_grace": { "type": "boolean", "title": "Hard Delete After Grace", "default": false }, "schedule": { "type": "string", "title": "Schedule", "default": "0 0 * * *" } }, "type": "object", "required": [ "retention_period" ], "title": "RetentionPolicyCreateRequest", "description": "Request body for creating a retention policy via the admin API." }, "RetentionPolicyUpdateRequest": { "properties": { "retention_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retention Period" }, "expiry_action": { "anyOf": [ { "$ref": "#/components/schemas/ExpiryAction" }, { "type": "null" } ] }, "grace_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Grace Period" }, "hard_delete_after_grace": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Hard Delete After Grace" }, "schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schedule" } }, "type": "object", "title": "RetentionPolicyUpdateRequest", "description": "Request body for partially updating a retention policy.\n\nEvery field is optional; only provided fields are applied." }, "SetDefaultVersionRequest": { "properties": { "default_version": { "type": "integer", "title": "Default Version" } }, "type": "object", "required": [ "default_version" ], "title": "SetDefaultVersionRequest", "description": "Request body for setting a skill's default version.\n\nShared by ``POST /v1/skills/{skill_id}`` (set default version) and\n``UPDATE /v1/skills/{skill_id}`` (OpenAI-compatible update); both accept ONLY\n``{\"default_version\": }`` and repoint the skill's default version." }, "ShareGrantRequest": { "properties": { "object_id": { "type": "string", "title": "Object Id" }, "users": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Users" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization" }, "public_scope": { "anyOf": [ { "$ref": "#/components/schemas/PublicScope" }, { "type": "null" } ] }, "permission": { "$ref": "#/components/schemas/AssignableRoles" } }, "type": "object", "required": [ "object_id", "permission" ], "title": "ShareGrantRequest", "description": "POST /share/{component} body \u2014 grant (or widen) access to an object.\n\n``object_id`` is the id of the object of the path's component; addressed\ngenerically as ``{component}:{object_id}``." }, "ShareRevokeRequest": { "properties": { "object_id": { "type": "string", "title": "Object Id" }, "users": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Users" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization" }, "public_scope": { "anyOf": [ { "$ref": "#/components/schemas/PublicScope" }, { "type": "null" } ] }, "permission": { "anyOf": [ { "$ref": "#/components/schemas/AssignableRoles" }, { "type": "null" } ] } }, "type": "object", "required": [ "object_id" ], "title": "ShareRevokeRequest", "description": "DELETE /share/{component} body \u2014 revoke a specific share rule." }, "ShellEnvironment": { "properties": { "type": { "type": "string", "title": "Type", "description": "Environment type (e.g. 'container_auto')" }, "skills": { "items": { "$ref": "#/components/schemas/SkillReference" }, "type": "array", "title": "Skills", "description": "Skills available in the shell environment" } }, "type": "object", "required": [ "type" ], "title": "ShellEnvironment", "description": "Environment configuration for a shell tool." }, "ShellTool": { "properties": { "type": { "type": "string", "const": "shell", "title": "Type", "description": "Tool type, must be 'shell'" }, "environment": { "$ref": "#/components/schemas/ShellEnvironment", "description": "Environment configuration for the shell tool" } }, "type": "object", "required": [ "type", "environment" ], "title": "ShellTool", "description": "Shell tool definition (server-executed in a containerized environment)." }, "SkillActivateRequest": { "properties": { "active": { "type": "boolean", "title": "Active" } }, "type": "object", "required": [ "active" ], "title": "SkillActivateRequest", "description": "Request body for ``POST /v1/skills/{skill_id}/activate``.\n\n``active=True`` turns the skill on for the authenticated caller (an\nidempotent upsert of the ``(user_id, skill_id)`` activation row);\n``active=False`` turns it off (an idempotent delete). The user is always the\nauthenticated caller, never client-supplied." }, "SkillCreateFromResponseRequest": { "properties": { "response_id": { "type": "string", "title": "Response Id" } }, "type": "object", "required": [ "response_id" ], "title": "SkillCreateFromResponseRequest", "description": "Request body for ``POST /v1/skill-create``." }, "SkillListResponse": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/SkillResponse" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "SkillListResponse", "description": "Response body for listing skills." }, "SkillManifest": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License" }, "compatibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Compatibility" }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metadata" }, "allowed_tools": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Allowed Tools" } }, "type": "object", "required": [ "name", "description" ], "title": "SkillManifest", "description": "Parsed ``SKILL.md`` YAML front matter.\n\n``name`` and ``description`` are required; everything else is optional and\npreserved verbatim. The hyphenated spec key ``allowed-tools`` is mapped to\n:attr:`allowed_tools` during parsing." }, "SkillReference": { "properties": { "type": { "type": "string", "const": "skill_reference", "title": "Type", "description": "Type, must be 'skill_reference'" }, "skill_id": { "type": "string", "title": "Skill Id", "description": "Identifier of the skill" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version", "description": "Optional version of the skill to use" } }, "type": "object", "required": [ "type", "skill_id" ], "title": "SkillReference", "description": "A reference to a skill available in a shell environment." }, "SkillResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "object": { "type": "string", "const": "skill", "title": "Object", "default": "skill" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metadata" }, "default_version": { "type": "integer", "title": "Default Version" }, "latest_version": { "type": "integer", "title": "Latest Version" }, "created_at": { "type": "integer", "title": "Created At" }, "is_active": { "type": "boolean", "title": "Is Active", "default": false } }, "type": "object", "required": [ "id", "name", "description", "default_version", "latest_version", "created_at" ], "title": "SkillResponse", "description": "API response schema for a skill (excludes internal ownership fields).\n\n``metadata`` mirrors the ``default_version`` manifest's ``metadata`` map so\ncallers can read per-skill flags from the list without an extra request per\nskill to fetch the version manifest." }, "SkillVersion": { "properties": { "skill_id": { "type": "string", "title": "Skill Id" }, "version": { "type": "integer", "title": "Version" }, "created_at": { "type": "integer", "title": "Created At" }, "file_count": { "type": "integer", "title": "File Count" }, "size_bytes": { "type": "integer", "title": "Size Bytes" }, "manifest": { "$ref": "#/components/schemas/SkillManifest" } }, "type": "object", "required": [ "skill_id", "version", "created_at", "file_count", "size_bytes", "manifest" ], "title": "SkillVersion", "description": "A single version of a skill: metadata plus that version's manifest." }, "SkillVersionListResponse": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/SkillVersionResponse" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "SkillVersionListResponse", "description": "Response body for listing a skill's versions." }, "SkillVersionResponse": { "properties": { "skill_id": { "type": "string", "title": "Skill Id" }, "version": { "type": "integer", "title": "Version" }, "created_at": { "type": "integer", "title": "Created At" }, "file_count": { "type": "integer", "title": "File Count" }, "size_bytes": { "type": "integer", "title": "Size Bytes" }, "manifest": { "$ref": "#/components/schemas/SkillManifest" }, "is_active": { "type": "boolean", "title": "Is Active", "default": false } }, "type": "object", "required": [ "skill_id", "version", "created_at", "file_count", "size_bytes", "manifest" ], "title": "SkillVersionResponse", "description": "API response schema for one skill version.\n\nMirrors the internal :class:`SkillVersion` domain model and adds the\nper-caller :attr:`is_active` flag. Activation is a per-skill fact, so every\nversion of a skill carries the same ``is_active`` for a given caller." }, "UpdateConversationRequest": { "properties": { "metadata": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metadata" } }, "type": "object", "required": [ "metadata" ], "title": "UpdateConversationRequest", "description": "Request body for updating conversation metadata." }, "UsageInfo": { "properties": { "input_tokens": { "type": "integer", "title": "Input Tokens" }, "output_tokens": { "type": "integer", "title": "Output Tokens" }, "total_tokens": { "type": "integer", "title": "Total Tokens" } }, "type": "object", "required": [ "input_tokens", "output_tokens", "total_tokens" ], "title": "UsageInfo", "description": "Token usage information." }, "Violation": { "properties": { "category": { "type": "string", "title": "Category" }, "provider": { "type": "string", "title": "Provider" }, "stage": { "type": "string", "title": "Stage" }, "step": { "type": "integer", "title": "Step" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "type": "object", "required": [ "category", "provider", "stage", "step" ], "title": "Violation", "description": "A single guardrail violation.\n\nAttribution fields (``provider``, ``stage``, ``step``) identify which\npipeline stage produced the violation so callers running multi-provider\npipelines can tell regex matches from llama-guard classifications.\n\n``reason`` is an optional human-readable explanation. Regex matches do\nnot populate it (the category is sufficient); ``provider_error`` and\nricher providers may set it to surface why a step failed or matched." }, "WebSearchFilters": { "properties": { "allowed_domains": { "items": { "type": "string" }, "type": "array", "title": "Allowed Domains", "description": "Restrict the search to these domains" }, "blocked_domains": { "items": { "type": "string" }, "type": "array", "title": "Blocked Domains", "description": "Exclude these domains from the search" } }, "type": "object", "title": "WebSearchFilters", "description": "Domain filters for hosted web search." }, "WebSearchTool": { "properties": { "type": { "type": "string", "const": "web_search", "title": "Type", "description": "Tool type, must be 'web_search'" }, "depth": { "type": "string", "enum": [ "fast", "standard", "deep" ], "title": "Depth", "description": "LinkUp search depth: 'fast', 'standard' or 'deep'", "default": "standard" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/WebSearchFilters" }, { "type": "null" } ], "description": "Optional domain allow/block lists for the search" } }, "type": "object", "required": [ "type" ], "title": "WebSearchTool", "description": "Hosted web-search tool definition (LinkUp-backed, server-executed).\n\nExposes agentic ``web_search`` and ``fetch_url`` function tools to the\nmodel; both are executed server-side against the LinkUp API. ``depth``\nmaps directly onto LinkUp's search depth \u2014 no translation layer." } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Responses", "description": "Create, retrieve, and delete responses. Supports streaming and multi-turn conversations via response chaining." }, { "name": "Conversations", "description": "Create, retrieve, update, delete, and list conversations." }, { "name": "Skills", "description": "Upload, version, manage, and reference reusable skill bundles." }, { "name": "Guardrails", "description": "Check content against guardrail policies." }, { "name": "Models", "description": "List available inference models." }, { "name": "Operations", "description": "Health checks and operational endpoints." } ], "security": [ { "HTTPBearer": [] } ], "servers": [ { "url": "{host}", "variables": { "host": { "default": "https://api.pharia.example.com" } } } ] }