{ "openapi": "3.1.0", "info": { "title": "Perplexity AI API", "description": "Perplexity AI API", "version": "1.0.0" }, "servers": [ { "url": "https://api.perplexity.ai", "description": "Perplexity AI API" } ], "paths": { "/v1/sonar": { "post": { "summary": "Create Chat Completion", "description": "Generate a chat completion response for the given conversation.", "operationId": "chat_completions_chat_completions_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiChatCompletionsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/search": { "post": { "summary": "Search the Web", "operationId": "search_search_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Search the web and retrieve relevant web page contents." } }, "/v1/embeddings": { "post": { "summary": "Create Embeddings", "description": "Generate embeddings for a list of texts. Use these embeddings for semantic search, clustering, and other machine learning applications.", "operationId": "embeddings_v1_embeddings_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/contextualizedembeddings": { "post": { "summary": "Create Contextualized Embeddings", "description": "Generate contextualized embeddings for document chunks. Chunks from the same document share context awareness, improving retrieval quality for document-based applications.", "operationId": "contextualized_embeddings_v1_contextualizedembeddings_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextualizedEmbeddingsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextualizedEmbeddingsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/async/sonar/{api_request}": { "get": { "summary": "Get Async Chat Completion", "description": "Retrieve the response for a given asynchronous chat completion request.", "operationId": "get_async_chat_completion_response_async_chat_completions__api_request__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "api_request", "in": "path", "required": true, "schema": { "type": "string", "title": "Api Request" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncApiChatCompletionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/async/sonar": { "get": { "summary": "List Async Chat Completions", "description": "Retrieve a list of all asynchronous chat completion requests for a given user.", "operationId": "list_async_chat_completions_async_chat_completions_get", "security": [ { "HTTPBearer": [] } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAsyncApiChatCompletionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "summary": "Create Async Chat Completion", "description": "Submit an asynchronous chat completion request.", "operationId": "create_async_chat_completions_async_chat_completions_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncApiChatCompletionsRequest" }, "example": { "request": { "model": "sonar-deep-research", "messages": [ { "role": "", "content": "" } ] } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncApiChatCompletionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agent": { "post": { "description": "Generate a response for the provided input with optional web search and reasoning.", "operationId": "createAgent", "summary": "Create Agent Response", "security": [ { "HTTPBearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ResponseStreamEvent" } } }, "description": "Successful response. Content type depends on `stream` parameter:\n- `stream: false` (default): `application/json` with Response\n- `stream: true`: `text/event-stream` with SSE events\n" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorInfo" } } } } }, "description": "Invalid request. Includes an unresolvable `previous_response_id`: the referenced response does not exist, belongs to a different account, has failed, or is still running." } } } }, "/v1/agent/{id}": { "get": { "description": "Retrieve a response created earlier. Returns a JSON snapshot of the response. Only responses created with `store` omitted or `true` can be retrieved; `store: false` responses return a 404.", "operationId": "retrieveAgent", "summary": "Retrieve Agent Response", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Response id (`resp_<...>`)" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } } }, "description": "JSON snapshot of the response." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorInfo" } } } } }, "description": "Unknown id, or the response belongs to a different account, or the response was created with `store: false`." } } } }, "/v1/agent/{id}/files": { "get": { "summary": "List Agent Response Files", "description": "List the files a response produced in the sandbox and delivered with the `share_file` tool. Scoped to the authenticated account, which only ever sees its own files. File content is not returned inline; download it with the file content endpoint.", "operationId": "listAgentFiles", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Response id (`resp_<...>`)" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseFileList" } } }, "description": "The list of files delivered from the response's sandbox." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorInfo" } } } } }, "description": "Unknown id, or the response belongs to a different account." } } } }, "/v1/agent/{id}/files/{file_id}/content": { "get": { "summary": "Download Agent Response File", "description": "Download the raw bytes of a file the response delivered with the `share_file` tool. The `file_id` comes from the file list endpoint and is distinct from the response `id`. The response streams raw bytes, not JSON, with a `Content-Type` matching the file and a `Content-Disposition: attachment` header carrying the original filename.", "operationId": "downloadAgentFile", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Response id (`resp_<...>`)" }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File id from the file list endpoint" } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "description": "The raw file bytes." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorInfo" } } } } }, "description": "Unknown response id or file id, or the response belongs to a different account." } } } }, "/v1/agent/{id}/cancel": { "post": { "summary": "Cancel Agent Response", "description": "Requests cancellation of response `{id}`. Acts on durable state, so it works for background runs that outlive the client connection. Cancellation is asynchronous: a `200` acknowledges the request (`status: cancelling`) and the run stops shortly after - poll `GET /v1/agent/{id}` for its terminal status. Cancelling a run that is already terminal returns `400`. Ownership is enforced server side; a cross-tenant or unknown id surfaces as `404`.", "operationId": "cancelAgentResponse", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Response id (`resp_<...>`)" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "response_id", "status" ], "properties": { "response_id": { "type": "string", "description": "The response id (`resp_<...>`)." }, "status": { "type": "string", "enum": [ "cancelling" ], "description": "Always `cancelling` - the cancel was accepted and the run stops asynchronously. An already-terminal run returns `400` instead, so no terminal status appears here." } } } } }, "description": "The cancel request was accepted; the run is being cancelled." }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorInfo" } } } } }, "description": "The response is already terminal, or the request is invalid." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorInfo" } } } } }, "description": "Unknown id, or the response belongs to a different account." } } } }, "/v1/models": { "get": { "summary": "List Models", "description": "List the models available for the Agent API. Returns model identifiers that can be used with the `POST /v1/agent` endpoint. The response follows the OpenAI List Models format for compatibility with third-party tools.", "operationId": "listModels", "security": [], "responses": { "200": { "description": "Successful response with the list of available models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" }, "example": { "object": "list", "data": [ { "id": "anthropic/claude-opus-5", "object": "model", "created": 0, "owned_by": "anthropic" }, { "id": "anthropic/claude-opus-5-5", "object": "model", "created": 0, "owned_by": "anthropic" }, { "id": "anthropic/claude-opus-4-8", "object": "model", "created": 0, "owned_by": "anthropic" }, { "id": "anthropic/claude-sonnet-5", "object": "model", "created": 0, "owned_by": "anthropic" }, { "id": "anthropic/claude-fable-5", "object": "model", "created": 0, "owned_by": "anthropic" }, { "id": "anthropic/claude-sonnet-4-6", "object": "model", "created": 0, "owned_by": "anthropic" }, { "id": "openai/gpt-6-sol", "object": "model", "created": 0, "owned_by": "openai" }, { "id": "openai/gpt-6-luna", "object": "model", "created": 0, "owned_by": "openai" }, { "id": "openai/gpt-5.6-sol", "object": "model", "created": 0, "owned_by": "openai" }, { "id": "openai/gpt-5.6-terra", "object": "model", "created": 0, "owned_by": "openai" }, { "id": "openai/gpt-5.6-luna", "object": "model", "created": 0, "owned_by": "openai" }, { "id": "openai/gpt-5.5", "object": "model", "created": 0, "owned_by": "openai" }, { "id": "google/gemini-3.1-flash-lite", "object": "model", "created": 0, "owned_by": "google" }, { "id": "google/gemini-3.5-flash", "object": "model", "created": 0, "owned_by": "google" }, { "id": "google/gemini-3.5-flash-lite", "object": "model", "created": 0, "owned_by": "google" }, { "id": "google/gemini-3.6-flash", "object": "model", "created": 0, "owned_by": "google" }, { "id": "google/gemini-3.7-flash", "object": "model", "created": 0, "owned_by": "google" }, { "id": "google/gemini-3.8-flash", "object": "model", "created": 0, "owned_by": "google" }, { "id": "xai/grok-4.7", "object": "model", "created": 0, "owned_by": "xai" }, { "id": "xai/grok-4.6", "object": "model", "created": 0, "owned_by": "xai" }, { "id": "xai/grok-4.5", "object": "model", "created": 0, "owned_by": "xai" }, { "id": "xai/grok-4.3", "object": "model", "created": 0, "owned_by": "xai" }, { "id": "xai/grok-4.20-reasoning", "object": "model", "created": 0, "owned_by": "xai" }, { "id": "xai/grok-4.20-non-reasoning", "object": "model", "created": 0, "owned_by": "xai" }, { "id": "xai/grok-4.20-multi-agent", "object": "model", "created": 0, "owned_by": "xai" }, { "id": "perplexity/glm-5.3", "object": "model", "created": 0, "owned_by": "perplexity" }, { "id": "perplexity/glm-5.3-flash", "object": "model", "created": 0, "owned_by": "perplexity" }, { "id": "perplexity/kimi-k3", "object": "model", "created": 0, "owned_by": "moonshotai" }, { "id": "perplexity/sonar", "object": "model", "created": 0, "owned_by": "perplexity" } ] } } } } } } }, "/v1/analytics/computer/usage": { "get": { "summary": "Usage Analytics", "description": "Returns your organization's Perplexity usage analytics as a bucketed time series for a single dataset. Requires an organization analytics API key, generated by an org admin from Settings → Organization → Computer in the Perplexity web app. Only complete UTC grid buckets are returned: start_time snaps down to its bucket, and the in-progress bucket is never included. Datasets differ in what they count: credits for credit_usage, queries for query_volume, distinct active members for daily_active_users, and thread counts for the rest. Buckets of daily_active_users are not additive — a member active on several days is counted once per day, so summing them is not the window's active-member count.", "operationId": "getComputerUsageAnalytics", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "dataset", "in": "query", "required": true, "description": "The dataset to query. query_volume and daily_active_users are daily organization-level datasets: they reject bucket_width=1h and user_email.", "schema": { "type": "string", "enum": [ "credit_usage", "connectors", "artifacts", "skills", "spaces", "workflows", "task_durations", "query_volume", "daily_active_users" ] } }, { "name": "start_time", "in": "query", "required": true, "description": "Window start in unix seconds (UTC), inclusive. Snapped down to the bucket grid, so the first bucket can include usage from before this time.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "end_time", "in": "query", "required": false, "description": "Window end in unix seconds (UTC), exclusive. Defaults to now; future values are capped at now. The window may span at most 90 days.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "bucket_width", "in": "query", "required": false, "description": "Bucket size. Buckets align to the UTC grid. Not accepted as 1h for query_volume or daily_active_users, which are stored at day grain.", "schema": { "type": "string", "enum": [ "1d", "1h" ], "default": "1d" } }, { "name": "limit", "in": "query", "required": false, "description": "Buckets per page. 1d: default 7, max 31. 1h: default 24, max 168.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response's next_page. Valid only with the same query parameters it was issued for.", "schema": { "type": "string" } }, { "name": "user_email", "in": "query", "required": false, "description": "Restrict results to a single member of your organization. Emails that don't match a current member return a generic 400. Not available for query_volume or daily_active_users, which are aggregated per organization; use the v2 endpoint for per-member query volume.", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "Bucketed usage for the requested window. Buckets without data carry count 0; the analytics store syncs periodically, so a zero in a recent bucket can mean the data hasn't synced yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerUsageResponse" }, "example": { "categories": [ "Model", "Credit Source" ], "data": [ { "start_time": 1746057600, "end_time": 1746144000, "count": 350, "by_categories": { "Model": [ { "category": "claude-opus-4-8", "count": 210 }, { "category": "claude-sonnet-4-6", "count": 120 } ], "Credit Source": [ { "category": "paid", "count": 250 }, { "category": "promo", "count": 80 } ] } } ], "has_more": false, "next_page": null } } } }, "400": { "description": "Invalid parameters (type: bad_request) or semantically invalid request (type: invalid_request) — e.g. start_time after end_time, a window over 90 days, a misused pagination cursor, or a user_email that doesn't match a member of the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsErrorResponse" }, "example": { "error": { "message": "start_time must be before end_time.", "type": "invalid_request", "code": 400 } } } } }, "401": { "description": "Missing or invalid API key (type: unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsErrorResponse" } } } }, "404": { "description": "The Analytics API is not enabled for this organization (type: feature_disabled).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsErrorResponse" } } } }, "429": { "description": "Rate limit exceeded (type: request_rate_limit_exceeded). Limits apply per organization across all of its keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsErrorResponse" } } } } } } }, "/v2/analytics/computer/usage": { "get": { "summary": "Usage Analytics per Member", "description": "Returns your organization's Perplexity usage broken down per member, as daily buckets. Each day lists one row per member with usage that day, keyed by email. credit_usage carries the same Model and Credit Source breakdown as v1; query_volume carries Feature, Project and Comet. Uses the same organization analytics API key as v1. Only complete UTC days are returned; the in-progress day is never included.", "operationId": "getComputerUsageAnalyticsV2", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "dataset", "in": "query", "required": true, "description": "The dataset to query. query_volume at this grain carries Feature, Project and Comet breakdowns, but not Model or Model Family.", "schema": { "type": "string", "enum": [ "credit_usage", "query_volume" ] } }, { "name": "group_by", "in": "query", "required": true, "description": "The dimension to group each day's usage by. user_email is currently the only supported value.", "schema": { "type": "string", "enum": [ "user_email" ] } }, { "name": "start_time", "in": "query", "required": true, "description": "Window start in unix seconds (UTC), inclusive. Snapped down to the day grid, so the first day can include usage from before this time.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "end_time", "in": "query", "required": false, "description": "Window end in unix seconds (UTC), exclusive. Defaults to now; future values are capped at now. The window may span at most 90 days.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Member rows per page. Default 50, max 100. A page can span multiple days.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response's next_page. Valid only with the same query parameters it was issued for.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-member daily usage for the requested window. Days with no attributable usage are omitted; the analytics store syncs periodically, so recent days may not yet be present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerUsageV2Response" }, "example": { "categories": [ "Model", "Credit Source" ], "data": [ { "start_time": 1746057600, "end_time": 1746144000, "results": [ { "user_email": "alice@example.com", "count": 900, "by_categories": { "Model": [ { "category": "claude-opus-4-8", "count": 900 } ], "Credit Source": [ { "category": "paid", "count": 900 } ] } }, { "user_email": "bob@example.com", "count": 500, "by_categories": { "Model": [ { "category": "claude-sonnet-4-6", "count": 500 } ], "Credit Source": [ { "category": "promo", "count": 500 } ] } } ] } ], "has_more": true, "next_page": "eyJwayI6ICJPUkcjLi4uIn0=" } } } }, "400": { "description": "Invalid parameters (type: bad_request) — e.g. a dataset or group_by outside the accepted values — or a semantically invalid request (type: invalid_request), e.g. start_time after end_time, a window over 90 days, or a misused pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsErrorResponse" }, "example": { "error": { "message": "start_time must be before end_time.", "type": "invalid_request", "code": 400 } } } } }, "401": { "description": "Missing or invalid API key (type: unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsErrorResponse" } } } }, "404": { "description": "The Analytics API is not enabled for this organization (type: feature_disabled).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsErrorResponse" } } } }, "429": { "description": "Rate limit exceeded (type: request_rate_limit_exceeded). Limits apply per organization across all of its keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsErrorResponse" } } } } } } }, "/v1/skills": { "get": { "operationId": "listSkills", "summary": "List skills", "description": "Lists the skills in your Project, newest first.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Available skills", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Skill service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ], "tags": [ "Skills" ] }, "post": { "operationId": "createSkill", "summary": "Create a skill", "description": "Creates a skill from a zip bundle. The bundle must contain a `SKILL.md`\nthat provides the skill name and description; those fields are read from\nthe bundle, not from the request.\n", "requestBody": { "$ref": "#/components/requestBodies/SkillBundle" }, "responses": { "201": { "description": "The created skill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedSkill" } } } }, "400": { "description": "Invalid request or bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Skill limit reached for this Project; delete a skill to create another", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Bundle exceeds the size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit or upload concurrency limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Skill service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ], "tags": [ "Skills" ] } }, "/v1/skills/{skill_id}": { "get": { "operationId": "getSkill", "summary": "Get a skill", "description": "Returns a skill. Without `revision`, returns the active revision.", "parameters": [ { "$ref": "#/components/parameters/SkillId" }, { "$ref": "#/components/parameters/Revision" } ], "responses": { "200": { "description": "The skill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedSkill" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Skill or revision not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Skill service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ], "tags": [ "Skills" ] }, "put": { "operationId": "updateSkill", "summary": "Add a skill revision", "description": "Uploads a new zip bundle as a new revision of an existing skill. Pass the\nrevision you expect to replace as the required `expected_revision`; the\nrequest fails with `409` if the skill has already moved past it, so the\nupdate cannot race a concurrent write. Name and description are re-read\nfrom the new bundle.\n", "parameters": [ { "$ref": "#/components/parameters/SkillId" }, { "$ref": "#/components/parameters/ExpectedRevisionRequired" } ], "requestBody": { "$ref": "#/components/requestBodies/SkillBundle" }, "responses": { "200": { "description": "The updated skill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedSkill" } } } }, "400": { "description": "Invalid request or bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Revision conflict; the skill moved past expected_revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Bundle exceeds the size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit or upload concurrency limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Skill service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ], "tags": [ "Skills" ] }, "delete": { "operationId": "deleteSkill", "summary": "Delete a skill", "description": "Deletes a skill. Pass the current revision as `expected_revision`; the\ndelete fails with `409` if the skill has a newer revision, so a delete\nnever races a concurrent update.\n", "parameters": [ { "$ref": "#/components/parameters/SkillId" }, { "$ref": "#/components/parameters/ExpectedRevisionRequired" } ], "responses": { "204": { "description": "Skill deleted" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Revision conflict; the skill moved past expected_revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Skill service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ], "tags": [ "Skills" ] } }, "/v1/skills/{skill_id}/revisions": { "get": { "operationId": "listSkillRevisions", "summary": "List skill revisions", "description": "Lists the revisions of a skill, newest first.", "parameters": [ { "$ref": "#/components/parameters/SkillId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "The skill revisions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillRevisionList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Skill service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ], "tags": [ "Skills" ] } }, "/v1/skills/{skill_id}/download": { "get": { "operationId": "downloadSkill", "summary": "Get a skill download URL", "description": "Returns a short-lived URL to download the skill bundle as a zip. Without\n`revision`, returns the active revision.\n", "parameters": [ { "$ref": "#/components/parameters/SkillId" }, { "$ref": "#/components/parameters/Revision" } ], "responses": { "200": { "description": "The skill bundle download", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillDownload" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Skill or revision not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Skill service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ], "tags": [ "Skills" ] } } }, "components": { "schemas": { "ApiChatCompletionsRequest": { "properties": { "max_tokens": { "anyOf": [ { "type": "integer", "maximum": 128000.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Max Tokens", "description": "Maximum number of completion tokens to generate" }, "model": { "type": "string", "title": "Model", "description": "Model to use, for example, sonar-pro", "enum": [ "sonar", "sonar-pro", "sonar-deep-research", "sonar-reasoning-pro" ] }, "stream": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Stream", "description": "If true, returns streaming SSE response", "default": false }, "stop": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Stop", "description": "Stop sequences. Generation stops when one of these strings is produced" }, "temperature": { "anyOf": [ { "type": "number", "minimum": 0.0, "maximum": 2.0 }, { "type": "null" } ], "title": "Temperature", "description": "Controls randomness in the response. Higher values make output more random. Range: 0-2" }, "top_p": { "anyOf": [ { "type": "number", "minimum": 0.0, "maximum": 1.0 }, { "type": "null" } ], "title": "Top P", "description": "Nucleus sampling parameter. Controls diversity via nucleus sampling" }, "response_format": { "anyOf": [ { "$ref": "#/components/schemas/ResponseFormatText" }, { "$ref": "#/components/schemas/ResponseFormatJSONSchema" }, { "type": "null" } ], "title": "Response Format", "description": "Optional. Controls the output format. Omit for default text output. Set `type` to `json_schema` for structured output.", "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/ResponseFormatText", "json_schema": "#/components/schemas/ResponseFormatJSONSchema" } } }, "messages": { "items": { "$ref": "#/components/schemas/ChatMessage-Input" }, "type": "array", "title": "Messages", "description": "Array of messages forming the conversation history" }, "web_search_options": { "$ref": "#/components/schemas/WebSearchOptions" }, "search_mode": { "anyOf": [ { "type": "string", "enum": [ "web", "academic", "sec" ] }, { "type": "null" } ], "title": "Search Mode", "description": "Source of search results (web, academic, or sec)" }, "return_images": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Images", "description": "When true, include image results in the response" }, "return_related_questions": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Related Questions", "description": "When true, generates suggested follow-up queries based on the search results" }, "enable_search_classifier": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enable Search Classifier", "description": "When true, uses a classifier to determine if web search is needed for the query" }, "disable_search": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Disable Search", "description": "When true, disables all web search capabilities. The model responds based solely on its training data" }, "search_domain_filter": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Search Domain Filter", "description": "Limit search results to specific domains (e.g. github.com, wikipedia.org)" }, "search_language_filter": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Search Language Filter", "description": "Filter results by language using ISO 639-1 codes (e.g. en, fr, de)" }, "search_recency_filter": { "anyOf": [ { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ] }, { "type": "null" } ], "title": "Search Recency Filter", "description": "Filter by publication recency (hour, day, week, month, or year)" }, "search_after_date_filter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search After Date Filter", "description": "Return results published after this date (MM/DD/YYYY)" }, "search_before_date_filter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Before Date Filter", "description": "Return results published before this date (MM/DD/YYYY)" }, "last_updated_before_filter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Updated Before Filter", "description": "Return results last updated before this date (MM/DD/YYYY)" }, "last_updated_after_filter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Updated After Filter", "description": "Return results last updated after this date (MM/DD/YYYY)" }, "image_format_filter": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Image Format Filter", "description": "Filter image results by format (e.g. png, jpg)" }, "image_domain_filter": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Image Domain Filter", "description": "Limit image results to specific domains" }, "stream_mode": { "type": "string", "enum": [ "full", "concise" ], "title": "Stream Mode", "description": "Controls the format of streaming events. 'full' suppresses reasoning events and includes metadata inline; 'concise' emits reasoning events separately", "default": "full" }, "reasoning_effort": { "anyOf": [ { "type": "string", "enum": [ "minimal", "low", "medium", "high" ] }, { "type": "null" } ], "title": "Reasoning Effort", "description": "Controls how much effort the model spends on reasoning" }, "language_preference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language Preference", "description": "ISO 639-1 language code for preferred response language" } }, "type": "object", "required": [ "model", "messages" ], "title": "ApiChatCompletionsRequest" }, "ApiPublicSearchResult": { "description": "A single search result from the web", "properties": { "title": { "type": "string", "title": "Title", "description": "Title of the search result page" }, "url": { "type": "string", "title": "Url", "description": "URL of the search result page" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date", "description": "Publication date of the result" }, "last_updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Updated", "description": "Date the result was last updated" }, "snippet": { "type": "string", "title": "Snippet", "description": "Text snippet from the search result", "default": "" }, "source": { "type": "string", "enum": [ "web", "attachment" ], "title": "Source", "description": "Source type of the result (web or attachment)", "default": "web" } }, "type": "object", "required": [ "title", "url" ], "title": "ApiPublicSearchResult" }, "ImageResult": { "description": "A single image search result", "properties": { "image_url": { "type": "string", "description": "URL of the image" }, "origin_url": { "type": "string", "description": "Original URL where the image was found" }, "height": { "format": "int64", "type": "integer", "description": "Height of the image in pixels" }, "width": { "format": "int64", "type": "integer", "description": "Width of the image in pixels" }, "title": { "type": "string", "description": "Title or description of the image" } }, "required": [ "image_url", "origin_url", "height", "width" ], "type": "object", "title": "ImageResult" }, "ApiSearchPage": { "description": "A single page from search results", "properties": { "title": { "type": "string", "title": "Title", "description": "Title of the page" }, "url": { "type": "string", "title": "Url", "description": "URL of the page" }, "snippet": { "type": "string", "title": "Snippet", "description": "Content snippet extracted from the page" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date", "description": "Publication date of the page" }, "last_updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Updated", "description": "Date the page was last updated" } }, "type": "object", "required": [ "title", "url", "snippet" ], "title": "ApiSearchPage" }, "ApiSearchRequest": { "allOf": [ { "properties": { "country": { "description": "ISO 3166-1 alpha-2 country code", "maxLength": 2, "minLength": 2, "type": "string" }, "max_results": { "default": 10, "description": "Maximum number of results. Values above 20 require search_type=people. Supports up to 20 for web search and up to 50 for people search.", "maximum": 50, "minimum": 1, "type": "integer" }, "search_type": { "default": "web", "description": "Search type - \"web\" for general web search, \"fast\" for lower-latency, lower-cost web search, \"people\" for people search. max_results above 20 is only supported for people search.", "enum": [ "web", "fast", "people" ], "type": "string" }, "max_tokens": { "description": "Maximum total webpage content tokens to return across all search results", "maximum": 1000000, "minimum": 1, "type": "integer" }, "max_tokens_per_page": { "description": "Maximum webpage content tokens to extract from each result page", "maximum": 1000000, "minimum": 1, "type": "integer" }, "query": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ], "title": "Query", "description": "Search query (required)" }, "search_language_filter": { "description": "ISO 639-1 language codes (2-character max)", "items": { "maxLength": 2, "minLength": 2, "type": "string" }, "maxItems": 20, "type": "array" } }, "required": [ "query" ], "type": "object" }, { "$ref": "#/components/schemas/SearchDomainFilter" }, { "$ref": "#/components/schemas/DateFilters" } ], "type": "object", "title": "ApiSearchRequest" }, "ApiSearchResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/ApiSearchPage" }, "type": "array", "title": "Results" }, "id": { "type": "string", "title": "Id" }, "server_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Server Time" } }, "type": "object", "required": [ "results", "id" ], "title": "ApiSearchResponse" }, "AsyncApiChatCompletionsRequest": { "description": "Request body for creating an asynchronous chat completion", "properties": { "request": { "$ref": "#/components/schemas/ApiChatCompletionsRequest", "description": "The chat completion request to execute asynchronously" }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency Key", "description": "Unique key to prevent duplicate requests" } }, "type": "object", "required": [ "request" ], "title": "AsyncApiChatCompletionsRequest" }, "AsyncApiChatCompletionsResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the async request" }, "model": { "type": "string", "title": "Model", "description": "Model used for the request" }, "created_at": { "type": "integer", "title": "Created At", "description": "Unix timestamp when the request was created" }, "started_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Started At", "description": "Unix timestamp when processing started" }, "completed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completed At", "description": "Unix timestamp when processing completed" }, "response": { "anyOf": [ { "$ref": "#/components/schemas/CompletionResponse" }, { "type": "null" } ] }, "failed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Failed At", "description": "Unix timestamp when the request failed (if applicable)" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message", "description": "Error message if the request failed" }, "status": { "$ref": "#/components/schemas/AsyncProcessingStatus", "description": "Current processing status of the request" } }, "type": "object", "required": [ "id", "model", "created_at", "status" ], "title": "AsyncApiChatCompletionsResponse" }, "AsyncApiChatCompletionsResponseSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "integer", "title": "Created At" }, "started_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Started At" }, "completed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completed At" }, "failed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Failed At" }, "model": { "type": "string", "title": "Model" }, "status": { "$ref": "#/components/schemas/AsyncProcessingStatus" } }, "type": "object", "required": [ "id", "created_at", "model", "status" ], "title": "AsyncApiChatCompletionsResponseSummary" }, "AsyncProcessingStatus": { "type": "string", "enum": [ "CREATED", "IN_PROGRESS", "COMPLETED", "FAILED" ], "title": "AsyncProcessingStatus", "description": "Status enum for async processing." }, "ChatMessage-Input": { "properties": { "role": { "$ref": "#/components/schemas/ChatMessageRole" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/ChatMessageContentTextChunk" }, { "$ref": "#/components/schemas/ChatMessageContentImageChunk" }, { "$ref": "#/components/schemas/ChatMessageContentFileChunk" }, { "$ref": "#/components/schemas/ChatMessageContentPDFChunk" }, { "$ref": "#/components/schemas/ChatMessageContentVideoChunk" } ] }, "type": "array", "title": "Structured Content" }, { "type": "null" } ], "title": "Content" } }, "type": "object", "required": [ "role", "content" ], "title": "ChatMessage" }, "ChatMessage-Output": { "properties": { "role": { "$ref": "#/components/schemas/ChatMessageRole" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/ChatMessageContentTextChunk" }, { "$ref": "#/components/schemas/ChatMessageContentImageChunk" }, { "$ref": "#/components/schemas/ChatMessageContentFileChunk" }, { "$ref": "#/components/schemas/ChatMessageContentPDFChunk" }, { "$ref": "#/components/schemas/ChatMessageContentVideoChunk" } ] }, "type": "array", "title": "Structured Content" }, { "type": "null" } ], "title": "Content" } }, "type": "object", "required": [ "role", "content" ], "title": "ChatMessage" }, "ChatMessageContentFileChunk": { "properties": { "type": { "type": "string", "const": "file_url", "title": "Type" }, "file_url": { "anyOf": [ { "$ref": "#/components/schemas/URL" }, { "type": "string" } ], "title": "File Url" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name" } }, "type": "object", "required": [ "type", "file_url" ], "title": "ChatMessageContentFileChunk" }, "ChatMessageContentImageChunk": { "properties": { "type": { "type": "string", "const": "image_url", "title": "Type" }, "image_url": { "anyOf": [ { "$ref": "#/components/schemas/URL" }, { "type": "string" } ], "title": "Image Url" } }, "type": "object", "required": [ "type", "image_url" ], "title": "ChatMessageContentImageChunk" }, "ChatMessageContentPDFChunk": { "properties": { "type": { "type": "string", "const": "pdf_url", "title": "Type" }, "pdf_url": { "anyOf": [ { "$ref": "#/components/schemas/URL" }, { "type": "string" } ], "title": "Pdf Url" } }, "type": "object", "required": [ "type", "pdf_url" ], "title": "ChatMessageContentPDFChunk" }, "ChatMessageContentTextChunk": { "properties": { "type": { "type": "string", "const": "text", "title": "Type" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "type", "text" ], "title": "ChatMessageContentTextChunk" }, "ChatMessageContentVideoChunk": { "properties": { "type": { "type": "string", "const": "video_url", "title": "Type" }, "video_url": { "anyOf": [ { "$ref": "#/components/schemas/VideoURL" }, { "type": "string" } ], "title": "Video Url" } }, "type": "object", "required": [ "type", "video_url" ], "title": "ChatMessageContentVideoChunk" }, "ChatMessageRole": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ], "title": "ChatMessageRole", "description": "Chat roles enum" }, "Choice": { "description": "A single completion choice", "properties": { "index": { "type": "integer", "title": "Index", "description": "Index of the choice in the array" }, "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length" ] }, { "type": "null" } ], "title": "Finish Reason", "description": "Reason generation stopped (stop or length)" }, "message": { "$ref": "#/components/schemas/ChatMessage-Output", "description": "Complete message (non-streaming)" }, "delta": { "$ref": "#/components/schemas/ChatMessage-Output", "description": "Incremental message delta (streaming)" } }, "type": "object", "required": [ "index", "message", "delta" ], "title": "Choice" }, "CompletionResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the completion" }, "model": { "type": "string", "title": "Model", "description": "Model used for generation" }, "created": { "type": "integer", "title": "Created", "description": "Unix timestamp when the completion was created" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/UsageInfo" }, { "type": "null" } ] }, "object": { "type": "string", "title": "Object", "description": "Object type identifier", "default": "chat.completion" }, "choices": { "items": { "$ref": "#/components/schemas/Choice" }, "type": "array", "title": "Choices", "description": "Array of completion choices" }, "citations": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Citations", "description": "URLs of sources used to generate the response" }, "search_results": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ApiPublicSearchResult" }, "type": "array" }, { "type": "null" } ], "title": "Search Results", "description": "Search results used for context in the response" }, "images": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ImageResult" }, "type": "array" }, { "type": "null" } ], "title": "Images", "description": "Array of images returned when return_images is true" }, "related_questions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Related Questions", "description": "Array of related questions returned when return_related_questions is true" } }, "type": "object", "required": [ "id", "model", "created", "choices" ], "title": "CompletionResponse" }, "CompletionResponseStatus": { "description": "Status of a streaming completion response", "type": "string", "enum": [ "PENDING", "COMPLETED" ], "title": "CompletionResponseStatus" }, "CompletionResponseType": { "description": "Type of a streaming completion response chunk", "type": "string", "enum": [ "message", "info", "end_of_stream" ], "title": "CompletionResponseType" }, "Cost": { "description": "Cost breakdown for a chat completion request", "properties": { "input_tokens_cost": { "type": "number", "title": "Input Tokens Cost", "description": "Cost for input tokens in USD" }, "output_tokens_cost": { "type": "number", "title": "Output Tokens Cost", "description": "Cost for output tokens in USD" }, "reasoning_tokens_cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Reasoning Tokens Cost", "description": "Cost for reasoning tokens in USD" }, "request_cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Request Cost", "description": "Cost for web search requests in USD (includes pro search cost if applicable)" }, "citation_tokens_cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Citation Tokens Cost", "description": "Cost for citation tokens in USD" }, "search_queries_cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Search Queries Cost", "description": "Cost for search queries in USD" }, "total_cost": { "type": "number", "title": "Total Cost", "description": "Total cost for the request in USD" } }, "type": "object", "required": [ "input_tokens_cost", "output_tokens_cost", "total_cost" ], "title": "Cost" }, "Currency": { "description": "Currency code for cost values", "enum": [ "USD" ], "type": "string" }, "ExecutePythonStepDetails": { "properties": { "code": { "type": "string", "title": "Code" }, "result": { "type": "string", "title": "Result" } }, "type": "object", "required": [ "code", "result" ], "title": "ExecutePythonStepDetails", "description": "Code generation step details wrapper class" }, "FetchUrlContentStepDetails": { "properties": { "contents": { "items": { "$ref": "#/components/schemas/ApiPublicSearchResult" }, "type": "array", "title": "Contents" } }, "type": "object", "required": [ "contents" ], "title": "FetchUrlContentStepDetails", "description": "Fetch url content step details wrapper class" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "JSONSchema": { "properties": { "schema": { "additionalProperties": true, "type": "object", "title": "Schema" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "default": "schema" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "strict": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Strict", "default": true } }, "type": "object", "required": [ "schema" ], "title": "JSONSchema" }, "ListAsyncApiChatCompletionsResponse": { "properties": { "next_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Token" }, "requests": { "items": { "$ref": "#/components/schemas/AsyncApiChatCompletionsResponseSummary" }, "type": "array", "title": "Requests" } }, "type": "object", "required": [ "requests" ], "title": "ListAsyncApiChatCompletionsResponse" }, "ReasoningStep-Output": { "properties": { "thought": { "type": "string", "title": "Thought" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "web_search": { "anyOf": [ { "$ref": "#/components/schemas/WebSearchStepDetails" }, { "type": "null" } ] }, "finance_search": { "anyOf": [ { "$ref": "#/components/schemas/FinanceSearchStepDetails" }, { "type": "null" } ] }, "people_search": { "anyOf": [ { "$ref": "#/components/schemas/PeopleSearchStepDetails" }, { "type": "null" } ] }, "fetch_url_content": { "anyOf": [ { "$ref": "#/components/schemas/FetchUrlContentStepDetails" }, { "type": "null" } ] }, "execute_python": { "anyOf": [ { "$ref": "#/components/schemas/ExecutePythonStepDetails" }, { "type": "null" } ] } }, "type": "object", "required": [ "thought" ], "title": "ReasoningStep", "description": "Reasoning step wrapper class" }, "ResponseFormatJSONSchema": { "description": "Constrains the model output to match the provided JSON schema.", "properties": { "type": { "type": "string", "const": "json_schema", "title": "Type", "description": "Must be `json_schema`." }, "json_schema": { "$ref": "#/components/schemas/JSONSchema" } }, "type": "object", "required": [ "type", "json_schema" ], "title": "ResponseFormatJSONSchema" }, "ResponseFormatText": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "description": "Must be `text`." } }, "type": "object", "required": [ "type" ], "title": "ResponseFormatText" }, "ToolCall": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "type": { "anyOf": [ { "type": "string", "const": "function" }, { "type": "null" } ], "title": "Type" }, "function": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallFunction" }, { "type": "null" } ] } }, "type": "object", "title": "ToolCall" }, "ToolCallFunction": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "arguments": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Arguments" } }, "type": "object", "title": "ToolCallFunction" }, "URL": { "properties": { "url": { "type": "string", "title": "Url" } }, "type": "object", "required": [ "url" ], "title": "URL" }, "UsageInfo": { "description": "Token usage and cost information for a request", "properties": { "prompt_tokens": { "type": "integer", "title": "Prompt Tokens", "description": "Number of tokens in the prompt/input" }, "completion_tokens": { "type": "integer", "title": "Completion Tokens", "description": "Number of tokens in the completion/output" }, "total_tokens": { "type": "integer", "title": "Total Tokens", "description": "Total tokens used (prompt + completion)" }, "search_context_size": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Context Size", "description": "Size of search context used" }, "citation_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Citation Tokens", "description": "Number of tokens used for citations" }, "num_search_queries": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Search Queries", "description": "Number of search queries executed" }, "reasoning_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Reasoning Tokens", "description": "Number of tokens used for reasoning" }, "cost": { "$ref": "#/components/schemas/Cost", "description": "Cost breakdown for the request" } }, "type": "object", "required": [ "prompt_tokens", "completion_tokens", "total_tokens", "cost" ], "title": "UsageInfo" }, "UserLocation": { "description": "User's geographic location for search personalization", "properties": { "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Latitude", "description": "Latitude coordinate" }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Longitude", "description": "Longitude coordinate" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "ISO 3166-1 alpha-2 country code" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City", "description": "City name" }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region", "description": "State or region name" } }, "type": "object", "title": "UserLocation" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VideoURL": { "properties": { "url": { "type": "string", "title": "Url" }, "frame_interval": { "anyOf": [ { "type": "string" }, { "type": "integer" } ], "title": "Frame Interval", "default": 25 } }, "type": "object", "required": [ "url" ], "title": "VideoURL" }, "WebSearchOptions": { "description": "Configuration options for web search behavior", "properties": { "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ], "title": "Search Context Size", "description": "Amount of search context to include (low, medium, or high)", "default": "low" }, "search_type": { "anyOf": [ { "type": "string", "enum": [ "fast", "pro", "auto" ] }, { "type": "null" } ], "title": "Search Type", "description": "Search type (fast for speed, pro for quality, auto to let the model decide)" }, "user_location": { "anyOf": [ { "$ref": "#/components/schemas/UserLocation" }, { "type": "null" } ] }, "image_results_enhanced_relevance": { "type": "boolean", "title": "Image Results Enhanced Relevance", "description": "When true, applies enhanced relevance filtering to image results", "default": false } }, "type": "object", "title": "WebSearchOptions" }, "ResponsesRequest": { "properties": { "input": { "$ref": "#/components/schemas/Input" }, "background": { "description": "Run the response asynchronously. With `stream: false`, the request returns immediately with `status: \"queued\"`; poll `GET /v1/responses/{id}` until the response reaches a terminal status. Background runs are durable, so you can also stream them and reconnect after a drop.", "type": "boolean" }, "instructions": { "description": "System instructions for the model", "type": "string" }, "language_preference": { "description": "ISO 639-1 language code for response language", "type": "string" }, "max_output_tokens": { "description": "Maximum tokens to generate. This is a shared optional Agent API request parameter, but it is required when using anthropic/* models. If omitted for an Anthropic model, the API returns HTTP 400 with: validation failed: max_output_tokens is required when using Anthropic models.", "format": "int32", "minimum": 1, "type": "integer" }, "max_steps": { "description": "Maximum number of research loop steps.\nIf provided, overrides the preset's max_steps value. For requests that specify model or models without a preset, the default is 1.\nSet max_steps to at least 3 when using finance_search with a direct model so the agent has enough steps to initialize and run the tool.\nMust be >= 1 if specified. Maximum allowed is 100.\n", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "model": { "description": "Model ID in provider/model format (e.g., \"openai/gpt-5.6-terra\", \"anthropic/claude-sonnet-4-6\").\nIf models is also provided, models takes precedence.\nRequired if neither models nor preset is provided.\n", "type": "string" }, "models": { "description": "Model fallback chain. Each model is in provider/model format.\nModels are tried in order until one succeeds.\nMax 5 models allowed. If set, takes precedence over single model field.\nThe response.model will reflect the model that actually succeeded.\n", "items": { "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array" }, "preset": { "description": "Preset configuration name (e.g., \"fast\", \"low\", \"medium\", \"high\", \"xhigh\").\nPre-configured model with system prompt and search parameters.\nRequired if model is not provided.\n", "type": "string" }, "profile": { "allOf": [ { "$ref": "#/components/schemas/ProfileReference" } ], "description": "Saved, versioned configuration to run with. The version is resolved when the request is admitted. Cannot be combined with preset." }, "previous_response_id": { "description": "OpenAI-compatible previous response id for multi-turn response chains. When set, the new response continues from the completed prior response's saved state. The prior response must belong to the same account and have completed.", "type": "string" }, "reasoning": { "$ref": "#/components/schemas/ReasoningConfig" }, "response_format": { "$ref": "#/components/schemas/ResponseFormat" }, "store": { "description": "OpenAI-compatible storage toggle. When false, the response is hidden from later retrieve calls, and the echoed response reports `store: false`. It can still be used as a `previous_response_id` continuation source.", "type": "boolean" }, "stream": { "description": "If true, returns SSE stream instead of JSON", "type": "boolean" }, "tools": { "description": "Tools available to the model", "items": { "$ref": "#/components/schemas/Tool" }, "type": "array" }, "tool_choice": { "allOf": [ { "$ref": "#/components/schemas/ToolChoice" } ], "description": "Tool choice strategy. Use `{\"type\":\"image_search\"}` to force image search." }, "skills": { "type": "array", "description": "Built-in, request-scoped inline, and organization-owned custom skills available to the model. Skill metadata is disclosed to the model up front; full instructions are loaded on demand through the load_skill tool. Selecting any skill enables the sandbox tool for the request. Requests with skills run on the durable backend and skills are not echoed back on Response objects.", "maxItems": 16, "items": { "$ref": "#/components/schemas/Skill" } }, "temperature": { "description": "OpenAI-compatible sampling temperature forwarded to generation.", "format": "double", "maximum": 2, "minimum": 0, "type": "number" }, "top_p": { "description": "OpenAI-compatible nucleus sampling parameter forwarded to generation.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" } }, "required": [ "input" ], "type": "object", "title": "ResponsesRequest" }, "ResponseFile": { "type": "object", "description": "One file shared from a response's sandbox via `share_file`.", "required": [ "id", "object", "filename", "bytes", "created_at" ], "properties": { "id": { "type": "string", "description": "File identifier, used to download the file; distinct from the response id." }, "object": { "type": "string", "description": "Always `file`." }, "filename": { "type": "string", "description": "Name the sandbox gave the file." }, "bytes": { "type": "integer", "format": "int64", "description": "File size in bytes." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp when the file was created." } }, "title": "ResponseFile" }, "ResponseFileList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseFile" } } }, "title": "ResponseFileList" }, "ResponsesResponse": { "description": "Non-streaming response returned when stream is false", "properties": { "created_at": { "description": "Unix timestamp when the response was created", "format": "int64", "type": "integer" }, "error": { "$ref": "#/components/schemas/ErrorInfo", "description": "Error details if the response failed" }, "id": { "description": "Unique identifier for the response", "type": "string" }, "model": { "description": "Model used for generation", "type": "string" }, "object": { "$ref": "#/components/schemas/ResponsesObjectType", "description": "Object type identifier" }, "output": { "description": "Array of output items (messages, search results, tool calls)", "items": { "$ref": "#/components/schemas/OutputItem" }, "type": "array" }, "status": { "$ref": "#/components/schemas/Status", "description": "Status of the response" }, "usage": { "$ref": "#/components/schemas/ResponsesUsage", "description": "Token usage and cost information" } }, "required": [ "id", "object", "created_at", "status", "model", "output" ], "type": "object", "title": "ResponsesResponse" }, "ResponsesObjectType": { "description": "Object type in API responses", "enum": [ "response" ], "type": "string", "title": "ResponsesObjectType" }, "ResponsesUsage": { "description": "Token usage and cost information for a Responses API request", "properties": { "cost": { "$ref": "#/components/schemas/ResponsesCost", "description": "Cost breakdown for the request" }, "input_tokens": { "description": "Number of input tokens used", "format": "int64", "type": "integer" }, "input_tokens_details": { "properties": { "cache_creation_input_tokens": { "description": "Tokens used for cache creation", "format": "int64", "type": "integer" }, "cache_read_input_tokens": { "description": "Tokens read from cache", "format": "int64", "type": "integer" } }, "type": "object" }, "output_tokens": { "description": "Number of output tokens generated", "format": "int64", "type": "integer" }, "tool_calls_details": { "description": "Details about tool call invocations", "additionalProperties": { "$ref": "#/components/schemas/ToolCallDetails" }, "type": "object" }, "total_tokens": { "description": "Total tokens used (input + output)", "format": "int64", "type": "integer" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "type": "object", "title": "ResponsesUsage" }, "ResponsesCost": { "description": "Cost breakdown for a Responses API request", "properties": { "cache_creation_cost": { "description": "Cost for cache creation in USD", "format": "double", "type": "number" }, "cache_read_cost": { "description": "Cost for cache reads in USD", "format": "double", "type": "number" }, "currency": { "$ref": "#/components/schemas/Currency", "description": "Currency of the cost values" }, "input_cost": { "description": "Cost for input tokens in USD", "format": "double", "type": "number" }, "output_cost": { "description": "Cost for output tokens in USD", "format": "double", "type": "number" }, "tool_calls_cost": { "description": "Cost for tool call invocations in USD", "format": "double", "type": "number" }, "tool_calls_cost_details": { "description": "USD cost attributed to each reported tool by tool name.\nUnpriced reported tools are included with a value of 0.\n", "additionalProperties": { "format": "double", "type": "number" }, "type": "object" }, "total_cost": { "description": "Total cost for the request in USD", "format": "double", "type": "number" } }, "required": [ "currency", "input_cost", "output_cost", "total_cost" ], "type": "object", "title": "ResponsesCost" }, "Input": { "description": "Input content - either a string or array of input items", "oneOf": [ { "title": "StringInput", "type": "string" }, { "items": { "$ref": "#/components/schemas/InputItem" }, "title": "InputItemArray", "type": "array" } ], "title": "Input" }, "InputItem": { "discriminator": { "mapping": { "function_call": "#/components/schemas/FunctionCallInput", "function_call_output": "#/components/schemas/FunctionCallOutputInput", "message": "#/components/schemas/InputMessage" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/InputMessage" }, { "$ref": "#/components/schemas/FunctionCallOutputInput" }, { "$ref": "#/components/schemas/FunctionCallInput" } ], "title": "InputItem" }, "InputMessage": { "properties": { "content": { "$ref": "#/components/schemas/InputContent" }, "role": { "enum": [ "user", "assistant", "system", "developer" ], "type": "string" }, "type": { "enum": [ "message" ], "type": "string" } }, "required": [ "type", "role", "content" ], "type": "object", "title": "InputMessage" }, "InputContent": { "description": "Message content - either a string or array of content parts", "oneOf": [ { "title": "StringContent", "type": "string" }, { "items": { "$ref": "#/components/schemas/InputContentPart" }, "title": "ContentPartArray", "type": "array" } ], "title": "InputContent" }, "InputContentPart": { "properties": { "image_url": { "maxLength": 2048, "type": "string" }, "text": { "type": "string" }, "type": { "enum": [ "input_text", "input_image", "input_file" ], "type": "string" }, "filename": { "type": "string", "description": "Optional input_file basename, at most 255 UTF-8 bytes. Its extension must match the document type." }, "file_data": { "type": "string", "description": "For input_file, standard base64 or a base64 data URI. Exactly one of file_data and file_url is required. Native Agent input allows at most 30 document parts and 50 MiB combined decoded inline bytes, including inherited documents. Provider limits also apply. Browser tools are unavailable with document inputs or document continuations." }, "file_url": { "type": "string", "description": "For input_file, public HTTPS URL fetched by the provider. Exactly one of file_data and file_url is required. Defaults to PDF unless filename supplies another supported extension; the remote content must match. No file_id support. Browser tools are unavailable with document inputs or document continuations." } }, "required": [ "type" ], "type": "object", "title": "InputContentPart" }, "OutputItem": { "discriminator": { "mapping": { "fetch_url_results": "#/components/schemas/FetchUrlResultsOutputItem", "finance_results": "#/components/schemas/FinanceResultsOutputItem", "function_call": "#/components/schemas/FunctionCallOutputItem", "message": "#/components/schemas/MessageOutputItem", "people_search_results": "#/components/schemas/PeopleSearchResultsOutputItem", "sandbox_results": "#/components/schemas/SandboxResultsOutputItem", "search_results": "#/components/schemas/SearchResultsOutputItem", "image_search_results": "#/components/schemas/ImageSearchResultsOutputItem", "mcp_list_tools": "#/components/schemas/McpListToolsOutputItem", "mcp_call": "#/components/schemas/McpCallOutputItem", "tool_search_output": "#/components/schemas/ToolSearchOutputItem" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/MessageOutputItem" }, { "$ref": "#/components/schemas/SearchResultsOutputItem" }, { "$ref": "#/components/schemas/ImageSearchResultsOutputItem" }, { "$ref": "#/components/schemas/FetchUrlResultsOutputItem" }, { "$ref": "#/components/schemas/FinanceResultsOutputItem" }, { "$ref": "#/components/schemas/PeopleSearchResultsOutputItem" }, { "$ref": "#/components/schemas/FunctionCallOutputItem" }, { "$ref": "#/components/schemas/SandboxResultsOutputItem" }, { "$ref": "#/components/schemas/McpListToolsOutputItem" }, { "$ref": "#/components/schemas/McpCallOutputItem" }, { "$ref": "#/components/schemas/ToolSearchOutputItem" } ], "title": "OutputItem" }, "MessageOutputItem": { "properties": { "content": { "items": { "$ref": "#/components/schemas/ContentPart" }, "type": "array" }, "id": { "type": "string" }, "role": { "$ref": "#/components/schemas/RoleType" }, "status": { "$ref": "#/components/schemas/Status" }, "type": { "enum": [ "message" ], "type": "string" } }, "required": [ "type", "id", "status", "role", "content" ], "type": "object", "title": "MessageOutputItem" }, "SearchResultsOutputItem": { "properties": { "queries": { "items": { "type": "string" }, "type": "array" }, "results": { "items": { "$ref": "#/components/schemas/SearchResult" }, "type": "array" }, "type": { "enum": [ "search_results" ], "type": "string" } }, "required": [ "type", "results" ], "type": "object", "title": "SearchResultsOutputItem" }, "ImageSearchResultsOutputItem": { "properties": { "error": { "description": "Present when image search failed. The value is image_search_failed.", "type": "string" }, "queries": { "items": { "type": "string" }, "type": "array" }, "results": { "items": { "$ref": "#/components/schemas/ImageResult" }, "type": "array" }, "type": { "enum": [ "image_search_results" ], "type": "string" } }, "required": [ "type", "results" ], "type": "object", "title": "ImageSearchResultsOutputItem" }, "FetchUrlResultsOutputItem": { "properties": { "contents": { "items": { "$ref": "#/components/schemas/UrlContent" }, "type": "array" }, "type": { "enum": [ "fetch_url_results" ], "type": "string" } }, "required": [ "type", "contents" ], "type": "object", "title": "FetchUrlResultsOutputItem" }, "SandboxResultsOutputItem": { "description": "Result of a sandbox tool invocation. Contains the executed code and its output.", "properties": { "type": { "enum": [ "sandbox_results" ], "type": "string" }, "code": { "description": "The code that was executed inside the sandbox.", "type": "string" }, "stdout": { "description": "Standard output captured from the sandbox execution.", "type": "string" }, "stderr": { "description": "Standard error captured from the sandbox execution.", "type": "string" }, "exit_code": { "description": "Process exit code. Non-zero indicates a runtime error.", "format": "int32", "type": "integer" }, "duration_ms": { "description": "Wall-clock duration of the sandbox execution, in milliseconds.", "format": "int64", "type": "integer" }, "status": { "description": "Execution status. One of `completed`, `timed_out`, `failed`.", "enum": [ "completed", "timed_out", "failed" ], "type": "string" } }, "required": [ "type", "status" ], "type": "object", "title": "SandboxResultsOutputItem" }, "FinanceResultsOutputItem": { "description": "Intermediate output item emitted when the finance_search tool runs. One item is emitted per tool invocation; the requested categories and tickers are echoed at the envelope level alongside the per-result entries.", "properties": { "categories": { "description": "Finance categories the tool was asked to retrieve for this invocation (for example, \"quote\").", "items": { "type": "string" }, "type": "array" }, "results": { "description": "Structured finance results returned for the invocation.", "items": { "$ref": "#/components/schemas/FinanceResult" }, "type": "array" }, "tickers": { "description": "Ticker symbols the tool was asked to retrieve for this invocation.", "items": { "type": "string" }, "type": "array" }, "type": { "enum": [ "finance_results" ], "type": "string" } }, "required": [ "type", "results" ], "type": "object", "title": "FinanceResultsOutputItem" }, "PeopleSearchResultsOutputItem": { "description": "Intermediate output item emitted when the people_search tool runs. Mirrors the shape of search_results: the agent's generated queries plus a list of per-person result entries.", "properties": { "queries": { "description": "Search queries the agent generated for this people_search invocation.", "items": { "type": "string" }, "type": "array" }, "results": { "description": "Per-person result entries. Shape matches SearchResult (id, url, title, snippet, source, last_updated).", "items": { "$ref": "#/components/schemas/SearchResult" }, "type": "array" }, "type": { "enum": [ "people_search_results" ], "type": "string" } }, "required": [ "type", "results" ], "type": "object", "title": "PeopleSearchResultsOutputItem" }, "ContentPart": { "properties": { "annotations": { "items": { "$ref": "#/components/schemas/Annotation" }, "type": "array" }, "text": { "type": "string" }, "type": { "$ref": "#/components/schemas/ContentPartType" } }, "required": [ "type", "text" ], "type": "object", "title": "ContentPart" }, "ContentPartType": { "description": "Type of a content part", "enum": [ "output_text" ], "type": "string", "title": "ContentPartType" }, "Annotation": { "description": "Text annotation (URL citation)", "properties": { "end_index": { "description": "End character index of the annotated text", "format": "int32", "type": "integer" }, "start_index": { "description": "Start character index of the annotated text", "format": "int32", "type": "integer" }, "title": { "description": "Title of the cited source", "type": "string" }, "type": { "description": "Annotation type (url_citation)", "type": "string" }, "url": { "description": "URL of the cited source", "type": "string" } }, "type": "object", "title": "Annotation" }, "SearchResult": { "description": "A single search result used in LLM responses", "properties": { "date": { "description": "Publication date of the result", "type": "string" }, "id": { "description": "Unique numeric identifier for the result", "format": "int64", "type": "integer" }, "last_updated": { "description": "Date the result was last updated", "type": "string" }, "snippet": { "description": "Text snippet from the search result", "type": "string" }, "source": { "$ref": "#/components/schemas/SearchSource", "description": "Source type of the result" }, "title": { "description": "Title of the search result page", "type": "string" }, "url": { "description": "URL of the search result page", "type": "string" } }, "required": [ "id", "url", "title", "snippet" ], "type": "object", "title": "SearchResult" }, "SearchSource": { "description": "Source of search results", "enum": [ "web" ], "type": "string", "title": "SearchSource" }, "FinanceResult": { "description": "A single structured finance result returned by the finance_search tool.", "properties": { "category": { "description": "Finance category this result belongs to (for example, \"quote\").", "type": "string" }, "content": { "description": "Structured content for the result, typically a markdown-formatted table or snippet.", "type": "string" }, "sources": { "description": "Source URLs backing the structured content.", "items": { "type": "string" }, "type": "array" }, "tickers": { "description": "Ticker symbols this result pertains to.", "items": { "type": "string" }, "type": "array" } }, "required": [ "category", "content" ], "type": "object", "title": "FinanceResult" }, "UrlContent": { "description": "Content fetched from a URL", "properties": { "snippet": { "description": "The fetched content snippet", "type": "string" }, "title": { "description": "The title of the page", "type": "string" }, "url": { "description": "The URL from which content was fetched", "type": "string" } }, "required": [ "url", "title", "snippet" ], "type": "object", "title": "UrlContent" }, "RoleType": { "description": "Role in a message", "enum": [ "assistant" ], "type": "string", "title": "RoleType" }, "Status": { "description": "Status of a response or output item", "enum": [ "completed", "failed", "incomplete", "in_progress", "queued", "cancelled" ], "type": "string", "title": "Status" }, "ErrorInfo": { "description": "Error information returned when a request fails", "properties": { "code": { "description": "Error code", "type": "string" }, "message": { "description": "Human-readable error message", "type": "string" }, "type": { "description": "Error type category", "type": "string" } }, "required": [ "message" ], "type": "object", "title": "ErrorInfo" }, "ProfileReference": { "additionalProperties": false, "properties": { "id": { "maxLength": 128, "minLength": 1, "type": "string" }, "type": { "enum": [ "custom" ], "type": "string" }, "version": { "description": "Version to bind to, or \"latest\". Omitted means \"latest\".", "type": "string" } }, "required": [ "type", "id" ], "type": "object", "title": "ProfileReference" }, "ReasoningConfig": { "properties": { "effort": { "description": "How much effort the model should spend on reasoning", "enum": [ "minimal", "low", "medium", "high", "xhigh", "max" ], "type": "string" } }, "type": "object", "title": "ReasoningConfig" }, "ResponseFormat": { "description": "Specifies the desired output format for the model response", "properties": { "json_schema": { "$ref": "#/components/schemas/JSONSchemaFormat" }, "type": { "description": "The type of response format", "enum": [ "json_schema" ], "type": "string" } }, "required": [ "type" ], "type": "object", "title": "ResponseFormat" }, "JSONSchemaFormat": { "description": "Defines a JSON schema for structured output validation", "properties": { "description": { "description": "Optional description of the schema", "type": "string" }, "name": { "description": "Name of the schema (1-64 alphanumeric chars)", "maxLength": 64, "minLength": 1, "type": "string" }, "schema": { "additionalProperties": true, "description": "The JSON schema object", "type": "object" }, "strict": { "description": "Whether to enforce strict schema validation", "type": "boolean" } }, "required": [ "name", "schema" ], "type": "object", "title": "JSONSchemaFormat" }, "FunctionCallInput": { "properties": { "arguments": { "description": "Function arguments (JSON string)", "type": "string" }, "call_id": { "description": "The call_id that correlates with function_call_output", "type": "string" }, "name": { "description": "The function name", "type": "string" }, "thought_signature": { "description": "Base64-encoded signature for thinking models", "type": "string" }, "type": { "enum": [ "function_call" ], "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "type": "object", "title": "FunctionCallInput" }, "FunctionCallOutputInput": { "additionalProperties": false, "properties": { "id": { "description": "Replay metadata populated when this item was returned by the API.", "nullable": true, "type": "string" }, "call_id": { "description": "The call_id from function_call output", "type": "string" }, "name": { "description": "Function name (required by some providers)", "type": "string" }, "output": { "description": "Function result as a JSON string or an array of input_text and input_image content parts.", "oneOf": [ { "title": "StringOutput", "type": "string" }, { "items": { "discriminator": { "mapping": { "input_image": "#/components/schemas/FunctionCallOutputImagePart", "input_text": "#/components/schemas/FunctionCallOutputTextPart" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/FunctionCallOutputTextPart" }, { "$ref": "#/components/schemas/FunctionCallOutputImagePart" } ] }, "title": "OutputPartArray", "type": "array" } ] }, "status": { "description": "Replay metadata populated when this item was returned by the API.", "enum": [ "in_progress", "completed", "incomplete" ], "nullable": true, "type": "string" }, "thought_signature": { "description": "Base64-encoded signature from function_call", "type": "string" }, "type": { "enum": [ "function_call_output" ], "type": "string" } }, "required": [ "type", "call_id", "output" ], "type": "object", "title": "FunctionCallOutputInput" }, "FunctionCallOutputTextPart": { "additionalProperties": false, "properties": { "text": { "type": "string" }, "type": { "enum": [ "input_text" ], "type": "string" } }, "required": [ "type", "text" ], "type": "object", "title": "FunctionCallOutputTextPart" }, "FunctionCallOutputImagePart": { "additionalProperties": false, "properties": { "detail": { "description": "Accepted for OpenAI replay compatibility; native tool-result forwarding ignores this hint.", "enum": [ "low", "high", "auto" ], "nullable": true, "type": "string" }, "image_url": { "description": "A fully qualified HTTP(S) URL or base64 image data URI.", "type": "string" }, "type": { "enum": [ "input_image" ], "type": "string" } }, "required": [ "type", "image_url" ], "type": "object", "title": "FunctionCallOutputImagePart" }, "FunctionCallOutputItem": { "properties": { "arguments": { "description": "JSON string of arguments", "type": "string" }, "call_id": { "description": "Correlates with function_call_output input", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" }, "thought_signature": { "description": "Base64-encoded opaque signature for thinking models", "type": "string" }, "type": { "enum": [ "function_call" ], "type": "string" } }, "required": [ "type", "id", "status", "name", "call_id", "arguments" ], "type": "object", "title": "FunctionCallOutputItem" }, "FunctionTool": { "properties": { "description": { "description": "A description of what the function does", "type": "string" }, "name": { "description": "The name of the function", "type": "string" }, "parameters": { "additionalProperties": true, "description": "JSON Schema defining the function's parameters", "type": "object" }, "strict": { "description": "Whether to enable strict schema validation", "type": "boolean" }, "type": { "enum": [ "function" ], "type": "string" } }, "required": [ "type", "name" ], "type": "object", "title": "FunctionTool" }, "Tool": { "discriminator": { "mapping": { "fetch_url": "#/components/schemas/FetchUrlTool", "finance_search": "#/components/schemas/FinanceSearchTool", "function": "#/components/schemas/FunctionTool", "people_search": "#/components/schemas/PeopleSearchTool", "sandbox": "#/components/schemas/SandboxTool", "web_search": "#/components/schemas/WebSearchTool", "image_search": "#/components/schemas/ImageSearchTool", "mcp": "#/components/schemas/McpTool", "connector": "#/components/schemas/ConnectorTool" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/WebSearchTool" }, { "$ref": "#/components/schemas/ImageSearchTool" }, { "$ref": "#/components/schemas/FinanceSearchTool" }, { "$ref": "#/components/schemas/PeopleSearchTool" }, { "$ref": "#/components/schemas/FetchUrlTool" }, { "$ref": "#/components/schemas/FunctionTool" }, { "$ref": "#/components/schemas/SandboxTool" }, { "$ref": "#/components/schemas/McpTool" }, { "$ref": "#/components/schemas/ConnectorTool" } ], "title": "Tool" }, "Skill": { "title": "Skill", "oneOf": [ { "$ref": "#/components/schemas/BuiltinSkill" }, { "$ref": "#/components/schemas/InlineSkill" }, { "$ref": "#/components/schemas/CustomSkill" } ], "discriminator": { "propertyName": "type", "mapping": { "builtin": "#/components/schemas/BuiltinSkill", "inline": "#/components/schemas/InlineSkill", "custom": "#/components/schemas/CustomSkill" } } }, "BuiltinSkill": { "title": "BuiltinSkill", "type": "object", "additionalProperties": false, "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "builtin" ] }, "name": { "type": "string", "enum": [ "office", "office/docx", "office/pdf", "office/pptx", "office/xlsx" ], "description": "Built-in skill to make available to the model. office is the full Office bundle (enables all four leaves). office/docx, office/pdf, office/pptx, office/xlsx each create polished documents of that type from scratch, with structural validation and visual QA." } } }, "InlineSkill": { "title": "InlineSkill", "type": "object", "additionalProperties": false, "required": [ "type", "name", "description", "instructions" ], "properties": { "type": { "type": "string", "enum": [ "inline" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Request-scoped lowercase ASCII name separated by single hyphens." }, "description": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Short discovery description, limited to 1,024 UTF-8 bytes." }, "instructions": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "Instructions returned by load_skill, limited to 65,536 UTF-8 bytes per skill and 262,144 bytes across the request." } } }, "CustomSkill": { "title": "CustomSkill", "type": "object", "additionalProperties": false, "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Identifier of an organization-owned skill stored in Perplexity, in the form skill_." }, "version": { "type": "string", "description": "Revision to load, or \"latest\". Omitted means \"latest\"." } } }, "WebSearchTool": { "description": "Web search tool configuration for the Responses API", "properties": { "filters": { "$ref": "#/components/schemas/WebSearchFilters", "description": "Domain and date filters for search results" }, "search_type": { "description": "Search type for this tool. `web` uses standard web search. `fast` uses the lower-latency Fast Search path, billed at $1.00 per 1,000 invocations plus model tokens. When omitted, inherits the preset's search type if configured; otherwise uses `web`.", "enum": [ "web", "fast" ], "type": "string" }, "max_results": { "description": "Upper bound on the number of search results collected per call. Must be between 1 and 50; values outside that range are rejected with a 400 error.", "format": "int32", "type": "integer", "minimum": 1, "maximum": 50 }, "max_tokens": { "description": "Maximum total tokens for search context", "format": "int32", "type": "integer" }, "max_tokens_per_page": { "description": "Maximum tokens to extract per search result page", "format": "int32", "type": "integer" }, "type": { "description": "Tool type identifier", "enum": [ "web_search" ], "type": "string" }, "user_location": { "$ref": "#/components/schemas/ToolUserLocation", "description": "User's location for search personalization" } }, "required": [ "type" ], "type": "object", "title": "WebSearchTool" }, "ToolChoice": { "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "additionalProperties": true } ], "title": "ToolChoice" }, "ImageSearchFilters": { "properties": { "domain_filter": { "items": { "type": "string" }, "maxItems": 10, "type": "array" }, "format_filter": { "items": { "type": "string", "enum": [ "bmp", "gif", "jpeg", "png", "webp", "svg" ] }, "maxItems": 10, "type": "array" }, "safe_search": { "default": true, "type": "boolean" } }, "type": "object", "title": "ImageSearchFilters" }, "ImageSearchTool": { "properties": { "type": { "enum": [ "image_search" ], "type": "string" }, "max_results": { "format": "int32", "minimum": 1, "maximum": 30, "default": 5, "type": "integer" }, "filters": { "$ref": "#/components/schemas/ImageSearchFilters" } }, "required": [ "type" ], "type": "object", "title": "ImageSearchTool" }, "FinanceSearchTool": { "description": "Finance search tool configuration for the Agent API", "properties": { "type": { "description": "Tool type identifier", "enum": [ "finance_search" ], "type": "string" } }, "required": [ "type" ], "type": "object", "title": "FinanceSearchTool" }, "FetchUrlTool": { "properties": { "max_urls": { "description": "Maximum number of URLs to fetch per tool call", "format": "int32", "maximum": 10, "minimum": 1, "type": "integer" }, "type": { "enum": [ "fetch_url" ], "type": "string" } }, "required": [ "type" ], "type": "object", "title": "FetchUrlTool" }, "PeopleSearchTool": { "description": "People search tool configuration for the Agent API", "properties": { "type": { "description": "Tool type identifier", "enum": [ "people_search" ], "type": "string" } }, "required": [ "type" ], "type": "object", "title": "PeopleSearchTool" }, "SandboxTool": { "description": "Sandbox tool configuration for the Responses API. Executes code in an isolated container during an Agent API request.", "properties": { "type": { "description": "Tool type identifier", "enum": [ "sandbox" ], "type": "string" } }, "required": [ "type" ], "type": "object", "title": "SandboxTool" }, "WebSearchFilters": { "allOf": [ { "$ref": "#/components/schemas/SearchDomainFilter" }, { "$ref": "#/components/schemas/DateFilters" } ], "title": "WebSearchFilters" }, "SearchDomainFilter": { "properties": { "search_domain_filter": { "description": "Limit search results to specific domains (max 20)", "items": { "maxLength": 253, "type": "string" }, "maxItems": 20, "type": "array" } }, "type": "object", "title": "SearchDomainFilter" }, "DateFilters": { "properties": { "last_updated_after_filter": { "$ref": "#/components/schemas/Date", "description": "Return results updated after this date (MM/DD/YYYY)" }, "last_updated_before_filter": { "$ref": "#/components/schemas/Date", "description": "Return results updated before this date (MM/DD/YYYY)" }, "search_after_date_filter": { "$ref": "#/components/schemas/Date", "description": "Return results published after this date (MM/DD/YYYY)" }, "search_before_date_filter": { "$ref": "#/components/schemas/Date", "description": "Return results published before this date (MM/DD/YYYY)" }, "search_recency_filter": { "$ref": "#/components/schemas/SearchRecencyFilter", "description": "Filter by publication recency (hour/day/week/month/year)" } }, "type": "object", "title": "DateFilters" }, "Date": { "description": "Input: MM/DD/YYYY, Output: YYYY-MM-DD", "type": "string", "title": "Date" }, "SearchRecencyFilter": { "description": "Time-based recency filter for search results", "enum": [ "hour", "day", "week", "month", "year" ], "type": "string", "title": "SearchRecencyFilter" }, "ToolUserLocation": { "description": "User's geographic location for search personalization", "properties": { "city": { "description": "City name", "type": "string" }, "country": { "description": "ISO 3166-1 alpha-2 country code", "type": "string" }, "latitude": { "description": "Latitude coordinate", "format": "double", "type": "number" }, "longitude": { "description": "Longitude coordinate", "format": "double", "type": "number" }, "region": { "description": "State or region name", "type": "string" } }, "type": "object", "title": "ToolUserLocation" }, "ToolCallDetails": { "description": "Details about a tool call invocation", "properties": { "invocation": { "description": "Number of times this tool was invoked", "format": "int64", "type": "integer" }, "cost_usd": { "description": "Accumulated customer charge in USD for this tool when the API can attribute one directly.", "format": "double", "type": "number" }, "token_usage": { "description": "Model token usage for tools backed by internal LLM calls. Sandbox SDK usage is aggregated by model; advisor entries represent individual invocations.\n", "items": { "$ref": "#/components/schemas/ToolCallTokenUsage" }, "type": "array" } }, "type": "object", "title": "ToolCallDetails" }, "InputTokensDetails": { "properties": { "cached_tokens": { "format": "int64", "type": "integer" }, "cache_creation_input_tokens": { "format": "int64", "type": "integer" }, "cache_read_input_tokens": { "format": "int64", "type": "integer" } }, "required": [ "cached_tokens" ], "type": "object", "title": "InputTokensDetails" }, "OutputTokensDetails": { "properties": { "reasoning_tokens": { "format": "int64", "type": "integer" } }, "required": [ "reasoning_tokens" ], "type": "object", "title": "OutputTokensDetails" }, "ToolCallTokenUsage": { "properties": { "model": { "description": "Model identifier reported by the internal LLM call.", "type": "string" }, "input_tokens": { "description": "Total input tokens, including uncached, cache write, and cache read tokens.", "format": "int64", "type": "integer" }, "output_tokens": { "description": "Output tokens returned by the internal LLM call.", "format": "int64", "type": "integer" }, "input_tokens_details": { "$ref": "#/components/schemas/InputTokensDetails" }, "output_tokens_details": { "$ref": "#/components/schemas/OutputTokensDetails" } }, "required": [ "input_tokens", "output_tokens", "input_tokens_details", "output_tokens_details" ], "type": "object", "title": "ToolCallTokenUsage" }, "ResponseStreamEvent": { "description": "SSE stream event. Discriminate by the `type` field:\n- `response.created`: Initial response object\n- `response.in_progress`: Response processing started\n- `response.completed`: Final response with output\n- `response.failed`: Error occurred\n- `response.output_item.added`: New output item started\n- `response.output_item.done`: Output item completed\n- `response.output_text.delta`: Streaming text delta\n- `response.output_text.done`: Final text content\n- `response.reasoning.started`: Reasoning phase started\n- `response.reasoning.search_queries`: Search queries issued\n- `response.reasoning.search_results`: Search results received\n- `response.reasoning.image_search_queries`: Image queries issued\n- `response.reasoning.image_search_results`: Image results received\n- `response.reasoning.fetch_url_queries`: URL fetch queries issued\n- `response.reasoning.fetch_url_results`: URL fetch results received\n- `response.reasoning.stopped`: Reasoning phase complete\n", "discriminator": { "mapping": { "response.completed": "#/components/schemas/ResponseCompletedEvent", "response.created": "#/components/schemas/ResponseCreatedEvent", "response.failed": "#/components/schemas/ResponseFailedEvent", "response.in_progress": "#/components/schemas/ResponseInProgressEvent", "response.output_item.added": "#/components/schemas/OutputItemAddedEvent", "response.output_item.done": "#/components/schemas/OutputItemDoneEvent", "response.output_text.delta": "#/components/schemas/TextDeltaEvent", "response.output_text.done": "#/components/schemas/TextDoneEvent", "response.reasoning.fetch_url_queries": "#/components/schemas/FetchUrlQueriesEvent", "response.reasoning.fetch_url_results": "#/components/schemas/FetchUrlResultsEvent", "response.reasoning.search_queries": "#/components/schemas/SearchQueriesEvent", "response.reasoning.search_results": "#/components/schemas/SearchResultsEvent", "response.reasoning.image_search_queries": "#/components/schemas/ImageSearchQueriesEvent", "response.reasoning.image_search_results": "#/components/schemas/ImageSearchResultsEvent", "response.reasoning.started": "#/components/schemas/ReasoningStartedEvent", "response.reasoning.stopped": "#/components/schemas/ReasoningStoppedEvent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/ResponseCreatedEvent" }, { "$ref": "#/components/schemas/ResponseInProgressEvent" }, { "$ref": "#/components/schemas/ResponseCompletedEvent" }, { "$ref": "#/components/schemas/ResponseFailedEvent" }, { "$ref": "#/components/schemas/OutputItemAddedEvent" }, { "$ref": "#/components/schemas/OutputItemDoneEvent" }, { "$ref": "#/components/schemas/TextDeltaEvent" }, { "$ref": "#/components/schemas/TextDoneEvent" }, { "$ref": "#/components/schemas/ReasoningStartedEvent" }, { "$ref": "#/components/schemas/SearchQueriesEvent" }, { "$ref": "#/components/schemas/SearchResultsEvent" }, { "$ref": "#/components/schemas/ImageSearchQueriesEvent" }, { "$ref": "#/components/schemas/ImageSearchResultsEvent" }, { "$ref": "#/components/schemas/FetchUrlQueriesEvent" }, { "$ref": "#/components/schemas/FetchUrlResultsEvent" }, { "$ref": "#/components/schemas/ReasoningStoppedEvent" } ], "title": "ResponseStreamEvent" }, "EventType": { "description": "SSE event type discriminator", "enum": [ "response.created", "response.in_progress", "response.completed", "response.failed", "response.output_item.added", "response.output_item.done", "response.output_text.delta", "response.output_text.done", "response.reasoning.started", "response.reasoning.search_queries", "response.reasoning.search_results", "response.reasoning.image_search_queries", "response.reasoning.image_search_results", "response.reasoning.fetch_url_queries", "response.reasoning.fetch_url_results", "response.reasoning.stopped" ], "type": "string", "title": "EventType" }, "ResponseCreatedEvent": { "description": "Response created event (type: \"response.created\").\nContains the initial response object.\n", "properties": { "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number" ], "type": "object", "title": "ResponseCreatedEvent" }, "ResponseInProgressEvent": { "description": "Response in progress event (type: \"response.in_progress\").\nEmitted when response processing has started.\n", "properties": { "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number" ], "type": "object", "title": "ResponseInProgressEvent" }, "ResponseCompletedEvent": { "description": "Response event\nContains the full or partial response object.\n", "properties": { "response": { "$ref": "#/components/schemas/ResponsesResponse" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number" ], "type": "object", "title": "ResponseCompletedEvent" }, "ResponseFailedEvent": { "description": "Response failed event (type: \"response.failed\").\nContains error details when streaming fails.\n", "properties": { "error": { "$ref": "#/components/schemas/ErrorInfo" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "error" ], "type": "object", "title": "ResponseFailedEvent" }, "OutputItemAddedEvent": { "description": "Output item added event (type: \"response.output_item.added\").\nEmitted when a new output item (message or tool call) starts.\n", "properties": { "item": { "$ref": "#/components/schemas/OutputItem" }, "output_index": { "format": "int64", "type": "integer" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "item", "output_index" ], "type": "object", "title": "OutputItemAddedEvent" }, "OutputItemDoneEvent": { "description": "Output item done event (type: \"response.output_item.done\").\nEmitted when an output item (message or tool call) completes.\n", "properties": { "item": { "$ref": "#/components/schemas/OutputItem" }, "output_index": { "format": "int64", "type": "integer" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "item", "output_index" ], "type": "object", "title": "OutputItemDoneEvent" }, "TextDeltaEvent": { "description": "Text delta event (type: \"response.output_text.delta\").\nContains incremental text content.\n", "properties": { "content_index": { "format": "int64", "type": "integer" }, "delta": { "type": "string" }, "item_id": { "type": "string" }, "output_index": { "format": "int64", "type": "integer" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "delta" ], "type": "object", "title": "TextDeltaEvent" }, "TextDoneEvent": { "description": "Text done event (type: \"response.output_text.done\").\nContains the final text content.\n", "properties": { "content_index": { "format": "int64", "type": "integer" }, "item_id": { "type": "string" }, "output_index": { "format": "int64", "type": "integer" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "text": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "text" ], "type": "object", "title": "TextDoneEvent" }, "ReasoningStartedEvent": { "description": "Reasoning started event (type: \"response.reasoning.started\").\nSignals the model has started reasoning/searching.\n", "properties": { "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number" ], "type": "object", "title": "ReasoningStartedEvent" }, "SearchQueriesEvent": { "description": "Search queries event (type: \"response.reasoning.search_queries\").\nContains search queries being executed.\n", "properties": { "queries": { "items": { "type": "string" }, "type": "array" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "queries" ], "type": "object", "title": "SearchQueriesEvent" }, "SearchResultsEvent": { "description": "Search results event (type: \"response.reasoning.search_results\").\nContains search results returned.\n", "properties": { "results": { "items": { "$ref": "#/components/schemas/SearchResult" }, "type": "array" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" }, "usage": { "$ref": "#/components/schemas/ResponsesUsage" } }, "required": [ "type", "sequence_number", "results" ], "type": "object", "title": "SearchResultsEvent" }, "ImageSearchQueriesEvent": { "properties": { "call_id": { "type": "string" }, "queries": { "items": { "type": "string" }, "type": "array" }, "sequence_number": { "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "call_id", "queries" ], "type": "object", "title": "ImageSearchQueriesEvent" }, "ImageSearchResultsEvent": { "properties": { "call_id": { "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/ImageResult" }, "type": "array" }, "sequence_number": { "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" }, "usage": { "$ref": "#/components/schemas/ResponsesUsage" } }, "required": [ "type", "sequence_number", "call_id", "results" ], "type": "object", "title": "ImageSearchResultsEvent" }, "FetchUrlQueriesEvent": { "description": "URL fetch queries event (type: \"response.reasoning.fetch_url_queries\").\nContains URLs being fetched.\n", "properties": { "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" }, "urls": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "sequence_number", "urls" ], "type": "object", "title": "FetchUrlQueriesEvent" }, "FetchUrlResultsEvent": { "description": "URL fetch results event (type: \"response.reasoning.fetch_url_results\").\nContains fetched URL contents.\n", "properties": { "contents": { "items": { "$ref": "#/components/schemas/UrlContent" }, "type": "array" }, "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number", "contents" ], "type": "object", "title": "FetchUrlResultsEvent" }, "ReasoningStoppedEvent": { "description": "Reasoning stopped event (type: \"response.reasoning.stopped\").\nSignals the model has finished reasoning/searching.\n", "properties": { "sequence_number": { "description": "Monotonically increasing sequence number for event ordering", "format": "int64", "type": "integer" }, "thought": { "type": "string" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "type", "sequence_number" ], "type": "object", "title": "ReasoningStoppedEvent" }, "WebSearchStepDetails": { "properties": { "search_results": { "items": { "$ref": "#/components/schemas/ApiPublicSearchResult" }, "type": "array", "title": "Search Results" }, "search_keywords": { "items": { "type": "string" }, "type": "array", "title": "Search Keywords" } }, "type": "object", "required": [ "search_results", "search_keywords" ], "title": "WebSearchStepDetails", "description": "Web search step details wrapper class" }, "FinanceSearchStepDetails": { "properties": { "search_results": { "items": { "$ref": "#/components/schemas/ApiPublicSearchResult" }, "type": "array", "title": "Search Results" }, "search_keywords": { "items": { "type": "string" }, "type": "array", "title": "Search Keywords" } }, "type": "object", "required": [ "search_results", "search_keywords" ], "title": "FinanceSearchStepDetails", "description": "Finance search step details wrapper class" }, "PeopleSearchStepDetails": { "properties": { "search_results": { "items": { "$ref": "#/components/schemas/ApiPublicSearchResult" }, "type": "array", "title": "Search Results" }, "search_keywords": { "items": { "type": "string" }, "type": "array", "title": "Search Keywords" } }, "type": "object", "required": [ "search_results", "search_keywords" ], "title": "PeopleSearchStepDetails", "description": "People search step details wrapper class" }, "EmbeddingsRequest": { "type": "object", "title": "Embeddings Request", "description": "Request body for creating embeddings", "required": [ "input", "model" ], "properties": { "input": { "title": "Input", "description": "Input text to embed, encoded as a string or array of strings. Maximum 512 texts per request. Each input must not exceed 32K tokens. All inputs in a single request must not exceed 120,000 tokens combined. Empty strings are not allowed.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 512 } ] }, "model": { "type": "string", "title": "Model", "description": "The embedding model to use", "enum": [ "pplx-embed-v1-0.6b", "pplx-embed-v1-4b" ] }, "dimensions": { "type": "integer", "title": "Dimensions", "description": "Number of dimensions for output embeddings (Matryoshka). Range: 128-1024 for pplx-embed-v1-0.6b, 128-2560 for pplx-embed-v1-4b. Defaults to full dimensions (1024 or 2560).", "minimum": 128, "maximum": 2560 }, "encoding_format": { "type": "string", "title": "Encoding Format", "description": "Output encoding format for embeddings. base64_int8 returns base64-encoded signed int8 values. base64_binary returns base64-encoded packed binary (1 bit per dimension).", "enum": [ "base64_int8", "base64_binary" ], "default": "base64_int8" } } }, "EmbeddingsResponse": { "type": "object", "title": "Embeddings Response", "description": "Response body for embeddings request", "properties": { "object": { "type": "string", "title": "Object", "description": "The object type", "example": "list" }, "data": { "type": "array", "title": "Data", "description": "List of embedding objects", "items": { "$ref": "#/components/schemas/EmbeddingObject" } }, "model": { "type": "string", "title": "Model", "description": "The model used to generate embeddings" }, "usage": { "$ref": "#/components/schemas/EmbeddingsUsage" } } }, "EmbeddingObject": { "type": "object", "title": "Embedding Object", "description": "A single embedding result", "properties": { "object": { "type": "string", "title": "Object", "description": "The object type", "example": "embedding" }, "index": { "type": "integer", "title": "Index", "description": "The index of the input text this embedding corresponds to" }, "embedding": { "type": "string", "title": "Embedding", "description": "Base64-encoded embedding vector. For base64_int8: decode to signed int8 array (length = dimensions). For base64_binary: decode to packed bits (length = dimensions / 8 bytes)." } } }, "EmbeddingsUsage": { "type": "object", "title": "Embeddings Usage", "description": "Token usage for the embeddings request", "properties": { "prompt_tokens": { "type": "integer", "title": "Prompt Tokens", "description": "Number of tokens in the input texts" }, "total_tokens": { "type": "integer", "title": "Total Tokens", "description": "Total number of tokens processed" }, "cost": { "type": "object", "title": "Cost", "description": "Cost breakdown for the request", "properties": { "input_cost": { "type": "number", "title": "Input Cost", "description": "Cost for input tokens in USD" }, "total_cost": { "type": "number", "title": "Total Cost", "description": "Total cost for the request in USD" }, "currency": { "type": "string", "title": "Currency", "description": "Currency of the cost values", "enum": [ "USD" ] } } } } }, "ContextualizedEmbeddingsRequest": { "type": "object", "title": "Contextualized Embeddings Request", "description": "Request body for creating contextualized embeddings", "required": [ "input", "model" ], "properties": { "input": { "type": "array", "title": "Input", "description": "Nested array structure where each inner array contains chunks from a single document. Chunks within the same document are encoded with document-level context awareness. Maximum 512 documents. Total chunks across all documents must not exceed 16,000. Total tokens per document must not exceed 32K. All chunks in a single request must not exceed 120,000 tokens combined. Empty strings are not allowed.", "items": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "minItems": 1, "maxItems": 512 }, "model": { "type": "string", "title": "Model", "description": "The contextualized embedding model to use", "enum": [ "pplx-embed-context-v1-0.6b", "pplx-embed-context-v1-4b" ] }, "dimensions": { "type": "integer", "title": "Dimensions", "description": "Number of dimensions for output embeddings (Matryoshka). Range: 128-1024 for pplx-embed-context-v1-0.6b, 128-2560 for pplx-embed-context-v1-4b. Defaults to full dimensions (1024 or 2560).", "minimum": 128, "maximum": 2560 }, "encoding_format": { "type": "string", "title": "Encoding Format", "description": "Output encoding format for embeddings. base64_int8 returns base64-encoded signed int8 values. base64_binary returns base64-encoded packed binary (1 bit per dimension).", "enum": [ "base64_int8", "base64_binary" ], "default": "base64_int8" } } }, "ContextualizedEmbeddingsResponse": { "type": "object", "title": "Contextualized Embeddings Response", "description": "Response body for contextualized embeddings request", "properties": { "object": { "type": "string", "title": "Object", "description": "The object type", "example": "list" }, "data": { "type": "array", "title": "Data", "description": "List of contextualized embedding objects", "items": { "$ref": "#/components/schemas/ContextualizedEmbeddingObject" } }, "model": { "type": "string", "title": "Model", "description": "The model used to generate embeddings" }, "usage": { "$ref": "#/components/schemas/EmbeddingsUsage" } } }, "ContextualizedEmbeddingObject": { "type": "object", "title": "Contextualized Embedding Object", "description": "A single contextualized embedding result", "properties": { "object": { "type": "string", "title": "Object", "description": "The object type", "example": "list" }, "index": { "type": "integer", "title": "Index", "description": "The index of the document this chunk belongs to" }, "data": { "type": "array", "title": "Data", "description": "List of embedding objects for chunks in this document", "items": { "$ref": "#/components/schemas/EmbeddingObject" } } } }, "Model": { "type": "object", "description": "Represents a model available through the Agent API.", "properties": { "id": { "type": "string", "description": "The model identifier in `provider/model-name` format. Use this value as the `model` parameter in Agent API requests.", "example": "openai/gpt-5.5" }, "object": { "type": "string", "description": "The object type, which is always `model`.", "enum": [ "model" ], "example": "model" }, "created": { "type": "integer", "description": "The Unix timestamp (in seconds) when the model was created.", "example": 0 }, "owned_by": { "type": "string", "description": "The provider that owns the model (e.g. `openai`, `anthropic`, `google`, `perplexity`, `xai`, `z-ai`, `moonshotai`, `nvidia`).", "example": "openai" } }, "required": [ "id", "object", "created", "owned_by" ] }, "ListModelsResponse": { "type": "object", "description": "Response from the List Models endpoint. Contains a list of available models.", "properties": { "object": { "type": "string", "description": "The object type, which is always `list`.", "enum": [ "list" ], "example": "list" }, "data": { "type": "array", "description": "A list of model objects.", "items": { "$ref": "#/components/schemas/Model" } } }, "required": [ "object", "data" ] }, "ComputerUsageCategoryCount": { "type": "object", "description": "A bucket's count for one value of a category breakdown — e.g. a connector name for connectors, a duration band for task_durations, or paid/promo for credit_usage's Credit Source axis.", "properties": { "category": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "category", "count" ] }, "ComputerUsageBucket": { "type": "object", "properties": { "start_time": { "type": "integer", "description": "Bucket start in unix seconds (UTC), inclusive." }, "end_time": { "type": "integer", "description": "Bucket end in unix seconds (UTC), exclusive." }, "count": { "type": "integer", "description": "Bucket total. For credit_usage this may exceed the sum of any single breakdown — usage without a category attribution counts toward the total but not the breakdown." }, "by_categories": { "type": "object", "description": "Category breakdowns for this bucket, keyed by the labels declared in the response's top-level `categories` list. An empty list means the bucket has no data for that breakdown.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/ComputerUsageCategoryCount" } } } }, "required": [ "start_time", "end_time", "count", "by_categories" ] }, "ComputerUsageResponse": { "type": "object", "properties": { "categories": { "type": "array", "description": "Category breakdown labels the requested dataset surfaces, in canonical render order. Each label is a key in every bucket's `by_categories`.", "items": { "type": "string" } }, "data": { "type": "array", "description": "Every bucket in the page's window, in chronological order. Buckets without data carry count 0 and an empty breakdown.", "items": { "$ref": "#/components/schemas/ComputerUsageBucket" } }, "has_more": { "type": "boolean", "description": "Whether more buckets exist beyond this page. False also when the window's remaining buckets are past the current data frontier." }, "next_page": { "type": [ "string", "null" ], "description": "Cursor for the next page; pass as the page parameter with otherwise identical query parameters." } }, "required": [ "categories", "data", "has_more" ] }, "ComputerUsageV2Result": { "type": "object", "description": "One member's credit usage for a single day.", "properties": { "user_email": { "type": "string", "description": "The member's email. Rows whose member can no longer be resolved to an email are omitted." }, "count": { "type": "integer", "description": "The member's credit total for the day. May exceed the sum of any single breakdown — usage without a category attribution counts toward the total but not the breakdown." }, "by_categories": { "type": "object", "description": "The member's day broken down by each label in the response's top-level `categories` list.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/ComputerUsageCategoryCount" } } } }, "required": [ "user_email", "count", "by_categories" ] }, "ComputerUsageV2Bucket": { "type": "object", "properties": { "start_time": { "type": "integer", "description": "Day start in unix seconds (UTC), inclusive." }, "end_time": { "type": "integer", "description": "Day end in unix seconds (UTC), exclusive." }, "results": { "type": "array", "description": "One row per member with credit usage on this day.", "items": { "$ref": "#/components/schemas/ComputerUsageV2Result" } } }, "required": [ "start_time", "end_time", "results" ] }, "ComputerUsageV2Response": { "type": "object", "properties": { "categories": { "type": "array", "description": "Category breakdown labels each member row surfaces, in canonical render order. Each label is a key in every row's `by_categories`.", "items": { "type": "string" } }, "data": { "type": "array", "description": "Daily buckets in chronological order, each with one row per member who used credits that day. Days with no attributable usage are omitted.", "items": { "$ref": "#/components/schemas/ComputerUsageV2Bucket" } }, "has_more": { "type": "boolean", "description": "Whether more member rows exist beyond this page." }, "next_page": { "type": [ "string", "null" ], "description": "Cursor for the next page; pass as the page parameter with otherwise identical query parameters." } }, "required": [ "categories", "data", "has_more" ] }, "AnalyticsErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "code": { "type": "integer" } }, "required": [ "message", "type", "code" ] } }, "required": [ "error" ] }, "McpToolDef": { "description": "One tool discovered on a remote MCP server.", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "input_schema": { "additionalProperties": true, "description": "The server's JSON Schema for the tool, passed through unmodified.", "type": "object" } }, "required": [ "name", "input_schema" ], "type": "object", "title": "McpToolDef" }, "McpListToolsOutputItem": { "description": "Tools discovered on one external MCP server when the request starts. Matches OpenAI's mcp_list_tools item.", "properties": { "type": { "enum": [ "mcp_list_tools" ], "type": "string" }, "id": { "type": "string" }, "server_label": { "type": "string" }, "connector_id": { "description": "Present only when the item originated from a managed connector.", "type": "string" }, "tools": { "items": { "$ref": "#/components/schemas/McpToolDef" }, "type": "array" }, "error": { "description": "Present only when the server's tools could not be listed. Absent on success.", "type": "string" } }, "required": [ "type", "id", "server_label", "tools" ], "type": "object", "title": "McpListToolsOutputItem" }, "McpCallOutputItem": { "description": "One tool call executed against an external MCP server, modeled on OpenAI's mcp_call item.", "properties": { "type": { "enum": [ "mcp_call" ], "type": "string" }, "id": { "type": "string" }, "server_label": { "type": "string" }, "connector_id": { "description": "Present only when the item originated from a managed connector.", "type": "string" }, "name": { "type": "string" }, "arguments": { "description": "JSON-encoded arguments the model passed.", "type": "string" }, "output": { "description": "Tool output text; empty when the call failed.", "type": "string" }, "error": { "description": "The failure string when the call failed (also returned to the model in-band); null on success, matching OpenAI's mcp_call.", "type": [ "string", "null" ] } }, "required": [ "type", "id", "server_label", "name", "arguments" ], "type": "object", "title": "McpCallOutputItem" }, "McpTool": { "description": "Connects a user-supplied remote MCP server. Agent API discovers the server's tools when the request starts and calls them like native tools. Matches OpenAI's mcp tool. `defer_loading: true` keeps discovered definitions out of the initial model context and lets the model search, inspect, and call them as needed. `require_approval` and `connector_id` are ignored: every call auto-runs, and only bring-your-own `server_url` is honored.", "properties": { "type": { "enum": [ "mcp" ], "type": "string" }, "server_label": { "description": "Unique per request, ^[a-zA-Z0-9_-]{1,64}$. Namespaces the server's tools.", "type": "string" }, "server_url": { "description": "HTTPS URL of the remote MCP server. Must be a Streamable HTTP MCP endpoint; the legacy SSE transport is not supported.", "type": "string" }, "authorization": { "description": "An access token passed to the remote MCP server for authentication. Provide the raw token value. Never logged or echoed.", "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "description": "Extra request headers.", "type": "object" }, "allowed_tools": { "description": "Optional allowlist of tool names. Empty exposes all discovered tools.", "items": { "type": "string" }, "type": "array" }, "defer_loading": { "description": "When true, keeps discovered tool definitions out of the initial model context and lets the model load relevant schemas as needed. Defaults to false.", "type": "boolean" } }, "required": [ "type", "server_label", "server_url" ], "type": "object", "title": "McpTool" }, "NamespaceToolDef": { "description": "One function definition discovered by hosted external-tool search.", "properties": { "type": { "enum": [ "function" ], "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "additionalProperties": true, "description": "The server's JSON Schema for the tool, passed through unmodified.", "type": "object" } }, "required": [ "type", "name" ], "type": "object", "title": "NamespaceToolDef" }, "NamespaceTool": { "description": "A response-only namespace containing complete external tool definitions.", "properties": { "type": { "enum": [ "namespace" ], "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tools": { "items": { "$ref": "#/components/schemas/NamespaceToolDef" }, "type": "array" } }, "required": [ "type", "name", "description", "tools" ], "type": "object", "title": "NamespaceTool" }, "ToolSearchOutputItem": { "description": "Complete public definitions matched by one hosted external-tool search.", "properties": { "type": { "enum": [ "tool_search_output" ], "type": "string" }, "id": { "type": "string" }, "call_id": { "description": "Always null for hosted search.", "type": [ "string", "null" ] }, "execution": { "description": "Execution location. Currently `server`. Clients must tolerate unknown values.", "type": "string" }, "arguments": { "description": "Exact argument text authored by the model for hosted search.", "type": "string" }, "tools": { "items": { "$ref": "#/components/schemas/NamespaceTool" }, "type": "array" }, "status": { "description": "Current execution status. Known values are `in_progress`, `completed`, and `incomplete`. Clients must tolerate unknown values.", "type": "string" } }, "required": [ "type", "id", "call_id", "execution", "tools", "status" ], "type": "object", "title": "ToolSearchOutputItem" }, "ConnectorTool": { "description": "A Perplexity-managed connector scoped to the authenticated API organization.", "properties": { "type": { "enum": [ "connector" ], "type": "string" }, "id": { "description": "Opaque connector identifier.", "type": "string" }, "server_label": { "description": "Unique per request, ^[a-zA-Z0-9_-]{1,64}$. Namespaces the connector's tools.", "type": "string" }, "server_description": { "description": "Optional model-facing namespace description.", "type": "string" }, "allowed_tools": { "description": "Optional exact-name allowlist. Omitted or empty admits every live tool.", "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "id", "server_label" ], "type": "object", "title": "ConnectorTool" }, "SkillSummary": { "type": "object", "required": [ "skill_id" ], "properties": { "skill_id": { "type": "string", "description": "Skill identifier" }, "name": { "type": "string", "description": "Skill name, read from the bundle's `SKILL.md`" }, "revision": { "type": "string", "description": "Opaque revision token of the skill; pass as expected_revision to update or delete" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SkillList": { "type": "object", "required": [ "skills" ], "properties": { "skills": { "type": "array", "items": { "$ref": "#/components/schemas/SkillSummary" } }, "next_page_token": { "type": "string", "description": "Opaque token for the next page; omitted on the last page" } } }, "SkillRevision": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "description": "Opaque revision token" }, "name": { "type": "string", "description": "Skill name at this revision" }, "created_at": { "type": "string", "format": "date-time" } } }, "SkillRevisionList": { "type": "object", "required": [ "revisions" ], "properties": { "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/SkillRevision" } }, "next_page_token": { "type": "string", "description": "Opaque token for the next page; omitted on the last page" } } }, "SkillDownload": { "type": "object", "required": [ "download_url" ], "properties": { "revision": { "type": "string", "description": "Opaque token of the downloaded revision" }, "name": { "type": "string", "description": "Skill name at this revision" }, "download_url": { "type": "string", "description": "Short-lived URL to download the zip bundle" } } }, "ApiError": { "type": "object", "properties": { "error": { "type": "object", "required": [ "message", "type", "code" ], "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "type": { "type": "string", "description": "Error type identifier" }, "code": { "type": "integer", "description": "HTTP status code" }, "param": { "type": "string", "description": "Parameter that caused the error", "nullable": true } } } } }, "ManagedSkill": { "type": "object", "required": [ "skill_id" ], "properties": { "skill_id": { "type": "string", "description": "Skill identifier" }, "name": { "type": "string", "description": "Skill name, read from the bundle's `SKILL.md`" }, "description": { "type": "string", "description": "Skill description, read from the bundle's `SKILL.md`" }, "revision": { "type": "string", "description": "Opaque token of the revision returned in this response; the latest revision, or the specific one requested via `revision`" }, "latest_revision": { "type": "string", "description": "Opaque token of the skill's current latest revision; pass as expected_revision to update or delete" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } }, "parameters": { "SkillId": { "name": "skill_id", "in": "path", "required": true, "description": "Skill identifier returned by create or `GET /v1/skills`", "schema": { "type": "string" } }, "Revision": { "name": "revision", "in": "query", "required": false, "description": "Opaque revision token; when omitted, the active revision is used", "schema": { "type": "string" } }, "ExpectedRevisionRequired": { "name": "expected_revision", "in": "query", "required": true, "description": "Opaque revision token the skill must currently be at. The write applies\nonly if it matches, so it cannot race a concurrent update.\n", "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Maximum items to return, 1 to 200; defaults to 50", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, "PageToken": { "name": "page_token", "in": "query", "required": false, "description": "Opaque token from a previous response's `next_page_token`", "schema": { "type": "string" } } }, "requestBodies": { "SkillBundle": { "required": true, "description": "The skill bundle as a zip archive", "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The skill bundle, a zip archive containing `SKILL.md`" } } } } } } } } }