{ "openapi": "3.1.0", "info": { "title": "", "description": "The main API structure\n\n- `/api/v1beta/` <- Most of the API is nested under here. All of the resources there are scoped to what is accessible by the authenticated identity.\n- `/api/v1beta/me` <- Everything under this path is scoped to the subject of the authenticated identity.\nThis means that the identity may be authorized to view more resources, but this is the default view for them.\nE.g. the chats route scoped under there will only list the chats created by the user, but the user may be authorized to also view chats shared by other users.\n", "version": "" }, "paths": { "/api/licenses": { "get": { "tags": [ "crate::server::license_notices" ], "operationId": "license_notices", "responses": { "200": { "description": "Combined third-party license notices by distribution package", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Failed to read license notices", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/api/v1beta/assistant-hub/assistants": { "get": { "tags": [ "assistant_hub" ], "operationId": "list_assistant_hub_assistants", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubVersionsResponse" } } } }, "401": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/assistants/{hub_assistant_id}": { "get": { "tags": [ "assistant_hub" ], "operationId": "get_assistant_hub_assistant", "parameters": [ { "name": "hub_assistant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubVersionResponse" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/assistants/{hub_assistant_id}/review": { "put": { "tags": [ "assistant_hub" ], "operationId": "submit_assistant_hub_review", "parameters": [ { "name": "hub_assistant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubUserReviewRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubUserReviewResponse" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/assistants/{hub_assistant_id}/reviews": { "get": { "tags": [ "assistant_hub" ], "operationId": "list_assistant_hub_reviews", "parameters": [ { "name": "hub_assistant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubUserReviewsResponse" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/assistants/{source_assistant_id}/submission-diff": { "post": { "tags": [ "assistant_hub" ], "operationId": "preview_assistant_hub_submission_diff", "parameters": [ { "name": "source_assistant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubSubmissionRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubSubmissionDiffResponse" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/assistants/{source_assistant_id}/versions": { "post": { "tags": [ "assistant_hub" ], "operationId": "submit_assistant_hub_version", "parameters": [ { "name": "source_assistant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubSubmissionRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubVersionResponse" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/config": { "get": { "tags": [ "assistant_hub" ], "operationId": "assistant_hub_config", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubConfigResponse" } } } }, "401": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/my/versions": { "get": { "tags": [ "assistant_hub" ], "operationId": "list_my_assistant_hub_versions", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubVersionsResponse" } } } }, "401": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/review/versions": { "get": { "tags": [ "assistant_hub" ], "operationId": "list_review_assistant_hub_versions", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubVersionsResponse" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/versions/{version_id}/current": { "put": { "tags": [ "assistant_hub" ], "operationId": "set_assistant_hub_version_current", "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubVersionResponse" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/versions/{version_id}/featured": { "put": { "tags": [ "assistant_hub" ], "operationId": "set_assistant_hub_version_featured", "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubSetFeaturedRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubVersionResponse" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/versions/{version_id}/published": { "put": { "tags": [ "assistant_hub" ], "operationId": "set_assistant_hub_version_published", "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubSetPublishedRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubVersionResponse" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/versions/{version_id}/review": { "post": { "tags": [ "assistant_hub" ], "operationId": "review_assistant_hub_version", "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubReviewRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubVersionResponse" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistant-hub/versions/{version_id}/withdraw": { "post": { "tags": [ "assistant_hub" ], "operationId": "withdraw_assistant_hub_version", "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantHubVersionResponse" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistants": { "get": { "tags": [ "assistants" ], "summary": "List all assistants available to the user", "operationId": "list_assistants", "parameters": [ { "name": "sharing_relation", "in": "query", "description": "Filter assistants by sharing relation\n- `all` (default): All assistants are listed\n- `owned_by_user`: Only assistants owned by the user\n- `shared_with_user`: Only assistants shared with the user (= all - owned_by_user)", "required": false, "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "description": "Whether to include archived assistants. Defaults to false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully retrieved user's assistants", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Assistant" } } } } }, "400": { "description": "Invalid query parameters" }, "401": { "description": "When no valid JWT token is provided" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "assistants" ], "summary": "Create a new assistant", "operationId": "create_assistant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssistantRequest" } } }, "required": true }, "responses": { "201": { "description": "Successfully created the assistant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantWithFiles" } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "When no valid JWT token is provided" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistants/{assistant_id}": { "get": { "tags": [ "assistants" ], "summary": "Get a specific assistant with its files", "operationId": "get_assistant", "parameters": [ { "name": "assistant_id", "in": "path", "description": "The ID of the assistant to retrieve", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the assistant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantWithFiles" } } } }, "400": { "description": "Invalid assistant ID format" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "Assistant not found or access denied" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "assistants" ], "summary": "Update an existing assistant", "operationId": "update_assistant", "parameters": [ { "name": "assistant_id", "in": "path", "description": "The ID of the assistant to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssistantRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully updated the assistant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantWithFiles" } } } }, "400": { "description": "Invalid assistant ID format or request data" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "Assistant not found or access denied" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistants/{assistant_id}/archive": { "post": { "tags": [ "assistants" ], "summary": "Archive an assistant", "operationId": "archive_assistant", "parameters": [ { "name": "assistant_id", "in": "path", "description": "The ID of the assistant to archive", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveAssistantRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully archived the assistant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveAssistantResponse" } } } }, "400": { "description": "Invalid assistant ID format" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "Assistant not found or access denied" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/assistants/{assistant_id}/usage": { "get": { "tags": [ "assistants" ], "operationId": "get_assistant_usage", "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "weeks", "in": "query", "description": "One of 1, 4, 12, or 52. Defaults to 4.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantUsage" } } } }, "400": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/chats": { "get": { "tags": [], "operationId": "chats", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Chat" } } } } } }, "deprecated": true } }, "/api/v1beta/chats/{chat_id}/archive": { "post": { "tags": [], "summary": "Archive a chat", "description": "This endpoint marks a chat as archived by setting its archived_at timestamp.\nArchived chats can be filtered out from the recent chats listing by default.\nDelegated runs spawned from the chat are archived along with it, except\nthose whose run has not finished yet.", "operationId": "archive_chat_endpoint", "parameters": [ { "name": "chat_id", "in": "path", "description": "The ID of the chat to archive", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveChatRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully archived the chat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveChatResponse" } } } }, "400": { "description": "Invalid chat ID format" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When the chat does not exist or is not accessible" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/chats/{chat_id}/messages": { "get": { "tags": [], "summary": "Get all messages for a specific chat", "operationId": "chat_messages", "parameters": [ { "name": "chat_id", "in": "path", "description": "The ID of the chat to get messages for", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of messages to return per page. Defaults to 100 if not provided. Larger values may impact performance.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Number of messages to skip for pagination. Defaults to 0 if not provided.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Successfully retrieved messages with pagination metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMessagesResponse" } } } }, "400": { "description": "Invalid chat ID format" }, "404": { "description": "When the chat does not exist or is not accessible" }, "500": { "description": "Server error while retrieving messages" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/chats/{chat_id}/unarchive": { "post": { "tags": [], "summary": "Unarchive a chat", "description": "Clears the chat's archived_at timestamp so it reappears in the default\nlisting. Delegated runs archived along with it stay archived, and\nunarchiving a chat that is not archived changes nothing.", "operationId": "unarchive_chat_endpoint", "parameters": [ { "name": "chat_id", "in": "path", "description": "The ID of the chat to unarchive", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully unarchived the chat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnarchiveChatResponse" } } } }, "400": { "description": "Invalid chat ID format" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When the chat does not exist or is not accessible" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/desktop-sidecar/distribution": { "get": { "tags": [ "desktop_sidecar" ], "operationId": "distribution", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopSidecarDistributionResponse" } } } }, "404": { "description": "Desktop sidecar distribution is disabled or unavailable" } } } }, "/api/v1beta/desktop-sidecar/distribution/download": { "get": { "tags": [ "desktop_sidecar" ], "operationId": "download_distribution_artifact", "parameters": [ { "name": "target", "in": "query", "description": "Manifest target identifier.", "required": true, "schema": { "type": "string" } }, { "name": "file", "in": "query", "description": "Manifest file identifier. The target's default is used when omitted.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Desktop sidecar distribution artifact", "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } } }, "404": { "description": "Distribution, target, or file is unavailable" }, "500": { "description": "The validated artifact could not be opened" } } } }, "/api/v1beta/files/{file_id}": { "get": { "tags": [], "summary": "Get a single file by its ID", "description": "This endpoint retrieves information about a specific file by its ID.", "operationId": "get_file", "parameters": [ { "name": "file_id", "in": "path", "description": "The ID of the file to retrieve", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadItem" } } } }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When the file doesn't exist or doesn't belong to the user" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/files/{file_id}/preview": { "get": { "tags": [], "summary": "Get an inline preview for a single file by its ID.", "operationId": "get_file_preview", "parameters": [ { "name": "file_id", "in": "path", "description": "The ID of the file to preview", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the file preview" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When the file doesn't exist or doesn't belong to the user" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/integrations/ms-office/ews": { "post": { "tags": [ "ms_office" ], "summary": "Proxy an Exchange EWS SOAP request to the configured EWS API endpoint.", "operationId": "ews_proxy", "requestBody": { "content": { "text/xml": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Response from the configured Exchange EWS endpoint", "content": { "text/xml": { "schema": { "type": "string" } } } }, "401": { "description": "When the X-EWS-Authentication header is missing or malformed (must be `Bearer ` with a non-empty token)" }, "404": { "description": "Exchange EWS proxy is not configured", "content": { "text/plain": { "schema": { "type": "string" } } } }, "502": { "description": "Failed to proxy the Exchange EWS request", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/integrations/sharepoint/all-drives": { "get": { "tags": [ "sharepoint" ], "summary": "Get all drives accessible to the user.", "description": "This exhaustively walks the Microsoft Graph drive discovery surfaces that are\nrelevant for the current user:\n- `GET /me/drive`: https://learn.microsoft.com/graph/api/drive-get\n- `GET /me/drives`, `GET /groups/{id}/drives`, `GET /sites/{id}/drives`:\n https://learn.microsoft.com/graph/api/drive-list\n- `GET /me/drive/sharedWithMe()`: https://learn.microsoft.com/graph/api/drive-sharedwithme\n- `GET /me/joinedTeams`: https://learn.microsoft.com/graph/api/user-list-joinedteams\n- `GET /sites?search=*`: https://learn.microsoft.com/graph/api/site-search\n- Group-backed library metadata uses the Microsoft Graph group `visibility`\n and `resourceProvisioningOptions` properties:\n https://learn.microsoft.com/graph/api/resources/group\n https://learn.microsoft.com/graph/group-set-options\n- Search requests discover matching group-backed libraries with\n `GET /groups?$search=\"displayName:...\"&$top=20` plus\n `ConsistencyLevel: eventual` before fetching `GET /groups/{id}/drives`:\n https://learn.microsoft.com/graph/search-query-parameter", "operationId": "all_drives", "parameters": [ { "name": "query", "in": "query", "description": "Optional Drive/site search query used to filter the returned drives by drive title or site name. If empty or omitted, wildcard search is used for site discovery and no filtering is applied.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of accessible drives", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllDrivesResponse" } } } }, "401": { "description": "No access token available" }, "404": { "description": "Sharepoint integration is not enabled" }, "500": { "description": "Failed to retrieve drives" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/integrations/sharepoint/drives/{drive_id}": { "get": { "tags": [ "sharepoint" ], "summary": "Get the root items of a specific drive.", "operationId": "get_drive_root", "parameters": [ { "name": "drive_id", "in": "path", "description": "The ID of the drive", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of items in the drive root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveItemsResponse" } } } }, "401": { "description": "No access token available" }, "404": { "description": "Drive not found or Sharepoint integration is not enabled" }, "500": { "description": "Failed to retrieve drive items" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/integrations/sharepoint/drives/{drive_id}/items/{item_id}": { "get": { "tags": [ "sharepoint" ], "summary": "Get details of a specific drive item.", "operationId": "get_drive_item", "parameters": [ { "name": "drive_id", "in": "path", "description": "The ID of the drive", "required": true, "schema": { "type": "string" } }, { "name": "item_id", "in": "path", "description": "The ID of the item", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Drive item details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveItemResponse" } } } }, "401": { "description": "No access token available" }, "404": { "description": "Item not found or Sharepoint integration is not enabled" }, "500": { "description": "Failed to retrieve item" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/integrations/sharepoint/drives/{drive_id}/items/{item_id}/children": { "get": { "tags": [ "sharepoint" ], "summary": "Get the children of a folder in a drive.", "operationId": "get_drive_item_children", "parameters": [ { "name": "drive_id", "in": "path", "description": "The ID of the drive", "required": true, "schema": { "type": "string" } }, { "name": "item_id", "in": "path", "description": "The ID of the folder", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of items in the folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveItemsResponse" } } } }, "401": { "description": "No access token available" }, "404": { "description": "Folder not found or Sharepoint integration is not enabled" }, "500": { "description": "Failed to retrieve folder children" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/budget": { "get": { "tags": [ "budget" ], "operationId": "budget_status", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetStatusResponse" } } } }, "401": { "description": "When no valid JWT token is provided" }, "500": { "description": "When an internal server error occurs" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/chats": { "post": { "tags": [], "summary": "Create a new chat without an initial message", "description": "This endpoint allows creating a new chat without requiring an initial message.\nThis is useful for scenarios where you want to upload files before sending the first message.", "operationId": "create_chat", "parameters": [ { "name": "X-Erato-Platform", "in": "header", "description": "Client surface creating the chat (`web`, `outlook`, `word`, `addin-neutral`, `teams`). Recorded as the chat's `created_via`; defaults to `web`.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully created a new chat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatResponse" } } } }, "401": { "description": "When no valid JWT token is provided" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/chats/archive_all": { "post": { "tags": [], "summary": "Archive all chats owned by the authenticated user.", "description": "Only chats that are currently not archived are updated.\nPreviously archived chats keep their original `archived_at` timestamp.", "operationId": "archive_all_chats_endpoint", "responses": { "200": { "description": "Successfully archived all non-archived chats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveAllChatsResponse" } } } }, "401": { "description": "When no valid JWT token is provided" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/chats/{chat_id}": { "get": { "tags": [], "summary": "Get a single chat.", "description": "Authorized exactly like the chat's message history, and carrying the\nfields a surface needs to describe the chat it just opened — which for a\ndelegated run means its provenance and the parameters it was dispatched\nwith, neither of which is reachable through the listing that hides it.", "operationId": "chat_detail", "parameters": [ { "name": "chat_id", "in": "path", "description": "The ID of the chat to retrieve", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the chat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatDetail" } } } }, "400": { "description": "Invalid chat ID format" }, "404": { "description": "When the chat does not exist or is not accessible" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [], "summary": "Update mutable fields on a chat.", "description": "Supports updating the user-provided title, pin state, the MCP write\ntools toggle and the disabled MCP server and tool lists.", "operationId": "update_chat", "parameters": [ { "name": "chat_id", "in": "path", "description": "The ID of the chat to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChatRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully updated the chat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChatResponse" } } } }, "400": { "description": "Invalid chat ID format" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When the chat does not exist or is not accessible" }, "409": { "description": "When pinning an archived chat" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/chats/{chat_id}/compact": { "post": { "tags": [ "chat_history_compaction" ], "summary": "Compact the current active conversation after explicit user approval.", "operationId": "compact_chat", "parameters": [ { "name": "chat_id", "in": "path", "description": "Chat ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompactChatRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompactChatResponse" } } } }, "400": { "description": "Invalid or over-limit context" }, "403": { "description": "Chat is read-only" }, "404": { "description": "Disabled or missing chat" }, "409": { "description": "Stale tip or busy chat" }, "502": { "description": "Invalid summarizer response" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/chats/{chat_id}/delegated_runs/{child_chat_id}/retry": { "post": { "tags": [], "summary": "Re-dispatch a failed delegated task run as a new async child.", "operationId": "retry_delegated_run", "parameters": [ { "name": "chat_id", "in": "path", "description": "The origin chat the run was dispatched from", "required": true, "schema": { "type": "string" } }, { "name": "child_chat_id", "in": "path", "description": "The failed delegated run to retry", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryDelegatedRunRequest" } } }, "required": true }, "responses": { "202": { "description": "A replacement run was dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryDelegatedRunResponse" } } } }, "400": { "description": "Invalid chat ID format" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When async tasks are disabled, or the origin chat or the run does not exist or is not accessible" }, "409": { "description": "When the origin chat is archived (plain text), the origin's generation lease is held (JSON, code = generation_running, body = GenerationRunningError), or the run cannot be retried (JSON, code = not_retryable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotRetryableError" } } } }, "422": { "description": "When `kind` is not a kind this server retries" }, "500": { "description": "When an internal server error occurs" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/chats/{chat_id}/react": { "post": { "tags": [], "summary": "Run the reaction turn a delivered task result is still owed.", "description": "The explicit, client-driven equivalent of the second half of\n`deliver_task_result`: the `task_result` row is already in the conversation,\nnothing has answered it, and the caller wants that answer run now and\nstreamed back on the same socket.", "operationId": "react_to_task_result_sse", "parameters": [ { "name": "chat_id", "in": "path", "description": "The chat holding the delivered task result", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactToTaskResultRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessage" } } } }, "400": { "description": "Invalid chat ID format" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When async task delivery is disabled, or the chat or message does not exist or is not accessible" }, "409": { "description": "When the chat is archived (plain text), the chat's generation lease is already held (JSON, code = generation_running), or there is nothing to react to (JSON, code = nothing_to_react, body = NothingToReactError)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRunningError" } } } }, "500": { "description": "When an internal server error occurs" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/client-operations": { "get": { "tags": [], "operationId": "listClientOperations", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListClientOperationsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/client-operations/{attempt_id}/cancel": { "post": { "tags": [], "operationId": "cancelClientOperation", "parameters": [ { "name": "attempt_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientOperationResponse" } } } }, "409": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/client-operations/{attempt_id}/claim": { "post": { "tags": [], "operationId": "claimClientOperation", "parameters": [ { "name": "attempt_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimClientOperationRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimClientOperationResponse" } } } }, "409": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/client-operations/{attempt_id}/continue": { "post": { "tags": [], "operationId": "continueClientOperation", "parameters": [ { "name": "attempt_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientOperationResponse" } } } }, "409": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/client-operations/{attempt_id}/result": { "post": { "tags": [], "operationId": "completeClientOperation", "parameters": [ { "name": "attempt_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteClientOperationRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientOperationResponse" } } } }, "409": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/desktop-sidecar/organization-configuration": { "get": { "tags": [ "desktop_sidecar" ], "operationId": "organization_configuration", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopSidecarOrganizationConfiguration" } } } }, "401": { "description": "When no valid JWT token is provided" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/facets": { "get": { "tags": [], "operationId": "facets", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetsResponse" } } } }, "401": { "description": "When no valid JWT token is provided" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/file-capabilities": { "get": { "tags": [], "summary": "Get available file capabilities", "description": "This endpoint returns all available file capabilities based on the configured\nfile processors and model capabilities. An optional model_id can be provided\nto get capabilities specific to that model (particularly for image understanding).", "operationId": "file_capabilities", "parameters": [ { "name": "model_id", "in": "query", "description": "Optional model ID to get capabilities specific to that model", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved file capabilities", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileCapability" } } } } }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When the specified model_id is not found" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/files": { "post": { "tags": [ "files" ], "summary": "Upload files and return UUIDs for each", "description": "This endpoint accepts a multipart form with one or more files and returns UUIDs for each.\nIf chat_id is provided, files are associated with that chat. If not provided, files are created\nas standalone uploads that can be linked to assistants later.\nAn optional `outlook_provenance` text part carries version 1 OutlookFileProvenance JSON\n(maximum 64 KiB). It must occur exactly once before any files and applies to every file\nin the request. Upload files with different origins in separate requests. The original\nEWS ID query parameter remains independent; a containing email's ID never replaces it.", "operationId": "upload_file", "parameters": [ { "name": "chat_id", "in": "query", "description": "Optional chat ID to associate the file with. If not provided, creates standalone files.", "required": false, "schema": { "type": "string" } }, { "name": "external_id_ews_id", "in": "query", "description": "Optional external EWS ID to persist on each file in this request. Upload files with different IDs in separate requests.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Files to upload", "content": { "multipart/form-data": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MultipartFormFile" } } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } }, "400": { "description": "Invalid file upload" }, "413": { "description": "Uploaded file exceeds size or file-count limit" }, "500": { "description": "Server error" } } } }, "/api/v1beta/me/files/link": { "post": { "tags": [ "files" ], "summary": "Link an external file (SharePoint, Google Drive, etc.) and return a file upload record", "description": "This endpoint creates a file upload record that references an external file,\nallowing it to be used in chat messages or attached to assistants.\nIf chat_id is provided, the file is associated with that chat. If not provided,\nthe file is created as a standalone upload.", "operationId": "link_file", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkFileRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } }, "400": { "description": "Invalid request or unsupported source" }, "401": { "description": "No access token available for external provider" }, "404": { "description": "File not found or integration not enabled" }, "415": { "description": "The file is not permitted by the configured upload-operation policy" }, "500": { "description": "Server error" } } } }, "/api/v1beta/me/frequent_assistants": { "get": { "tags": [], "operationId": "frequent_assistants", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of assistants to return. Defaults to 10 if not provided.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "days", "in": "query", "description": "Number of days to look back for usage statistics. Defaults to 30 if not provided.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Successfully retrieved frequently used assistants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrequentAssistantsResponse" } } } }, "500": { "description": "Server error while retrieving assistants" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/generating": { "get": { "tags": [], "operationId": "generating_chats", "responses": { "200": { "description": "Successfully retrieved the chats with a running or recently finished generation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratingChatsResponse" } } } }, "500": { "description": "Server error while retrieving chats" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/local-delegation/context": { "post": { "tags": [ "local_delegation" ], "operationId": "local_delegation_context", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssertionResponse" } } } } } } }, "/api/v1beta/me/local-delegation/exports": { "get": { "tags": [ "local_delegation" ], "operationId": "local_delegation_receipts", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptsResponse" } } } } } } }, "/api/v1beta/me/local-delegation/jobs/{id}/authorize": { "post": { "tags": [ "local_delegation" ], "operationId": "local_delegation_authorize", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationResponse" } } } } } } }, "/api/v1beta/me/local-delegation/jobs/{id}/complete": { "post": { "tags": [ "local_delegation" ], "operationId": "local_delegation_complete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptResponse" } } } } } } }, "/api/v1beta/me/local-delegation/jobs/{id}/export-context": { "post": { "tags": [ "local_delegation" ], "operationId": "local_delegation_export_context", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationResponse" } } } } } } }, "/api/v1beta/me/mcp-tool-approval-settings": { "get": { "tags": [], "operationId": "list_user_tool_approval_settings", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserToolApprovalSettingsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [], "summary": "Store a persistent decision for a tool from the settings surface. The\nin-stream ApproveAlways decision remains the other writer of the same rows;\nthis endpoint exists so a grant flipped back to the policy default in\nsettings can be re-granted without waiting for the next in-chat approval\nstop, and so a tool can be put on ask or denied outright. The\n`allow_always` policy only guards grants: it exists to keep the product\nfrom becoming more permissive, and a denial is strictly more restrictive,\nso it works in deployments that never enable approvals at all. An ask\nneeds the approval gate to have any effect, so it is refused without one.", "operationId": "create_user_tool_approval_setting", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserToolApprovalSettingRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserToolApprovalSetting" } } } }, "400": { "description": "The decision is unavailable under the MCP approval policy or the MCP server is unknown" }, "403": { "description": "The user is not authorized to access the MCP server" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/mcp-tool-approval-settings/batch": { "put": { "tags": [], "summary": "Apply several decisions for one server at once, e.g. a whole group of\ntools set to one decision. Every entry is validated before anything is\nwritten and the writes share one transaction, so a rejected entry leaves\nthe stored decisions untouched.", "operationId": "apply_user_tool_approval_settings_batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyUserToolApprovalSettingsBatchRequest" } } }, "required": true }, "responses": { "200": { "description": "The server's active decisions after the batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserToolApprovalSettingsResponse" } } } }, "400": { "description": "An entry is invalid or unavailable under the MCP approval policy, or the MCP server is unknown" }, "403": { "description": "The user is not authorized to access the MCP server" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/mcp-tool-approval-settings/{setting_id}": { "delete": { "tags": [], "operationId": "deactivate_user_tool_approval_setting", "parameters": [ { "name": "setting_id", "in": "path", "description": "Approval setting ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/mcp_servers": { "get": { "tags": [ "mcp_servers" ], "operationId": "list_mcp_servers", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMcpServersResponse" } } } }, "401": { "description": "When no valid JWT token is provided" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/mcp_servers/{server_id}/oauth": { "delete": { "tags": [ "mcp_servers" ], "operationId": "disconnect_mcp_server_oauth", "parameters": [ { "name": "server_id", "in": "path", "description": "Configured MCP server ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectMcpServerOauthResponse" } } } }, "400": { "description": "The server is not configured for oauth2" }, "401": { "description": "When no valid JWT token is provided" }, "403": { "description": "The user is not authorized to access the MCP server" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/mcp_servers/{server_id}/oauth/callback": { "get": { "tags": [ "mcp_servers" ], "operationId": "complete_mcp_server_oauth", "parameters": [ { "name": "server_id", "in": "path", "description": "Configured MCP server ID", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "OAuth authorization code", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "OAuth authorization state", "required": true, "schema": { "type": "string" } }, { "name": "iss", "in": "query", "description": "OAuth authorization response issuer", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteMcpServerOauthResponse" } } } }, "400": { "description": "The server is not configured for oauth2" }, "401": { "description": "When no valid JWT token is provided" }, "403": { "description": "The user is not authorized to access the MCP server" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/mcp_servers/{server_id}/oauth/start": { "post": { "tags": [ "mcp_servers" ], "operationId": "start_mcp_server_oauth", "parameters": [ { "name": "server_id", "in": "path", "description": "Configured MCP server ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartMcpServerOauthResponse" } } } }, "400": { "description": "The server is not configured for oauth2" }, "401": { "description": "When no valid JWT token is provided" }, "403": { "description": "The user is not authorized to access the MCP server" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/mcp_servers/{server_id}/tools": { "get": { "tags": [ "mcp_servers" ], "operationId": "list_mcp_server_tools", "parameters": [ { "name": "server_id", "in": "path", "description": "Configured MCP server ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMcpServerToolsResponse" } } } }, "401": { "description": "When no valid JWT token is provided" }, "403": { "description": "The user is not authorized to access the MCP server" }, "404": { "description": "The server is not configured" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/messages/abortstream": { "post": { "tags": [], "operationId": "abort_message_stream", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AbortStreamRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AbortStreamResponse" } } } }, "401": { "description": "When no valid JWT token is provided" }, "403": { "description": "When the user has no access to the chat" }, "404": { "description": "No active generation task found for this chat" }, "500": { "description": "When an internal server error occurs" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/messages/clienttoolresult": { "post": { "tags": [], "operationId": "client_tool_result", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientToolResultRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientToolResultResponse" } } } }, "401": { "description": "When no valid JWT token is provided" }, "403": { "description": "When the user has no access to the chat" }, "404": { "description": "No suspended generation matches this chat and message" }, "500": { "description": "When an internal server error occurs" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/messages/continuestream": { "post": { "tags": [], "operationId": "continue_message_sse", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContinueStreamRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessage" } } } }, "400": { "description": "The message has no pending approval, the decision is invalid, or the submitted decisions do not cover the open approvals (JSON, code = decisions_mismatch)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDecisionsError" } } } }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When the chat does not exist or is not accessible" }, "409": { "description": "When the chat is archived (plain text), the chat's generation lease is already held and delegation.tasks.enabled is on (JSON, code = generation_running), every approval the row opened is already decided (JSON, code = already_continued, body = AlreadyContinuedError), or the chat that dispatched this delegated run is still asking the same question (JSON, code = covered_by_parent, body = CoveredByParentError)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRunningError" } } } }, "500": { "description": "When an internal server error occurs" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/messages/editstream": { "post": { "tags": [], "operationId": "edit_message_sse", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditMessageRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/EditMessageStreamingResponseMessage" } } } }, "400": { "description": "When validation fails (e.g., invalid message role)" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When the chat does not exist or is not accessible" }, "409": { "description": "When the chat is archived, or is a delegated run that is still in progress (plain text), or the chat's generation lease is already held and delegation.tasks.enabled is on (JSON, code = generation_running)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRunningError" } } } }, "500": { "description": "When an internal server error occurs" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/messages/regeneratestream": { "post": { "tags": [], "operationId": "regenerate_message_sse", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegenerateMessageRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/RegenerateMessageStreamingResponseMessage" } } } }, "400": { "description": "When validation fails (e.g., invalid message role)" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When the chat does not exist or is not accessible" }, "409": { "description": "When the chat is archived, or is a delegated run that is still in progress (plain text), or the chat's generation lease is already held and delegation.tasks.enabled is on (JSON, code = generation_running)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRunningError" } } } }, "500": { "description": "When an internal server error occurs" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/messages/resumestream": { "post": { "tags": [], "operationId": "resume_message_sse", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeStreamRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessage" } } } }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "No active generation task found for this chat" }, "500": { "description": "When an internal server error occurs" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/messages/submitstream": { "post": { "tags": [], "operationId": "message_submit_sse", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageSubmitRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessage" } } } }, "400": { "description": "When validation fails (e.g., invalid previous_message_id)" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When the chat does not exist or is not accessible" }, "409": { "description": "When the chat is archived, or is a delegated run that is still in progress (plain text), or the chat's generation lease is already held and delegation.tasks.enabled is on (JSON, code = generation_running)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRunningError" } } } }, "500": { "description": "When an internal server error occurs" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/models": { "get": { "tags": [], "summary": "Get available chat models for the user", "description": "This endpoint returns all available chat models (providers) that the user can use.\nEach model includes the provider ID and display name.", "operationId": "available_models", "responses": { "200": { "description": "Successfully retrieved available models", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChatModel" } } } } }, "401": { "description": "When no valid JWT token is provided" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/organization/groups": { "get": { "tags": [ "entra_id" ], "summary": "List all groups in the organization.", "description": "If the Entra ID integration is not enabled, returns an empty list.\nIf enabled, fetches groups from the MS Graph API.\nWhen is_involved=true, only returns groups the user is a member of.\nWhen query parameter is provided (even if empty), returns only the first page for performance.\nNon-empty queries use $search for fuzzy matching.", "operationId": "list_organization_groups", "parameters": [ { "name": "is_involved", "in": "query", "description": "Filter to only show groups the requesting user is \"involved\" with.\nWhen true, only returns groups that the requesting user is a member of.", "required": false, "schema": { "type": "boolean" } }, { "name": "query", "in": "query", "description": "Optional search query to filter groups by displayName.\nUses Microsoft Graph $search parameter with fuzzy, tokenized matching.\nWhen provided (even if empty), only the first page of results is returned for performance.\nThis optimizes search field implementations where typing starts with an empty query.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of organization groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationGroupsResponse" } } } }, "401": { "description": "No access token available" }, "500": { "description": "Failed to retrieve groups" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/organization/users": { "get": { "tags": [ "entra_id" ], "summary": "List all users in the organization.", "description": "If the Entra ID integration is not enabled, returns an empty list.\nIf enabled, fetches users from the MS Graph API.\nWhen is_involved=true, only returns users who share at least one group with the requesting user.\nWhen query parameter is provided (even if empty), returns only the first page for performance.\nNon-empty queries use $search for fuzzy matching.", "operationId": "list_organization_users", "parameters": [ { "name": "is_involved", "in": "query", "description": "Filter to only show users the requesting user is \"involved\" with.\nWhen true, only returns users who share at least one group with the requesting user.", "required": false, "schema": { "type": "boolean" } }, { "name": "query", "in": "query", "description": "Optional search query to filter users by displayName.\nUses Microsoft Graph $search parameter with fuzzy, tokenized matching.\nWhen provided (even if empty), only the first page of results is returned for performance.\nThis optimizes search field implementations where typing starts with an empty query.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of organization users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUsersResponse" } } } }, "401": { "description": "No access token available" }, "500": { "description": "Failed to retrieve users" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/profile": { "get": { "tags": [], "operationId": "profile", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfile" } } } }, "401": { "description": "When no valid JWT token is provided" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/profile/preferences": { "put": { "tags": [], "operationId": "update_profile_preferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfilePreferencesRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfile" } } } }, "401": { "description": "When no valid JWT token is provided" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/recent_chats": { "get": { "tags": [], "operationId": "recent_chats", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of chats to return per page. Defaults to 30 if not provided. Larger values may impact performance.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Number of chats to skip for pagination. Defaults to 0 if not provided.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "include_archived", "in": "query", "description": "Whether to include archived chats in results. Defaults to false if not provided.", "required": false, "schema": { "type": "boolean" } }, { "name": "q", "in": "query", "description": "Optional full-text search query for chat titles. User-provided titles take precedence over generated summary titles. Empty values are treated like an unfiltered recent chats list.", "required": false, "schema": { "type": "string" } }, { "name": "pinned", "in": "query", "description": "If provided, filter chats by their pinned state.", "required": false, "schema": { "type": "boolean" } }, { "name": "type", "in": "query", "description": "If provided, only return chats of the given kind: `chat` for chats without an assistant, `assistant` for assistant-based chats.", "required": false, "schema": { "$ref": "#/components/schemas/RecentChatTypeFilter" } }, { "name": "include_delegated", "in": "query", "description": "Whether to include delegated runs (chats spawned by in-chat delegation). Defaults to false; delegated runs are hidden from listings unless requested.", "required": false, "schema": { "type": "boolean" } }, { "name": "origin_chat_id", "in": "query", "description": "If provided, only return chats spawned from this origin chat. Composes with `include_delegated` rather than overriding it, so listing a chat's delegated runs requires passing both.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "created_via", "in": "query", "description": "Comma-separated `ChatCreatedVia` values. If provided, only return chats created via one of these surfaces.", "required": false, "schema": { "type": "string" } }, { "name": "exclude_created_via", "in": "query", "description": "Comma-separated `ChatCreatedVia` values. Chats created via one of these surfaces are left out. Composes with `created_via`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved chats with pagination metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentChatsResponse" } } } }, "400": { "description": "Invalid origin_chat_id format, or an unknown created_via value" }, "500": { "description": "Server error while retrieving chats" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/starter-prompts": { "get": { "tags": [], "operationId": "starter_prompts", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StarterPromptsResponse" } } } }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "When starter prompts are disabled" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/me/starting-assistant": { "get": { "tags": [ "starting_assistant" ], "operationId": "starting_assistant", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartingAssistantResponse" } } } }, "401": { "description": "When no valid JWT token is provided" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/messages": { "get": { "tags": [], "operationId": "messages", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } } }, "/api/v1beta/messages/{message_id}/feedback": { "put": { "tags": [], "summary": "Submit or update feedback for a message", "operationId": "submit_message_feedback", "parameters": [ { "name": "message_id", "in": "path", "description": "The ID of the message to submit feedback for", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageFeedbackRequest" } } }, "required": true }, "responses": { "200": { "description": "Feedback successfully submitted or updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageFeedback" } } } }, "400": { "description": "Invalid message ID or request format" }, "403": { "description": "User does not have permission to submit feedback for this message, or the editing time limit has been exceeded" }, "404": { "description": "Message not found" }, "500": { "description": "Server error while submitting feedback" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [], "summary": "Delete feedback for a message", "operationId": "delete_message_feedback", "parameters": [ { "name": "message_id", "in": "path", "description": "The ID of the message to delete feedback for", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Feedback successfully deleted" }, "400": { "description": "Invalid message ID" }, "403": { "description": "User does not have permission to delete feedback for this message, or the editing time limit has been exceeded" }, "404": { "description": "Message or feedback not found" }, "500": { "description": "Server error while deleting feedback" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/prompt-optimizer": { "post": { "tags": [], "summary": "Optimize a prompt using the configured prompt optimizer.", "operationId": "prompt_optimizer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptOptimizerRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully optimized the prompt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptOptimizerResponse" } } } }, "400": { "description": "Invalid prompt" }, "401": { "description": "When no valid JWT token is provided" }, "404": { "description": "Prompt optimizer is not enabled" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/share-grants": { "get": { "tags": [ "share_grants" ], "summary": "List share grants for a resource", "operationId": "list_share_grants", "parameters": [ { "name": "resource_type", "in": "query", "description": "The type of resource (e.g., 'assistant')", "required": true, "schema": { "type": "string" } }, { "name": "resource_id", "in": "query", "description": "The ID of the resource", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved share grants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListShareGrantsResponse" } } } }, "400": { "description": "Invalid query parameters" }, "401": { "description": "When no valid JWT token is provided" }, "403": { "description": "User does not own the resource" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "share_grants" ], "summary": "Create a new share grant", "operationId": "create_share_grant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareGrantRequest" } } }, "required": true }, "responses": { "201": { "description": "Successfully created the share grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareGrantResponse" } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "When no valid JWT token is provided" }, "403": { "description": "User does not own the resource" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/share-grants/{grant_id}": { "delete": { "tags": [ "share_grants" ], "summary": "Delete a share grant", "operationId": "delete_share_grant", "parameters": [ { "name": "grant_id", "in": "path", "description": "The ID of the share grant to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Successfully deleted the share grant" }, "400": { "description": "Invalid grant ID format" }, "401": { "description": "When no valid JWT token is provided" }, "403": { "description": "User does not own the resource" }, "404": { "description": "Share grant not found" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/share-links": { "get": { "tags": [ "share_links" ], "operationId": "get_share_link_for_resource", "parameters": [ { "name": "resource_type", "in": "query", "description": "The shared resource type", "required": true, "schema": { "type": "string" } }, { "name": "resource_id", "in": "query", "description": "The shared resource ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkForResourceResponse" } } } }, "403": { "description": "Access denied" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "share_links" ], "operationId": "set_share_link", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetShareLinkRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetShareLinkResponse" } } } }, "403": { "description": "Access denied or feature disabled" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/share-links/{share_link_id}": { "get": { "tags": [ "share_links" ], "operationId": "resolve_share_link", "parameters": [ { "name": "share_link_id", "in": "path", "description": "The share link ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveShareLinkResponse" } } } }, "400": { "description": "Invalid share link ID" }, "404": { "description": "Share link not found, disabled, or unavailable" }, "500": { "description": "Server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/share-links/{share_link_id}/messages": { "get": { "tags": [ "share_links" ], "operationId": "share_link_messages", "parameters": [ { "name": "share_link_id", "in": "path", "description": "The share link ID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of messages to return per page. Defaults to 100 if not provided. Larger values may impact performance.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Number of messages to skip for pagination. Defaults to 0 if not provided.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Successfully retrieved active-thread messages for the shared chat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMessagesResponse" } } } }, "400": { "description": "Invalid share link ID" }, "404": { "description": "Share link not found, disabled, or unavailable" }, "500": { "description": "Server error while retrieving messages" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1beta/token_usage/estimate": { "post": { "tags": [ "token_usage" ], "operationId": "token_usage_estimate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenUsageRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenUsageResponse" } } } }, "401": { "description": "When no valid JWT token is provided" }, "500": { "description": "When an internal server error occurs" } }, "security": [ { "bearer_auth": [] } ] } }, "/health": { "get": { "tags": [], "summary": "Get health of the API.", "operationId": "health", "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "string" } } } } } }, "head": { "tags": [], "summary": "Get health of the API.", "operationId": "health", "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/office-addin/manifest-document.xml": { "get": { "tags": [], "summary": "Get the document task-pane Office add-in manifest with runtime URL substitutions.", "operationId": "office_addin_document_manifest", "parameters": [ { "name": "base_url", "in": "query", "description": "Optional externally reachable deployment base URL used to rewrite the manifest.\nExample: https://app.example.com", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Rendered document task-pane Office add-in manifest", "content": { "application/xml": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid base_url query parameter", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Office add-in is disabled or manifest is unavailable", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Failed to render manifest", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/office-addin/manifest-exchange-server.xml": { "get": { "tags": [], "summary": "Get the Office add-in manifest for Exchange Server with runtime URL substitutions.", "operationId": "office_addin_exchange_server_manifest", "parameters": [ { "name": "base_url", "in": "query", "description": "Optional externally reachable deployment base URL used to rewrite the manifest.\nExample: https://app.example.com", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Rendered Exchange Server Office add-in manifest", "content": { "application/xml": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid base_url query parameter", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Office add-in is disabled or manifest is unavailable", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Failed to render manifest", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/office-addin/manifest.xml": { "get": { "tags": [], "summary": "Get the Office add-in manifest with runtime URL substitutions.", "operationId": "office_addin_manifest", "parameters": [ { "name": "base_url", "in": "query", "description": "Optional externally reachable deployment base URL used to rewrite the manifest.\nExample: https://app.example.com", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Rendered Office add-in manifest", "content": { "application/xml": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid base_url query parameter", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Office add-in is disabled or manifest is unavailable", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Failed to render manifest", "content": { "text/plain": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "AbortStreamRequest": { "type": "object", "required": [ "chat_id" ], "properties": { "chat_id": { "type": "string", "format": "uuid", "description": "The ID of the chat whose active generation should be stopped.", "example": "00000000-0000-0000-0000-000000000000" } } }, "AbortStreamResponse": { "type": "object", "required": [ "abort_requested" ], "properties": { "abort_requested": { "type": "boolean" } } }, "ActionFacetInfo": { "type": "object", "required": [ "id", "display_name" ], "properties": { "allowed_args": { "type": "array", "items": { "type": "string" }, "description": "Argument keys accepted by this facet. Clients can gate optional context on this list." }, "client_actions": { "type": "array", "items": { "type": "string" }, "description": "Fixed identifiers of client-side actions the model may propose via the\n`propose_client_action` tool when this facet is active. The client\nmust only execute actions from this list, after user confirmation." }, "client_actions_always_ask": { "type": "array", "items": { "type": "string" }, "description": "Subset of `client_actions` the deployment enforces a per-use\nconfirmation for: the client must always ask and must not offer or\nhonor a persistent \"always allow\" for these actions. Users may still\ndeny them entirely." }, "display_name": { "type": "string", "description": "Human readable name for the facet, e.g. for client settings UIs." }, "id": { "type": "string" }, "platform": { "type": "string" }, "presentation": { "type": "string", "description": "How the client should surface a proposed client action:\n`render_buttons` (show buttons, user clicks) or `auto_prompt` (the\nclient may surface the proposal immediately after a fresh assistant\ncompletion, subject to the user's local approval preferences). Present\nonly when `client_actions` is non-empty; defaults to `render_buttons`." } } }, "ActionFacetRequest": { "type": "object", "description": "A facet action requested by the user for this generation.", "required": [ "id" ], "properties": { "args": { "type": "object", "description": "Key-value arguments for the action facet.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "The unique identifier of the action facet." } } }, "AllDrivesResponse": { "type": "object", "description": "Response for the all-drives endpoint", "required": [ "drives" ], "properties": { "drives": { "type": "array", "items": { "$ref": "#/components/schemas/Drive" }, "description": "List of drives accessible to the user" } } }, "AlreadyContinuedError": { "type": "object", "description": "Body of the `409` `continuestream` answers when the named row has nothing\nleft to decide: a duplicate resume, not a decision the server refused.", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Always `already_continued`." } } }, "ApplyUserToolApprovalSettingsBatchRequest": { "type": "object", "required": [ "mcp_server_id", "decisions" ], "properties": { "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/UserToolApprovalDecisionEntry" } }, "mcp_server_id": { "type": "string" } } }, "ApprovalDecisionItem": { "type": "object", "description": "One decision of a continuation, naming the approval it answers.", "required": [ "approval_id", "decision" ], "properties": { "approval_id": { "type": "string", "example": "call_abc123" }, "decision": { "$ref": "#/components/schemas/ToolApprovalDecision" } } }, "ApprovalDecisionsError": { "type": "object", "description": "Body of the `400` answers when the submitted decisions do not match the\napprovals a parked turn has open.\n\nTwo lists rather than one message, because the client's recovery differs:\n`missing` means it has to ask the user the remaining questions, `unknown`\nmeans the card it rendered is stale and the row needs refetching.", "required": [ "code", "missing", "unknown" ], "properties": { "code": { "type": "string", "description": "Always `decisions_mismatch`." }, "missing": { "type": "array", "items": { "type": "string" }, "description": "Open approvals that no submitted decision covers." }, "unknown": { "type": "array", "items": { "type": "string" }, "description": "Submitted approval ids this turn does not have open." } } }, "ApprovalItem": { "type": "object", "description": "One decision the user owes on a parked turn. A stop carries several of\nthese when a batch parked on more than one call.", "required": [ "approval_id", "tool_call_id", "tool_name", "input" ], "properties": { "approval_id": { "type": "string" }, "child": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChildApprovalRef" } ] }, "display": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ToolDisplayMetadata" } ] }, "input": { "$ref": "#/components/schemas/Value" }, "tool_call_id": { "type": "string" }, "tool_name": { "type": "string" } } }, "ApprovedExport": { "type": "object", "required": [ "binding", "exportId", "snapshotId", "grantId", "manifestDigest", "approvedAt", "expiresAt", "artifacts" ], "properties": { "approvedAt": { "type": "integer", "maximum": 9007199254740991, "minimum": 0 }, "artifacts": { "type": "array" }, "binding": { "type": "object", "required": [ "backendOrigin", "accountId", "deviceId", "taskId", "jobId", "attemptId", "toolCallId", "planDigest" ], "properties": { "accountId": { "type": "string", "maxLength": 128, "minLength": 1 }, "attemptId": { "type": "string", "maxLength": 128, "minLength": 1 }, "backendOrigin": { "type": "string", "maxLength": 2048, "minLength": 1 }, "deviceId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,128}$" }, "jobId": { "type": "string", "maxLength": 128, "minLength": 1 }, "planDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "taskId": { "type": "string", "maxLength": 128, "minLength": 1 }, "toolCallId": { "type": "string", "maxLength": 128, "minLength": 1 } }, "additionalProperties": true }, "expiresAt": { "type": "integer", "maximum": 9007199254740991, "minimum": 0 }, "exportId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,128}$" }, "grantId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,128}$" }, "manifestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "snapshotId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,128}$" } }, "additionalProperties": true }, "ArchiveAllChatsResponse": { "type": "object", "description": "Response from the archive all chats endpoint", "required": [ "archived_count" ], "properties": { "archived_count": { "type": "integer", "format": "int64", "description": "Number of chats newly archived by this call." } } }, "ArchiveAssistantRequest": { "type": "object", "description": "Request to archive an assistant" }, "ArchiveAssistantResponse": { "type": "object", "description": "Response when archiving an assistant", "required": [ "id", "archived_at" ], "properties": { "archived_at": { "type": "string", "format": "date-time", "description": "When the assistant was archived" }, "id": { "type": "string", "description": "The ID of the archived assistant" } } }, "ArchiveChatRequest": { "type": "object", "description": "Request to archive a chat" }, "ArchiveChatResponse": { "type": "object", "description": "Response from the archive chat endpoint", "required": [ "chat_id", "archived_at" ], "properties": { "archived_at": { "type": "string", "format": "date-time", "description": "The time when the chat was archived" }, "chat_id": { "type": "string", "description": "The ID of the archived chat" } } }, "AssertionResponse": { "type": "object", "required": [ "assertion" ], "properties": { "assertion": { "type": "string" } } }, "Assistant": { "type": "object", "description": "An assistant model", "required": [ "id", "name", "prompt", "enforce_facet_settings", "created_at", "updated_at", "can_edit" ], "properties": { "archived_at": { "type": "string", "format": "date-time", "description": "When this assistant was archived" }, "can_edit": { "type": "boolean", "description": "Whether the current user can edit this assistant\n\nThis is true for the owner and users with an editor share grant." }, "created_at": { "type": "string", "format": "date-time", "description": "When this assistant was created" }, "default_chat_provider": { "type": "string", "description": "Default chat provider/model ID for this assistant" }, "description": { "type": "string", "description": "Optional description of the assistant" }, "enforce_facet_settings": { "type": "boolean", "description": "Whether chats derived from this assistant must use the configured facets" }, "facet_ids": { "type": "array", "items": { "type": "string" }, "description": "Default facet IDs for chats derived from this assistant" }, "id": { "type": "string", "description": "The unique ID of the assistant" }, "mcp_server_ids": { "type": "array", "items": { "type": "string" }, "description": "List of MCP server IDs available to this assistant" }, "name": { "type": "string", "description": "The display name of the assistant" }, "owner_email": { "type": "string", "description": "Optional email of the assistant owner" }, "prompt": { "type": "string", "description": "The system prompt used by the assistant" }, "updated_at": { "type": "string", "format": "date-time", "description": "When this assistant was last updated" } } }, "AssistantFile": { "type": "object", "description": "A file associated with an assistant", "required": [ "id", "filename", "file_contents_unavailable_missing_permissions", "is_sharepoint_file", "file_capability" ], "properties": { "download_url": { "type": [ "string", "null" ], "description": "Pre-signed URL for downloading the file.\nNull when file contents are unavailable for the current user due to missing permissions." }, "external_id_ews_id": { "type": "string", "description": "External Exchange Web Services ID for deep linking to the original item." }, "file_capability": { "$ref": "#/components/schemas/FileCapability", "description": "The file capability that was evaluated for this file" }, "file_contents_unavailable_missing_permissions": { "type": "boolean", "description": "Indicates that file contents are unavailable for the current user due to missing permissions." }, "filename": { "type": "string", "description": "The original filename" }, "id": { "type": "string", "description": "The unique ID of the file" }, "is_sharepoint_file": { "type": "boolean", "description": "True when this file is stored in Sharepoint" }, "outlook_provenance": { "$ref": "#/components/schemas/OutlookFileProvenance", "description": "Outlook source references for reopening the original email." }, "preview_url": { "type": [ "string", "null" ], "description": "Proxied URL for inline preview without forcing download when available." } } }, "AssistantHubAssistantSnapshot": { "type": "object", "required": [ "id", "name", "prompt", "enforce_facet_settings", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "default_chat_provider": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "enforce_facet_settings": { "type": "boolean" }, "facet_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "id": { "type": "string" }, "mcp_server_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "name": { "type": "string" }, "prompt": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AssistantHubAudienceGrantInput": { "type": "object", "required": [ "subject_type", "subject_id_type", "subject_id", "role" ], "properties": { "role": { "type": "string" }, "subject_id": { "type": "string", "description": "The ID of the subject. Organization-wide grants use \"__organization__\"." }, "subject_id_type": { "type": "string", "description": "The type of subject ID (e.g., \"id\", \"organization_group_id\", or \"organization_id\")" }, "subject_type": { "type": "string", "description": "The type of subject to grant access to (e.g., \"user\", \"organization_group\", or \"organization\")" } } }, "AssistantHubCategory": { "type": "object", "required": [ "id", "display_name", "icon" ], "properties": { "display_name": { "type": "string" }, "icon": { "type": "string" }, "id": { "type": "string" } } }, "AssistantHubConfigResponse": { "type": "object", "required": [ "enabled", "enable_categories", "can_review", "rating_mode", "default_share_with_whole_organization", "categories" ], "properties": { "can_review": { "type": "boolean" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantHubCategory" } }, "default_share_with_whole_organization": { "type": "boolean" }, "enable_categories": { "type": "boolean" }, "enabled": { "type": "boolean" }, "rating_mode": { "type": "string" } } }, "AssistantHubCreator": { "type": "object", "required": [ "id", "display_name" ], "properties": { "display_name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "id": { "type": "string" } } }, "AssistantHubReviewRequest": { "type": "object", "required": [ "accepted" ], "properties": { "accepted": { "type": "boolean" }, "reviewer_review_comment": { "type": [ "string", "null" ] } } }, "AssistantHubReviewUser": { "type": "object", "required": [ "id", "display_name" ], "properties": { "display_name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "id": { "type": "string" } } }, "AssistantHubSetFeaturedRequest": { "type": "object", "required": [ "featured" ], "properties": { "featured": { "type": "boolean" } } }, "AssistantHubSetPublishedRequest": { "type": "object", "required": [ "is_published" ], "properties": { "is_published": { "type": "boolean" } } }, "AssistantHubSubmissionDiffResponse": { "type": "object", "required": [ "diff_summary" ], "properties": { "diff_summary": { "type": "object" } } }, "AssistantHubSubmissionRequest": { "type": "object", "required": [ "long_description", "category_ids", "keywords", "version_number" ], "properties": { "audience_grants": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantHubAudienceGrantInput" } }, "category_ids": { "type": "array", "items": { "type": "string" } }, "creator_review_comment": { "type": [ "string", "null" ] }, "keywords": { "type": "array", "items": { "type": "string" } }, "long_description": { "type": "string" }, "version_comment": { "type": [ "string", "null" ] }, "version_number": { "type": "string" } } }, "AssistantHubUserReview": { "type": "object", "required": [ "id", "hub_assistant_id", "version_id", "version_number", "reviewer", "score", "created_at", "updated_at" ], "properties": { "comment": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "hub_assistant_id": { "type": "string" }, "id": { "type": "string" }, "reviewer": { "$ref": "#/components/schemas/AssistantHubReviewUser" }, "score": { "type": "integer", "format": "int32" }, "updated_at": { "type": "string", "format": "date-time" }, "version_id": { "type": "string" }, "version_number": { "type": "string" } } }, "AssistantHubUserReviewRequest": { "type": "object", "required": [ "score" ], "properties": { "comment": { "type": [ "string", "null" ] }, "score": { "type": "integer", "format": "int32" } } }, "AssistantHubUserReviewResponse": { "type": "object", "required": [ "review" ], "properties": { "review": { "$ref": "#/components/schemas/AssistantHubUserReview" } } }, "AssistantHubUserReviewsResponse": { "type": "object", "required": [ "reviews" ], "properties": { "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantHubUserReview" } } } }, "AssistantHubVersion": { "type": "object", "required": [ "hub_assistant_id", "source_assistant_id", "version_id", "assistant_id", "status", "is_published", "is_current_published_version", "featured", "version_number", "long_description", "category_ids", "keywords", "diff_summary", "submitted_at", "created_at", "updated_at", "review_count", "audience_grants", "assistant", "creator" ], "properties": { "assistant": { "$ref": "#/components/schemas/AssistantHubAssistantSnapshot" }, "assistant_id": { "type": "string" }, "audience_grants": { "type": "array", "items": { "$ref": "#/components/schemas/ShareGrant" } }, "category_ids": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "creator": { "$ref": "#/components/schemas/AssistantHubCreator" }, "creator_review_comment": { "type": [ "string", "null" ] }, "diff_summary": { "type": "object" }, "featured": { "type": "boolean" }, "hub_assistant_id": { "type": "string" }, "is_current_published_version": { "type": "boolean" }, "is_published": { "type": "boolean" }, "keywords": { "type": "array", "items": { "type": "string" } }, "long_description": { "type": "string" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_average_score": { "type": [ "number", "null" ], "format": "double" }, "review_count": { "type": "integer", "format": "int64", "minimum": 0 }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "reviewer_review_comment": { "type": [ "string", "null" ] }, "source_assistant_id": { "type": "string" }, "status": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "version_comment": { "type": [ "string", "null" ] }, "version_id": { "type": "string" }, "version_number": { "type": "string" }, "withdrawn_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "AssistantHubVersionResponse": { "type": "object", "required": [ "version" ], "properties": { "version": { "$ref": "#/components/schemas/AssistantHubVersion" } } }, "AssistantHubVersionsResponse": { "type": "object", "required": [ "versions" ], "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantHubVersion" } } } }, "AssistantUsage": { "type": "object", "required": [ "assistant_name", "total_invocations", "total_unique_users", "bucket_days", "buckets" ], "properties": { "assistant_name": { "type": "string" }, "bucket_days": { "type": "integer", "format": "int32", "minimum": 0 }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBucket" } }, "total_invocations": { "type": "integer", "format": "int64" }, "total_unique_users": { "type": "integer", "format": "int64" } } }, "AssistantWithFiles": { "allOf": [ { "$ref": "#/components/schemas/Assistant", "description": "The assistant information" }, { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantFile" }, "description": "Files associated with this assistant" } } } ], "description": "An assistant with its associated files" }, "AttemptState": { "type": "string", "enum": [ "pending", "claimed", "ready", "continuing", "completed" ] }, "AudioTranscriptSegment": { "type": "object", "properties": { "chunk_index": { "type": "integer", "description": "Zero-based chunk index for this segment.", "minimum": 0 }, "end_ms": { "type": "integer", "format": "int64", "description": "Segment end offset in milliseconds.", "minimum": 0 }, "start_ms": { "type": "integer", "format": "int64", "description": "Segment start offset in milliseconds.", "minimum": 0 }, "text": { "type": "string", "description": "Transcribed text for this segment." } } }, "AudioTranscriptionChunk": { "type": "object", "properties": { "attempts": { "type": "integer", "description": "Number of attempts made for this chunk.", "minimum": 0 }, "byte_end": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional byte range end in the stored canonical audio object.", "minimum": 0 }, "byte_start": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional byte range start in the stored canonical audio object.", "minimum": 0 }, "end_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional end offset in milliseconds for the chunk.", "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Optional sanitized error for this chunk." }, "index": { "type": "integer", "description": "Stable zero-based chunk index.", "minimum": 0 }, "start_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional start offset in milliseconds for the chunk.", "minimum": 0 }, "status": { "type": "string", "description": "Per-chunk transcription status." }, "transcript": { "type": [ "string", "null" ], "description": "Per-chunk transcript text." } } }, "AudioTranscriptionMetadata": { "type": "object", "properties": { "chunks": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AudioTranscriptionChunk" }, "description": "Per-chunk progress and state for future timeline alignment." }, "error": { "type": [ "string", "null" ], "description": "Optional error message if status indicates failure." }, "progress": { "type": [ "number", "null" ], "format": "double", "description": "Optional aggregate progress value in `[0, 1]`." }, "status": { "type": "string", "description": "Current transcription state." }, "transcript": { "type": [ "string", "null" ], "description": "Optional transcript text once transcription completes." }, "transcript_segments": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AudioTranscriptSegment" }, "description": "Transcript segments derived from completed chunks for timeline-aware UI surfaces." } } }, "AuthorizationRequest": { "type": "object", "required": [ "claimToken" ], "properties": { "claimToken": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "AuthorizationResponse": { "type": "object", "required": [ "job", "authorization" ], "properties": { "authorization": { "type": "string" }, "job": { "$ref": "#/components/schemas/NativeJobResponse" } } }, "BudgetCurrency": { "type": "string", "enum": [ "EUR", "USD" ] }, "BudgetStatusResponse": { "type": "object", "description": "Budget status information for the current user", "required": [ "enabled" ], "properties": { "budget_currency": { "$ref": "#/components/schemas/BudgetCurrency", "description": "The currency configured for display purposes" }, "budget_limit": { "type": "number", "format": "double", "description": "The budget limit for the time period (unit-less)" }, "budget_period_days": { "type": "integer", "format": "int32", "description": "Number of days in the current budget period", "minimum": 0 }, "current_spending": { "type": "number", "format": "double", "description": "Current spending in the budget period for the user (unit-less)" }, "enabled": { "type": "boolean", "description": "Whether the budget feature is enabled" }, "warn_threshold": { "type": "number", "format": "double", "description": "The warning threshold (0.0 to 1.0)" } } }, "Chat": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } }, "deprecated": true }, "ChatCreatedVia": { "type": "string", "description": "Surface a chat was created from, stored in `chats.created_via`.", "enum": [ "legacy", "web", "outlook", "word", "office_addin", "ms_teams_tab", "ms_teams_bot" ] }, "ChatDetail": { "type": "object", "description": "A single chat, for surfaces that open one directly rather than picking it\nout of a listing.\n\nDelegated runs are why this exists: `/me/recent_chats` hides them unless\nasked for, so a client that follows a link into one has no listing row to\nread its provenance and run parameters from.", "required": [ "id", "title_resolved", "is_pinned", "mcp_write_tools_enabled", "disabled_mcp_server_ids", "disabled_mcp_tools", "can_edit", "created_via" ], "properties": { "adopted_at": { "type": "string", "format": "date-time", "description": "Delegated runs only: when the owner first wrote into the run\nthemselves, taking it over from the conversation that dispatched it." }, "archived_at": { "type": "string", "format": "date-time", "description": "When this chat was archived by the user, or by the archive cascade of\nthe chat that spawned it." }, "assistant_id": { "type": "string", "description": "The assistant ID if this chat is based on an assistant." }, "assistant_name": { "type": "string", "description": "The name of the assistant if this chat is based on an assistant." }, "can_edit": { "type": "boolean", "description": "Whether the current user can edit this chat." }, "constraints": { "type": "string", "description": "Delegated runs only: the limits the delegate was told to work within." }, "created_via": { "$ref": "#/components/schemas/ChatCreatedVia", "description": "Surface the chat was created from." }, "disabled_mcp_server_ids": { "type": "array", "items": { "type": "string" }, "description": "MCP servers the user switched off for this chat; their tools are not\noffered to the model." }, "disabled_mcp_tools": { "type": "array", "items": { "type": "string" }, "description": "`server/tool` patterns of MCP tools the user switched off for this\nchat; matching tools are not offered to the model." }, "expected_output": { "type": "string", "description": "Delegated runs only: the result shape the dispatching model asked for." }, "id": { "type": "string" }, "is_pinned": { "type": "boolean", "description": "Whether this chat is pinned by its owner." }, "mcp_write_tools_enabled": { "type": "boolean", "description": "Whether the model may be offered MCP write tools and client actions\nin this chat. Off, only tools the server marks read-only are offered." }, "origin_assistant_id": { "type": "string", "description": "The assistant bound to the origin chat at spawn time, if any." }, "origin_chat_id": { "type": "string", "description": "The origin chat this chat was spawned from, if any. May reference a\ndeleted chat." }, "origin_chat_title": { "type": "string", "description": "Resolved display title of the origin chat; absent when the origin no\nlonger exists." }, "provenance_kind": { "type": "string", "description": "Provenance kind when the chat was spawned from another chat (e.g.\n`delegation` for a delegated run). Clients derive \"is delegated run\"\nfrom this value." }, "title_by_summary": { "type": "string", "description": "Title of the chat as generated by summary automation." }, "title_by_user_provided": { "type": "string", "description": "Title of the chat as explicitly provided by the user." }, "title_resolved": { "type": "string", "description": "Resolved chat title where user-provided title takes precedence over\nsummary title." } } }, "ChatMessage": { "type": "object", "description": "A message in a chat", "required": [ "id", "chat_id", "role", "content", "created_at", "updated_at", "is_message_in_active_thread", "input_files_ids", "files" ], "properties": { "action_facet_args": { "type": "object", "description": "The action facet arguments supplied with this user message, if any", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "action_facet_id": { "type": "string", "description": "The action facet ID supplied with this user message, if any" }, "chat_id": { "type": "string", "description": "The ID of the chat this message belongs to" }, "chat_provider_id": { "type": "string", "description": "The chat provider used to generate this message, if available." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPart" }, "description": "The text content of the message" }, "created_at": { "type": "string", "format": "date-time", "description": "When the message was created" }, "error": { "$ref": "#/components/schemas/GenerationErrorType", "description": "Optional error information if generation failed" }, "error_report": { "type": "string", "description": "Rendered copyable error report if generation failed" }, "feedback": { "$ref": "#/components/schemas/MessageFeedback", "description": "Optional feedback for this message" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileUploadItem" }, "description": "Resolved file objects for all input_files_ids" }, "id": { "type": "string", "description": "The unique ID of the message" }, "initiator": { "$ref": "#/components/schemas/GenerationInitiator", "description": "Who started the generation that produced this assistant message.\nAbsent means a user did, so messages written before this existed keep\ntheir meaning." }, "input_files_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of the files that were used to generate this message" }, "is_message_in_active_thread": { "type": "boolean", "description": "Whether this message is in the active thread" }, "mcp_servers_disabled_by_user": { "type": "array", "items": { "type": "string" }, "description": "MCP server IDs whose tools were withheld from this generation because\nthe user switched the server off for the chat" }, "mcp_servers_needing_auth": { "type": "array", "items": { "type": "string" }, "description": "MCP server IDs skipped for this generation because the requesting user\nhas not completed the server's OAuth authorization yet" }, "mcp_servers_unavailable": { "type": "array", "items": { "type": "string" }, "description": "MCP server IDs that were unavailable while preparing this generation" }, "mcp_tools_disabled_by_user": { "type": "array", "items": { "type": "string" }, "description": "`server/tool` names of MCP tools withheld from this generation because\nthe user switched the tool off for the chat" }, "mentioned_assistants": { "type": "array", "items": { "$ref": "#/components/schemas/MentionedAssistant" }, "description": "Assistants the user @-mentioned in this message, resolved to display\nnames at read time. Mentions whose assistant no longer resolves are\nomitted; absent on assistant messages and mention-less user messages." }, "previous_message_id": { "type": "string", "description": "The ID of the previous message in the thread, if any" }, "role": { "type": "string", "description": "Role of the message sender. May be on of \"user\", \"assistant\", \"system\"" }, "sibling_message_id": { "type": "string", "description": "The unique ID of the sibling message, if any" }, "submission_outcome": { "$ref": "#/components/schemas/SubmissionOutcome" }, "task_result": { "$ref": "#/components/schemas/TaskResultInput", "description": "Present on a user message the server appended to deliver a finished\ndelegated task's result. The client uses it to tell such a row apart\nfrom one a person wrote, and to decide whether it still needs a\nreaction." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the message was last updated" } } }, "ChatMessageStats": { "type": "object", "description": "Statistics for a list of chat messages", "required": [ "total_count", "current_offset", "returned_count", "has_more" ], "properties": { "current_offset": { "type": "integer", "format": "int64", "description": "Current offset in the list", "minimum": 0 }, "has_more": { "type": "boolean", "description": "Whether there are more messages available" }, "returned_count": { "type": "integer", "description": "Number of messages in the current response", "minimum": 0 }, "total_count": { "type": "integer", "format": "int64", "description": "Total number of messages in the chat" } } }, "ChatMessagesResponse": { "type": "object", "description": "Response for the chat_messages endpoint", "required": [ "messages", "stats" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" }, "description": "The list of messages" }, "stats": { "$ref": "#/components/schemas/ChatMessageStats", "description": "Statistics about the message list" } } }, "ChatModel": { "type": "object", "description": "A chat model available to the user", "required": [ "chat_provider_id", "model_display_name" ], "properties": { "chat_provider_id": { "type": "string", "description": "The unique ID of the chat provider" }, "model_description": { "type": [ "string", "null" ], "description": "Optional description of the model shown to users" }, "model_display_name": { "type": "string", "description": "The display name of the model shown to users" }, "model_icon": { "type": [ "string", "null" ], "description": "Optional icon identifier of the model shown to users" } } }, "ChildApprovalRef": { "type": "object", "description": "The gated call a delegated child parked on, copied onto the parent's\napproval item so the card renders without reading the child's chat.", "required": [ "child_chat_id", "child_message_id", "child_tool_call_id", "tool_name", "mcp_server_id", "input", "annotations", "preset", "requested_at" ], "properties": { "annotations": { "$ref": "#/components/schemas/ToolApprovalAnnotations" }, "child_chat_id": { "type": "string", "format": "uuid" }, "child_message_id": { "type": "string", "format": "uuid" }, "child_tool_call_id": { "type": "string" }, "display": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ToolDisplayMetadata" } ] }, "input": { "$ref": "#/components/schemas/Value" }, "mcp_server_id": { "type": "string" }, "preset": { "type": "string" }, "requested_at": { "type": "string" }, "tool_name": { "type": "string" } } }, "ClaimClientOperationRequest": { "type": "object", "required": [ "binding" ], "properties": { "binding": { "$ref": "#/components/schemas/ExecutorBinding" }, "user_confirmed": { "type": "boolean" } }, "additionalProperties": false }, "ClaimClientOperationResponse": { "type": "object", "required": [ "claim_token", "expires_at" ], "properties": { "claim_token": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" } } }, "ClientOperationResponse": { "type": "object", "required": [ "state" ], "properties": { "state": { "$ref": "#/components/schemas/AttemptState" } } }, "ClientOperationView": { "type": "object", "required": [ "request", "state" ], "properties": { "request": { "$ref": "#/components/schemas/OperationRequest" }, "state": { "$ref": "#/components/schemas/AttemptState" } } }, "ClientToolDecision": { "type": "string", "description": "A user's standing decision for one client tool, keyed by its qualified\n`namespace/name`. Tools without a decision keep their default behaviour.", "enum": [ "never_allow", "ask", "always_allow" ] }, "ClientToolDraftReference": { "type": "object", "description": "Opaque host-owned correction handle; it grants no permission to apply an artifact.", "required": [ "id", "revision" ], "properties": { "id": { "type": "string" }, "revision": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ClientToolFileApproval": { "type": "string", "description": "Default handling of files retrieved by client tools before they leave the device.", "enum": [ "never_allow", "ask", "always_allow" ] }, "ClientToolPending": { "type": "object", "description": "Metadata-only suspension marker. Input and approved output use the normal\nToolUse part; this marker is never replayed as model context.", "required": [ "attempt_id", "tool_call_id", "pending_tool_calls" ], "properties": { "attempt_id": { "type": "string", "format": "uuid" }, "pending_tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/PendingToolCall" } }, "tool_call_id": { "type": "string" } } }, "ClientToolResultRequest": { "type": "object", "required": [ "chat_id", "message_id", "tool_call_id" ], "properties": { "chat_id": { "type": "string", "format": "uuid", "description": "The chat whose suspended generation is awaiting this result.", "example": "00000000-0000-0000-0000-000000000000" }, "error": { "type": "string", "description": "An error message if the client could not execute the tool. Provide this\nOR `result`." }, "file_upload_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Uploaded files to attach to the assistant message with rich previews and\nread with the normal file processor for this tool result. Each file is\nauthorized before reading or attaching. Duplicate IDs are ignored; at\nmost min(frontend.max_files, 20) unique files are considered." }, "message_id": { "type": "string", "format": "uuid", "description": "The id of the assistant message whose generation emitted the client\ntool call. Disambiguates a result from a task that has since been\nreplaced by a concurrent generation on the same chat.", "example": "00000000-0000-0000-0000-000000000000" }, "result": { "$ref": "#/components/schemas/Value", "description": "The tool's JSON result (any JSON value, including `null`). Provide this\nOR `error`. An absent field is treated as \"no result\"; an explicit\n`null` is a valid result." }, "submission_feedback": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ClientToolSubmissionFeedback", "description": "Optional host-owned correction handle and terminal rejection marker.\nOnly meaningful with nonempty validation_errors." } ] }, "tool_call_id": { "type": "string", "description": "The `tool_call_id` from the `client_tool_call` event being answered." }, "validation_errors": { "type": "array", "items": { "$ref": "#/components/schemas/ClientToolValidationIssue" }, "description": "Parser diagnostics for a rejected submission. Nonempty diagnostics are\na failure even if a result is also supplied. Messages should be concise;\nthe backend retains at most 16 issues with bounded field lengths." } } }, "ClientToolResultResponse": { "type": "object", "required": [ "delivered", "stored" ], "properties": { "delivered": { "type": "boolean", "description": "True if a suspended generation received this result; false if it was a\nbenign no-op (already delivered, timed out, aborted, or unknown id)." }, "stored": { "type": "boolean", "description": "True if this result settled a parked client operation, which the\nsender then continues." } } }, "ClientToolSubmissionFeedback": { "type": "object", "description": "Rejection metadata, distinct from a successful submission result.", "properties": { "draft": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ClientToolDraftReference" } ] }, "recovery": { "$ref": "#/components/schemas/SubmissionRecovery" }, "terminal": { "type": "boolean", "description": "Ends an opt-in submission turn without accepting an artifact." } } }, "ClientToolValidationIssue": { "type": "object", "description": "Compact, parser-owned diagnostics. `path` is a JSON Pointer into the tool\narguments (empty for the root); `code` is a stable validator error identifier.", "required": [ "path", "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" } } }, "CompactChatRequest": { "type": "object", "required": [ "expected_tip_message_id", "operation_id" ], "properties": { "expected_tip_message_id": { "type": "string", "format": "uuid" }, "operation_id": { "type": "string", "format": "uuid" }, "selected_facet_ids": { "type": "array", "items": { "type": "string" } }, "target_chat_provider_id": { "type": "string", "description": "Conversation model used for estimates and the soft target, not the summarizer." } }, "additionalProperties": false }, "CompactChatResponse": { "type": "object", "required": [ "message_id", "compaction" ], "properties": { "compaction": { "$ref": "#/components/schemas/ContentPartCompactionMarker" }, "message_id": { "type": "string", "format": "uuid" } } }, "CompleteClientOperationRequest": { "type": "object", "required": [ "claim_token", "result" ], "properties": { "claim_token": { "type": "string", "format": "uuid" }, "result": { "$ref": "#/components/schemas/OperationResult" } }, "additionalProperties": false }, "CompleteMcpServerOauthResponse": { "type": "object", "required": [ "connection_status" ], "properties": { "connection_status": { "$ref": "#/components/schemas/McpServerStatusValue" } } }, "CompleteRequest": { "type": "object", "required": [ "claimToken", "package" ], "properties": { "claimToken": { "type": "string", "format": "uuid" }, "package": { "$ref": "#/components/schemas/ApprovedExport" } }, "additionalProperties": false }, "ConsentPolicy": { "type": "string", "enum": [ "none", "ask", "native" ] }, "ContentPart": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ContentPartCompactionMarker" }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "compaction_marker" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ContentPartText" }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "text" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ContentPartReasoning" }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "reasoning" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ToolUse" }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "tool_use" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ContentPartToolApprovalRequest" }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "tool_approval_request" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ClientToolPending" }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "client_tool_pending" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ContentPartToolApproval" }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "tool_approval" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ContentPartToolRejection" }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "tool_rejection" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ContentPartTextFilePointer" }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "text_file_pointer" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ContentPartImageFilePointer" }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "image_file_pointer" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ContentPartImage" }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "image" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ContentPartActionFacetMarker", "description": "Reference to an action-facet directive that will be rendered fresh\nat request-build time. Persisted in `generation_input_messages` as a\nmetadata-only marker (facet id + invocation args) instead of the\nrendered template text — mirrors the `TextFilePointer` pattern.\nAction facets are request-scoped: when this marker is loaded as part\nof *prior-turn* history, the resolver drops it; for the *current\nturn* it renders the template against the current config + args." }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "action_facet_marker" ] } } } ], "description": "Reference to an action-facet directive that will be rendered fresh\nat request-build time. Persisted in `generation_input_messages` as a\nmetadata-only marker (facet id + invocation args) instead of the\nrendered template text — mirrors the `TextFilePointer` pattern.\nAction facets are request-scoped: when this marker is loaded as part\nof *prior-turn* history, the resolver drops it; for the *current\nturn* it renders the template against the current config + args." }, { "allOf": [ { "$ref": "#/components/schemas/ContentPartDelegationPreambleMarker", "description": "Reference to the run directive of a delegated chat, resolved the same\nway as `ActionFacetMarker`: metadata in the persisted snapshot, text\nonly in the request about to be sent, dropped when the snapshot is\nreplayed as prior-turn history." }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "delegation_preamble_marker" ] } } } ], "description": "Reference to the run directive of a delegated chat, resolved the same\nway as `ActionFacetMarker`: metadata in the persisted snapshot, text\nonly in the request about to be sent, dropped when the snapshot is\nreplayed as prior-turn history." }, { "allOf": [ { "$ref": "#/components/schemas/ContentPartTaskResult", "description": "The result of an `async` delegated task, delivered back into the chat\nthe task was started from as a user-role row.\n\nA user row rather than an assistant one because the model has to react\nto it: it is material that arrived, not something the assistant said.\nThe history walk keeps it (unlike the directive markers above, which\nare request-scoped) so later turns can still see what came back." }, { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "task_result" ] } } } ], "description": "The result of an `async` delegated task, delivered back into the chat\nthe task was started from as a user-role row.\n\nA user row rather than an assistant one because the model has to react\nto it: it is material that arrived, not something the assistant said.\nThe history walk keeps it (unlike the directive markers above, which\nare request-scoped) so later turns can still see what came back." } ] }, "ContentPartActionFacetMarker": { "type": "object", "required": [ "facet_id", "args" ], "properties": { "args": { "type": "object", "description": "Arguments captured at the time of the user's request (e.g. the\nselected text for `outlook_rewrite_selection`, the compose body for\n`outlook_review_draft`).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "facet_id": { "type": "string", "description": "Identifier of the action facet whose template should be rendered." } } }, "ContentPartCompactionMarker": { "type": "object", "description": "A durable context boundary. Its replacement snapshot is authoritative;\nthis metadata is only for display and retry identification.", "required": [ "version", "mode", "operation_id", "summarizer_chat_provider_id", "target_chat_provider_id", "before_tokens", "after_tokens", "before_files", "after_files", "retained_file_ids", "dropped_file_ids" ], "properties": { "after_files": { "type": "integer", "minimum": 0 }, "after_tokens": { "type": "integer", "minimum": 0 }, "before_files": { "type": "integer", "minimum": 0 }, "before_tokens": { "type": "integer", "minimum": 0 }, "dropped_file_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "mode": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid" }, "retained_file_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "summarizer_chat_provider_id": { "type": "string" }, "target_chat_provider_id": { "type": "string" }, "version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ContentPartDelegationPreambleMarker": { "type": "object", "description": "The structured-brief fields of a delegated run, copied from the chat's\nprovenance envelope at composition time. The preamble template itself is\nnot carried: it is read from the config in force when the marker resolves.", "properties": { "constraints": { "type": [ "string", "null" ] }, "expected_output": { "type": [ "string", "null" ] }, "run_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProvenanceRunMode", "description": "How the run relates to its origin turn; the preamble tells a background\ndelegate its answer is read in place rather than returned, and an async\none that its answer is delivered back later. Absent means awaited, so\nmarkers persisted before the field existed keep rendering the same text." } ] } } }, "ContentPartImage": { "type": "object", "required": [ "content_type", "base64_data" ], "properties": { "base64_data": { "type": "string" }, "content_type": { "type": "string" } } }, "ContentPartImageFilePointer": { "type": "object", "required": [ "file_upload_id" ], "properties": { "download_url": { "type": [ "string", "null" ] }, "file_upload_id": { "type": "string", "format": "uuid" }, "preview_url": { "type": [ "string", "null" ] } } }, "ContentPartReasoning": { "type": "object", "properties": { "ended_at": { "type": [ "string", "null" ], "default": null }, "started_at": { "type": [ "string", "null" ], "default": null }, "text": { "type": "string", "default": "" } } }, "ContentPartTaskResult": { "type": "object", "description": "A delivered task result, as it sits in the conversation.\n\n`summary` is the child's own answer, already bounded to\n`delegation.result_max_chars`, and is the only untrusted field here: the\nrest is written by the server. It is stored RAW — the untrusted-data frame\nand the safety guidance are applied when the conversation is composed for\nthe model, so the UI can render the answer plainly.", "required": [ "child_chat_id", "parent_tool_call_id", "status", "summary", "truncated", "sequence" ], "properties": { "child_chat_id": { "type": "string", "format": "uuid", "description": "The child chat that produced this result; the link the UI offers." }, "parent_tool_call_id": { "type": "string", "description": "The `delegate_task` call in the origin turn that started it." }, "reason": { "type": "string" }, "redeliveries": { "type": "integer", "format": "int32", "description": "How many times this same result was delivered again after the origin\nbranched away from an earlier delivery of it. `0` on every first-time\ndelivery, including a parked run's follow-up answer.", "minimum": 0 }, "sequence": { "type": "integer", "format": "int32", "description": "Which delivery for this task this is. `0` is the first, and every\nfurther delivery of the same run bumps it — including the answer a\nparked `async` run delivers after its card is decided, which is a\nSECOND result and not the first one repeated. `redeliveries` is the\nfield that says \"you have seen this before\".", "minimum": 0 }, "status": { "type": "string", "description": "Terminal status of the run, from the D-K vocabulary." }, "summary": { "type": "string", "description": "The child's answer, bounded. Untrusted." }, "truncated": { "type": "boolean", "description": "Whether `summary` was shortened to fit." } } }, "ContentPartText": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } } }, "ContentPartTextFilePointer": { "type": "object", "required": [ "file_upload_id" ], "properties": { "file_upload_id": { "type": "string", "format": "uuid" } } }, "ContentPartToolApproval": { "type": "object", "description": "Records a user approval in the assistant message lifecycle.", "required": [ "tool_call_id", "approved_at" ], "properties": { "always_allow": { "type": "boolean" }, "approval_id": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "child_chat_id": { "type": [ "string", "null" ], "format": "uuid" }, "tool_call_id": { "type": "string" }, "user_tool_approval_setting_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "ContentPartToolApprovalRequest": { "type": "object", "description": "A durable request for user approval before an MCP tool call is executed.", "required": [ "tool_call_id", "tool_name", "mcp_server_id", "input", "annotations", "preset", "allow_always", "requested_at" ], "properties": { "allow_always": { "type": "boolean", "description": "Snapshot the global policy so the client can hide the option when\npersistent approval settings are disabled." }, "annotations": { "$ref": "#/components/schemas/ToolApprovalAnnotations" }, "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalItem" }, "description": "Every decision this stop covers. An `mcp_tool` stop carries one item\ndescribing the same call as the flat fields above; readers that branch\non `kind` first may use either." }, "display": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ToolDisplayMetadata" } ] }, "input": { "$ref": "#/components/schemas/Value" }, "kind": { "$ref": "#/components/schemas/ToolApprovalKind" }, "mcp_server_id": { "type": "string" }, "pending_tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/PendingToolCall" } }, "preset": { "type": "string" }, "requested_at": { "type": "string" }, "tool_call_id": { "type": "string" }, "tool_name": { "type": "string" } } }, "ContentPartToolRejection": { "type": "object", "description": "Records a user rejection in the assistant message lifecycle.", "required": [ "tool_call_id", "rejected_at" ], "properties": { "approval_id": { "type": [ "string", "null" ] }, "child_chat_id": { "type": [ "string", "null" ], "format": "uuid" }, "never_allow": { "type": "boolean", "description": "Both fields default, so rejections stored before standing denials\nexisted still parse." }, "reason": { "type": [ "string", "null" ], "description": "Why the call was rejected when the user did not decide it directly.\nThe only value is `withdrawn`." }, "rejected_at": { "type": "string" }, "tool_call_id": { "type": "string" }, "user_tool_approval_setting_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "ContextRequest": { "type": "object", "required": [ "deviceId", "challenge" ], "properties": { "challenge": { "type": "string" }, "deviceId": { "type": "string" } }, "additionalProperties": false }, "ContinueStreamRequest": { "type": "object", "description": "Rehydrates a generation that was deliberately stopped for tool approval.\n\nA stop can cover several decisions, so the body names each one. The legacy\nshape `{ message_id, decision }` carries no `approval_id` and is therefore\naccepted only while exactly one approval is open — otherwise it would have\nto guess which call the user answered.", "required": [ "message_id" ], "properties": { "decision": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ToolApprovalDecision" } ] }, "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalDecisionItem" } }, "message_id": { "type": "string", "format": "uuid", "description": "The assistant message/generation that contains the pending approval request." } } }, "Coverage": { "type": "string", "enum": [ "complete", "partial", "unavailable" ] }, "CoveredByParentError": { "type": "object", "description": "Body of the `409` `continuestream` answers on a delegated child whose\nrequest is currently being asked about in the chat that started it.\n\n`parent_message_id` is where the question actually is: the client follows it\nrather than telling the user their own chat is broken.", "required": [ "code", "parent_message_id" ], "properties": { "code": { "type": "string", "description": "Always `covered_by_parent`." }, "parent_message_id": { "type": "string", "format": "uuid", "description": "The origin row whose approval part carries this child's request." } } }, "CreateAssistantRequest": { "type": "object", "description": "Request to create a new assistant", "required": [ "name", "prompt" ], "properties": { "default_chat_provider": { "type": [ "string", "null" ], "description": "Default chat provider/model ID for this assistant" }, "description": { "type": [ "string", "null" ], "description": "Optional description of the assistant" }, "enforce_facet_settings": { "type": "boolean", "description": "Whether chats derived from this assistant must use the configured facets" }, "facet_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Optional list of facet IDs to configure for this assistant" }, "file_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Optional list of file upload IDs to associate with this assistant" }, "mcp_server_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List of MCP server IDs available to this assistant" }, "name": { "type": "string", "description": "The name of the assistant" }, "prompt": { "type": "string", "description": "The system prompt for the assistant" }, "share_grants": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ShareGrantInput" }, "description": "Optional list of share grants to create with the assistant" } } }, "CreateAssistantResponse": { "allOf": [ { "$ref": "#/components/schemas/AssistantWithFiles", "description": "The created assistant with files" } ], "description": "Response when creating an assistant" }, "CreateChatRequest": { "type": "object", "description": "Request to create a new chat without an initial message", "properties": { "assistant_id": { "type": "string", "description": "Optional assistant ID to base this chat on" }, "title_by_user_provided": { "type": "string", "description": "Optional user-specified display name for the chat.\nIf set, this takes precedence over auto-generated summary titles." } } }, "CreateChatResponse": { "type": "object", "description": "Response for create_chat endpoint", "required": [ "chat_id" ], "properties": { "chat_id": { "type": "string", "description": "The ID of the newly created chat" } } }, "CreateShareGrantRequest": { "type": "object", "description": "Request to create a new share grant", "required": [ "resource_type", "resource_id", "subject_type", "subject_id_type", "subject_id", "role" ], "properties": { "resource_id": { "type": "string", "description": "The ID of the resource to share" }, "resource_type": { "type": "string", "description": "The type of resource to share (e.g., \"assistant\")" }, "role": { "type": "string", "description": "The role to grant (\"viewer\" or \"editor\")" }, "subject_id": { "type": "string", "description": "The ID of the subject to grant access to. Organization-wide grants use \"__organization__\"." }, "subject_id_type": { "type": "string", "description": "The type of subject ID (e.g., \"id\", \"organization_group_id\", or \"organization_id\")" }, "subject_type": { "type": "string", "description": "The type of subject to grant access to (e.g., \"user\", \"organization_group\", or \"organization\")" } } }, "CreateShareGrantResponse": { "allOf": [ { "$ref": "#/components/schemas/ShareGrant", "description": "The created share grant" } ], "description": "Response when creating a share grant" }, "CreateUserToolApprovalSettingRequest": { "type": "object", "required": [ "mcp_server_id", "tool_name" ], "properties": { "decision": { "$ref": "#/components/schemas/UserToolDecision", "description": "Defaults to `always_allow`, which is what pre-existing clients meant." }, "mcp_server_id": { "type": "string" }, "tool_name": { "type": "string" } } }, "DelegationRunMode": { "type": "string", "description": "How a delegated child run relates to the turn that spawned it: `wait`\nblocks the turn on the child and feeds the result back into it,\n`background` returns at launch and the child result never re-enters the\nturn.", "enum": [ "wait", "background" ] }, "DesktopSidecarDistributionFileResponse": { "type": "object", "required": [ "id", "kind", "download_filename", "media_type", "size" ], "properties": { "download_filename": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "media_type": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 } } }, "DesktopSidecarDistributionPlatformResponse": { "type": "object", "required": [ "os", "architecture", "abi" ], "properties": { "abi": { "type": "string" }, "architecture": { "type": "string" }, "os": { "type": "string" } } }, "DesktopSidecarDistributionResponse": { "type": "object", "required": [ "targets" ], "properties": { "targets": { "type": "array", "items": { "$ref": "#/components/schemas/DesktopSidecarDistributionTargetResponse" } } } }, "DesktopSidecarDistributionTargetResponse": { "type": "object", "required": [ "id", "platform", "default_file", "files" ], "properties": { "default_file": { "type": "string" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/DesktopSidecarDistributionFileResponse" } }, "id": { "type": "string" }, "platform": { "$ref": "#/components/schemas/DesktopSidecarDistributionPlatformResponse" } } }, "DesktopSidecarOrganizationConfiguration": { "type": "object", "properties": { "show_tray_icon": { "type": [ "boolean", "null" ], "description": "Whether the desktop sidecar should show its system tray icon.\n\nWhen unset, the sidecar uses its user configuration or built-in default." } } }, "DisconnectMcpServerOauthResponse": { "type": "object", "required": [ "connection_status" ], "properties": { "connection_status": { "$ref": "#/components/schemas/McpServerStatusValue" } } }, "Drive": { "type": "object", "description": "A drive accessible to the user (OneDrive, Sharepoint, etc.)", "required": [ "id", "name", "drive_type", "kind" ], "properties": { "drive_type": { "type": "string", "description": "The type of drive (e.g., \"personal\", \"documentLibrary\")" }, "group_visibility": { "type": "string", "description": "The Microsoft 365 group visibility for group-backed libraries, if available" }, "id": { "type": "string", "description": "The unique ID of the drive" }, "kind": { "type": "string", "description": "Best-effort classification of the drive based on Graph drive, site, and group metadata" }, "name": { "type": "string", "description": "The display name of the drive" }, "owner_name": { "type": "string", "description": "The owner of the drive, if available" }, "site_name": { "type": "string", "description": "The SharePoint site name for document libraries, if available" }, "web_url": { "type": "string", "description": "The web URL to access this drive in OneDrive/SharePoint" } } }, "DriveItem": { "type": "object", "description": "A drive item (file or folder)", "required": [ "id", "name", "is_folder" ], "properties": { "id": { "type": "string", "description": "The unique ID of the item" }, "is_folder": { "type": "boolean", "description": "Whether this item is a folder" }, "last_modified": { "type": "string", "format": "date-time", "description": "When the item was last modified" }, "mime_type": { "type": "string", "description": "The MIME type (for files)" }, "name": { "type": "string", "description": "The name of the item" }, "size": { "type": "integer", "format": "int64", "description": "The size in bytes (for files)" }, "web_url": { "type": "string", "description": "The web URL to access this item" } } }, "DriveItemResponse": { "allOf": [ { "$ref": "#/components/schemas/DriveItem", "description": "The drive item details" }, { "type": "object", "required": [ "drive_id" ], "properties": { "drive_id": { "type": "string", "description": "The drive ID this item belongs to" } } } ], "description": "Response for a single drive item" }, "DriveItemsResponse": { "type": "object", "description": "Response for drive items endpoints", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DriveItem" }, "description": "List of items in the drive or folder" } } }, "EditMessageRequest": { "type": "object", "required": [ "message_id", "replace_user_message" ], "properties": { "action_facet": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ActionFacetRequest", "description": "Optional action facet to apply during this generation." } ] }, "chat_provider_id": { "type": "string", "description": "The ID of the chat provider to use for generation. If not provided, will use the highest priority model for the user.", "example": "primary" }, "delegation_run_mode": { "$ref": "#/components/schemas/DelegationRunMode", "description": "How delegated runs spawned by this message are awaited. Defaults to\n`wait`; `background` requires `delegation.allow_background`\nand is downgraded to `wait` server-side when the gate is off." }, "mentioned_assistant_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Assistants the user @-mentioned in this message as delegation targets.\nValidated server-side; requires `delegation.assistants.enabled`." }, "message_id": { "type": "string", "format": "uuid", "description": "The ID of the message that should be edited with a new response. It will be considered a sibling message to the new message.", "example": "00000000-0000-0000-0000-000000000000" }, "replace_input_files_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The IDs of any files that should replace the input files. These files must already be uploaded to the file_uploads table.", "example": "[\"00000000-0000-0000-0000-000000000000\"]" }, "replace_user_message": { "type": "string", "description": "The text of the message that should replace the user message.", "example": "Hello, world!" }, "selected_facet_ids": { "type": "array", "items": { "type": "string" }, "description": "IDs of facets selected by the user for this generation." } } }, "EditMessageStreamingResponseMessage": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseAssistantMessageStarted", "description": "Sent when the assistant message entry has been created, before generation starts." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "assistant_message_started" ] } } } ], "description": "Sent when the assistant message entry has been created, before generation starts." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessageComplete", "description": "Sent when the assistant's response has been saved in full." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "assistant_message_completed" ] } } } ], "description": "Sent when the assistant's response has been saved in full." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessageTextDelta", "description": "Sent whenever a new text chunk is generated by the assistant." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "text_delta" ] } } } ], "description": "Sent whenever a new text chunk is generated by the assistant." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessageReasoningDelta", "description": "Sent whenever a new reasoning chunk is generated by the assistant." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "reasoning_delta" ] } } } ], "description": "Sent whenever a new reasoning chunk is generated by the assistant." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseToolCallProposed", "description": "Sent when the LLM proposes a tool call to be part of the assistant message." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "tool_call_proposed" ] } } } ], "description": "Sent when the LLM proposes a tool call to be part of the assistant message." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseToolCallUpdate", "description": "Sent to update the status of a tool call execution by the backend." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "tool_call_update" ] } } } ], "description": "Sent to update the status of a tool call execution by the backend." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseClientToolCall", "description": "Sent when the model calls a facet client tool: the turn is suspended\nuntil the client executes it and POSTs the result back." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "client_tool_call" ] } } } ], "description": "Sent when the model calls a facet client tool: the turn is suspended\nuntil the client executes it and POSTs the result back." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseError", "description": "Sent when an error occurs during message generation." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "error" ] } } } ], "description": "Sent when an error occurs during message generation." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseUserMessageSaved", "description": "Sent when the edited user message has been saved." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "user_message_saved" ] } } } ], "description": "Sent when the edited user message has been saved." } ] }, "ExecutionRealm": { "type": "string", "enum": [ "frontend", "office-addin", "desktop-sidecar" ] }, "ExecutorBinding": { "type": "object", "description": "Client-asserted routing identity, not attestation. Kinds may require stronger proof.", "required": [ "device_id", "realm" ], "properties": { "device_id": { "type": "string" }, "host_context": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HostContext" } ] }, "realm": { "$ref": "#/components/schemas/ExecutionRealm" } }, "additionalProperties": false }, "FacetInfo": { "type": "object", "required": [ "id", "display_name", "default_enabled" ], "properties": { "default_enabled": { "type": "boolean" }, "display_name": { "type": "string" }, "icon": { "type": "string" }, "id": { "type": "string" } } }, "FacetsResponse": { "type": "object", "required": [ "global_facet_settings", "facets" ], "properties": { "action_facets": { "type": "array", "items": { "$ref": "#/components/schemas/ActionFacetInfo" } }, "facets": { "type": "array", "items": { "$ref": "#/components/schemas/FacetInfo" } }, "global_facet_settings": { "$ref": "#/components/schemas/GlobalFacetSettings" } } }, "FeedbackSentiment": { "type": "string", "description": "Sentiment for message feedback", "enum": [ "positive", "negative" ] }, "FileCapabilitiesQuery": { "type": "object", "properties": { "model_id": { "type": [ "string", "null" ], "description": "Optional model ID to get capabilities specific to that model" } } }, "FileCapability": { "type": "object", "description": "Represents what operations can be performed on files with specific types", "required": [ "id", "extensions", "mime_types", "operations" ], "properties": { "extensions": { "type": "array", "items": { "type": "string" }, "description": "File extensions this capability applies to (e.g., [\"docx\", \"doc\"])\nSpecial value \"*\" indicates all extensions" }, "id": { "type": "string", "description": "Stable identifier (e.g., 'word', 'pdf', 'image', 'other')" }, "mime_types": { "type": "array", "items": { "type": "string" }, "description": "MIME types this capability applies to (e.g., [\"application/vnd.openxmlformats-officedocument.wordprocessingml.document\"])\nMay contain wildcards like \"image/*\" or \"*/*\"" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/FileOperation" }, "description": "Operations that can be performed on matching files" }, "upload_allowed": { "type": "boolean", "description": "Whether this file type may be uploaded under the active deployment policy." } } }, "FileOperation": { "type": "string", "description": "Operations that can be performed on files", "enum": [ "extract_text", "analyze_image" ] }, "FileReference": { "type": "object", "description": "Minimal file reference containing only the file ID", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The unique ID of the file" } } }, "FileUploadItem": { "type": "object", "description": "Response for file upload", "required": [ "id", "filename", "download_url", "file_contents_unavailable_missing_permissions", "is_sharepoint_file", "file_capability" ], "properties": { "audio_transcription": { "$ref": "#/components/schemas/AudioTranscriptionMetadata", "description": "Optional audio transcription metadata for supported audio uploads." }, "download_url": { "type": "string", "description": "Pre-signed URL for downloading the file directly from storage" }, "external_id_ews_id": { "type": "string", "description": "External Exchange Web Services ID for deep linking to the original item." }, "file_capability": { "$ref": "#/components/schemas/FileCapability", "description": "The file capability that was evaluated for this file" }, "file_contents_unavailable_missing_permissions": { "type": "boolean", "description": "Indicates that file contents are unavailable for the current user due to missing permissions." }, "filename": { "type": "string", "description": "The original filename of the uploaded file" }, "id": { "type": "string", "description": "The unique ID of the uploaded file" }, "is_sharepoint_file": { "type": "boolean", "description": "Indicates the file is stored in Sharepoint" }, "outlook_provenance": { "$ref": "#/components/schemas/OutlookFileProvenance", "description": "Outlook source references for reopening the original email." }, "preview_url": { "type": [ "string", "null" ], "description": "Proxied URL for inline preview without forcing download when available" } } }, "FileUploadResponse": { "type": "object", "description": "Response for file upload", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileUploadItem" }, "description": "The list of uploaded files with their IDs and filenames" }, "rejected_files": { "type": "array", "items": { "type": "string" }, "description": "Filenames skipped by the configured operation policy." } } }, "FrequentAssistantItem": { "allOf": [ { "$ref": "#/components/schemas/AssistantWithFiles", "description": "The assistant details" }, { "type": "object", "required": [ "usage_count" ], "properties": { "usage_count": { "type": "integer", "format": "int64", "description": "Number of times this assistant was used to create chats" } } } ], "description": "A frequently used assistant with usage statistics" }, "FrequentAssistantsResponse": { "type": "object", "description": "Response for the frequent_assistants endpoint", "required": [ "assistants" ], "properties": { "assistants": { "type": "array", "items": { "$ref": "#/components/schemas/FrequentAssistantItem" }, "description": "The list of frequently used assistants" } } }, "GeneratingChat": { "type": "object", "description": "A chat with a running or recently finished generation", "required": [ "chat_id", "state", "started_at" ], "properties": { "chat_id": { "type": "string", "description": "The unique ID of the chat" }, "ended_at": { "type": "string", "format": "date-time", "description": "When the generation reached its terminal state" }, "initiator": { "$ref": "#/components/schemas/GenerationInitiator", "description": "Who started the generation this row describes. Absent means a person\ndid — including every generation written before the field existed." }, "started_at": { "type": "string", "format": "date-time", "description": "When the generation started" }, "state": { "$ref": "#/components/schemas/GenerationChatState", "description": "Current state of the chat's generation" }, "title": { "type": "string", "description": "Resolved chat title (user-provided title takes precedence over the\ngenerated summary title), when one exists" } } }, "GeneratingChatsResponse": { "type": "object", "description": "Response for the generating_chats endpoint", "required": [ "chats" ], "properties": { "chats": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratingChat" }, "description": "Chats with a running or recently finished generation" } } }, "GenerationChatState": { "type": "string", "description": "State of a chat's most recent generation", "enum": [ "running", "completed", "errored", "action_required" ] }, "GenerationErrorType": { "oneOf": [ { "type": "object", "description": "Content was filtered by the model provider's content policy.", "required": [ "error_description", "error_type" ], "properties": { "error_description": { "type": "string", "description": "Description of why the content was filtered." }, "error_type": { "type": "string", "enum": [ "content_filter" ] }, "filter_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value", "description": "Additional details about which filters were triggered." } ] } } }, { "type": "object", "description": "Rate limit was exceeded.", "required": [ "error_description", "error_type" ], "properties": { "error_description": { "type": "string", "description": "Description of the rate limit error." }, "error_type": { "type": "string", "enum": [ "rate_limit" ] } } }, { "type": "object", "description": "Model or provider is unavailable.", "required": [ "error_description", "error_type" ], "properties": { "error_description": { "type": "string", "description": "Description of the availability issue." }, "error_type": { "type": "string", "enum": [ "model_unavailable" ] } } }, { "type": "object", "description": "Invalid request parameters.", "required": [ "error_description", "error_type" ], "properties": { "error_description": { "type": "string", "description": "Description of what was invalid." }, "error_type": { "type": "string", "enum": [ "invalid_request" ] } } }, { "type": "object", "description": "Generic error from the model provider.", "required": [ "error_description", "error_type" ], "properties": { "error_description": { "type": "string", "description": "Description of the provider error." }, "error_type": { "type": "string", "enum": [ "provider_error" ] }, "status_code": { "type": [ "integer", "null" ], "format": "int32", "description": "HTTP status code if available.", "minimum": 0 } } }, { "type": "object", "description": "Generation was aborted because a hallucination loop was detected.", "required": [ "error_description", "error_type" ], "properties": { "error_description": { "type": "string", "description": "Description of why generation was aborted." }, "error_type": { "type": "string", "enum": [ "hallucination_loop" ] } } }, { "type": "object", "description": "Internal server error.", "required": [ "error_description", "error_type" ], "properties": { "error_description": { "type": "string", "description": "Description of the internal error." }, "error_type": { "type": "string", "enum": [ "internal_error" ] } } } ], "description": "Represents different types of errors that can occur during message generation." }, "GenerationInitiator": { "type": "string", "description": "Who started a generation.\n\nAbsent means a person did, so rows written before this existed keep their\nmeaning without a migration.", "enum": [ "user", "task_result" ] }, "GenerationRunningError": { "type": "object", "description": "Body of the `409` a streaming route answers when the chat's generation\nlease is already held.\n\n`code` is what the client discriminates on: the same status is also used\nfor archived chats and for live delegated runs, which stay plain text.", "required": [ "code", "chat_id", "initiator" ], "properties": { "chat_id": { "type": "string", "format": "uuid", "description": "The chat whose lease is held." }, "code": { "type": "string", "description": "Always `generation_running`." }, "initiator": { "type": "string", "description": "Who started the generation holding the lease. Always `user` until\nsystem-initiated deliveries persist their own marker." }, "started_at": { "type": [ "string", "null" ], "description": "When the holding generation started, RFC 3339, when the row records it." } } }, "GlobalFacetSettings": { "type": "object", "required": [ "only_single_facet", "show_facet_indicator_with_display_name" ], "properties": { "only_single_facet": { "type": "boolean", "description": "Whether one or multiple facets may be selected" }, "show_facet_indicator_with_display_name": { "type": "boolean", "description": "Whether to show facet indicator with display name" } } }, "HostContext": { "type": "object", "required": [ "kind", "identity" ], "properties": { "identity": { "type": "string" }, "kind": { "type": "string" } }, "additionalProperties": false }, "InclusionMode": { "type": "string", "enum": [ "full", "preview", "reference_only" ] }, "LinkFileRequest": { "type": "object", "description": "Request to link an external file (SharePoint, Google Drive, etc.)", "required": [ "source", "provider_metadata" ], "properties": { "chat_id": { "type": [ "string", "null" ], "description": "Optional chat ID to associate the file with. If not provided, creates standalone files." }, "provider_metadata": { "$ref": "#/components/schemas/SharepointProviderMetadata", "description": "Provider-specific metadata (e.g., drive_id, item_id for SharePoint)" }, "source": { "type": "string", "description": "The source/provider type: \"sharepoint\" (future: \"google_drive\", etc.)" } } }, "ListClientOperationsResponse": { "type": "object", "required": [ "account_id", "enabled", "operations" ], "properties": { "account_id": { "type": "string" }, "after": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/ClientOperationView" } } } }, "ListMcpServerToolsResponse": { "type": "object", "required": [ "server_id", "status", "allow_always", "ask_available", "tools" ], "properties": { "allow_always": { "type": "boolean", "description": "Whether the approval policy honors persistent \"always allow\" grants;\na settings surface offers that decision only when this is set, the\nsame way the in-chat approval card does." }, "ask_available": { "type": "boolean", "description": "Whether a stored \"ask\" decision is honored: it needs the approval\ngate, so with approvals disabled the decision is stored but inert." }, "server_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/McpServerStatusValue" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpServerTool" }, "description": "Empty unless `status` is `SUCCESS`; sorted by title." } } }, "ListMcpServersResponse": { "type": "object", "required": [ "servers" ], "properties": { "servers": { "type": "array", "items": { "$ref": "#/components/schemas/McpServerStatus" } } } }, "ListShareGrantsResponse": { "type": "object", "description": "Response when listing share grants", "required": [ "grants" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/ShareGrant" }, "description": "The list of share grants" } } }, "McpServerStatus": { "type": "object", "required": [ "id", "authentication_mode", "connection_status" ], "properties": { "authentication_mode": { "type": "string" }, "connection_status": { "$ref": "#/components/schemas/McpServerStatusValue" }, "id": { "type": "string" } } }, "McpServerStatusValue": { "type": "string", "enum": [ "SUCCESS", "FAILURE", "NEEDS_AUTHENTICATION" ] }, "McpServerTool": { "type": "object", "description": "One tool as the server declares it. `title` and `description` are vendor\ntext passed through `sanitize_display_text`; a client shows them as plain\ntext and never interprets them. `name` is the tool's identity, not display\ntext: a client sends it back unchanged when it stores a decision or\nswitches the tool off for a chat, and every gate compares it byte for byte\nwith the name the server declares.", "required": [ "name", "title", "description_truncated", "annotations", "policy", "user_decision", "effective", "is_wait_tool" ], "properties": { "annotations": { "$ref": "#/components/schemas/McpServerToolAnnotations" }, "description": { "type": [ "string", "null" ] }, "description_truncated": { "type": "boolean", "description": "Whether the description was cut at the display cap." }, "effective": { "$ref": "#/components/schemas/McpToolEffectiveState", "description": "What happens on the next call; a client renders this rather than\nre-deriving it from the other two." }, "is_wait_tool": { "type": "boolean" }, "name": { "type": "string", "description": "The name the server declares, verbatim; the key a client echoes back." }, "policy": { "$ref": "#/components/schemas/McpServerToolPolicy", "description": "The policy's own verdict, before any user decision." }, "title": { "type": "string", "description": "Display text: the server's title, else its annotation title, else the\nname, each cleaned; the first that survives cleaning." }, "user_decision": { "$ref": "#/components/schemas/McpServerToolUserDecision" } } }, "McpServerToolAnnotations": { "type": "object", "description": "MCP tool hints with absent values normalized to the protocol defaults.", "required": [ "read_only_hint", "destructive_hint", "idempotent_hint", "open_world_hint", "annotated", "sources" ], "properties": { "annotated": { "type": "boolean", "description": "Whether effective annotations are present, from the server or operator\nconfiguration. This flag does not describe their source." }, "destructive_hint": { "type": "boolean" }, "idempotent_hint": { "type": "boolean" }, "open_world_hint": { "type": "boolean" }, "read_only_hint": { "type": "boolean" }, "sources": { "$ref": "#/components/schemas/McpToolAnnotationSources", "description": "The winning declaration for each hint, resolved by the backend." } } }, "McpServerToolPolicy": { "type": "string", "description": "What the configured approval policy does before running the tool.", "enum": [ "auto", "ask" ] }, "McpServerToolUserDecision": { "type": "string", "description": "The requesting user's stored decision for the tool, whether or not the\npolicy currently honors it.", "enum": [ "none", "always_allow", "ask", "denied" ] }, "McpToolAnnotationSource": { "type": "string", "description": "The winning declaration for one effective MCP tool hint.", "enum": [ "tool_override", "server_override", "global_override", "server_supplied", "tool_default", "server_default", "global_default", "protocol_default" ] }, "McpToolAnnotationSources": { "type": "object", "description": "Sources are independent: a tool can inherit each hint from a different scope.", "required": [ "read_only_hint", "destructive_hint", "idempotent_hint", "open_world_hint" ], "properties": { "destructive_hint": { "$ref": "#/components/schemas/McpToolAnnotationSource" }, "idempotent_hint": { "$ref": "#/components/schemas/McpToolAnnotationSource" }, "open_world_hint": { "$ref": "#/components/schemas/McpToolAnnotationSource" }, "read_only_hint": { "$ref": "#/components/schemas/McpToolAnnotationSource" } } }, "McpToolEffectiveState": { "type": "string", "description": "What actually happens when the tool is called, once the user's stored\ndecision is laid over the policy verdict.", "enum": [ "allow", "ask", "denied" ] }, "MentionedAssistant": { "type": "object", "description": "An assistant the user @-mentioned in a message, resolved for display.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "The unique ID of the mentioned assistant" }, "name": { "type": "string", "description": "The assistant's display name at read time" } } }, "Message": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } }, "MessageFeedback": { "type": "object", "description": "Message feedback response", "required": [ "id", "sentiment", "created_at", "updated_at" ], "properties": { "comment": { "type": [ "string", "null" ], "description": "Optional comment text" }, "created_at": { "type": "string", "format": "date-time", "description": "When the feedback was created" }, "id": { "type": "string", "description": "The unique ID of the feedback" }, "sentiment": { "$ref": "#/components/schemas/FeedbackSentiment", "description": "Sentiment of the feedback" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the feedback was last updated" } } }, "MessageFeedbackRequest": { "type": "object", "description": "Request to submit or update message feedback", "required": [ "sentiment" ], "properties": { "comment": { "type": [ "string", "null" ], "description": "Optional comment text" }, "sentiment": { "$ref": "#/components/schemas/FeedbackSentiment", "description": "Sentiment of the feedback (positive or negative)" } } }, "MessageSubmitRequest": { "type": "object", "required": [ "user_message" ], "properties": { "action_facet": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ActionFacetRequest", "description": "Optional action facet to apply during this generation." } ] }, "assistant_id": { "type": "string", "format": "uuid", "description": "Optional assistant ID to associate with the chat when creating a new chat.\nIf provided with an existing_chat_id, this field is ignored.", "example": "00000000-0000-0000-0000-000000000000" }, "chat_provider_id": { "type": "string", "description": "The ID of the chat provider to use for generation. If not provided, will use the highest priority model for the user.", "example": "primary" }, "delegation_run_mode": { "$ref": "#/components/schemas/DelegationRunMode", "description": "How delegated runs spawned by this message are awaited. Defaults to\n`wait`; `background` requires `delegation.allow_background`\nand is downgraded to `wait` server-side when the gate is off." }, "disabled_mcp_server_ids": { "type": "array", "items": { "type": "string" }, "description": "MCP servers a newly created chat starts with switched off; their tools\nare withheld from the model. Ignored when existing_chat_id is\nprovided; `PUT /me/chats/{chat_id}` changes the list on an existing\nchat." }, "disabled_mcp_tools": { "type": "array", "items": { "type": "string" }, "description": "`server/tool` patterns of MCP tools a newly created chat starts with\nswitched off; matching tools are withheld from the model. Ignored when\nexisting_chat_id is provided; `PUT /me/chats/{chat_id}` changes the\nlist on an existing chat." }, "existing_chat_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of an existing chat to use. If provided, the chat with this ID will be used instead of creating a new one.\nThis is useful for scenarios where you have created a chat first (e.g. for file uploads) before sending the first message.", "example": "00000000-0000-0000-0000-000000000000" }, "input_files_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The IDs of any files attached to this message. These files must already be uploaded to the file_uploads table.\nThe files should normally only be provided with the first message they appear in the chat. After that they can assumed to be part of the chat history.", "example": "[\"00000000-0000-0000-0000-000000000000\"]" }, "mcp_write_tools_enabled": { "type": "boolean", "description": "Whether a newly created chat offers the model MCP write tools and\nclient actions. Defaults to enabled. Ignored when existing_chat_id is\nprovided; `PUT /me/chats/{chat_id}` changes it on an existing chat." }, "mentioned_assistant_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Assistants the user @-mentioned in this message as delegation targets.\nValidated server-side; requires `delegation.assistants.enabled`." }, "previous_message_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of the message that this message is a response to. If this is the first message in the chat, this should be empty.", "example": "00000000-0000-0000-0000-000000000000" }, "selected_facet_ids": { "type": "array", "items": { "type": "string" }, "description": "IDs of facets selected by the user for this generation." }, "title_by_user_provided": { "type": "string", "description": "Optional user-specified display name for a newly created chat.\nIgnored when existing_chat_id is provided." }, "user_message": { "type": "string", "description": "The text of the message.", "example": "Hello, world!" } } }, "MessageSubmitStreamingResponseAssistantMessageStarted": { "type": "object", "required": [ "message_id" ], "properties": { "message_id": { "type": "string", "format": "uuid" } } }, "MessageSubmitStreamingResponseChatCreated": { "type": "object", "required": [ "chat_id" ], "properties": { "chat_id": { "type": "string", "format": "uuid" } } }, "MessageSubmitStreamingResponseClientToolCall": { "type": "object", "description": "Sent when the model calls a facet `client_tool`: the generation is suspended\nuntil the client executes the tool and POSTs the result back to the\ncontinuation endpoint. Distinct from `tool_call_proposed` (which fires for\nevery proposed tool call) — this is the signal to execute on the client.", "required": [ "message_id", "content_index", "tool_call_id", "tool_name" ], "properties": { "content_index": { "type": "integer", "minimum": 0 }, "input": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "message_id": { "type": "string", "format": "uuid" }, "tool_call_id": { "type": "string" }, "tool_name": { "type": "string" } } }, "MessageSubmitStreamingResponseError": { "allOf": [ { "$ref": "#/components/schemas/GenerationErrorType", "description": "The error details." }, { "type": "object", "properties": { "message_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The message ID if available (may not be present if error occurred before message creation)." } } } ] }, "MessageSubmitStreamingResponseMessage": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseChatCreated", "description": "May optionally be sent at the start of the stream to indicate that a new chat has been created." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "chat_created" ] } } } ], "description": "May optionally be sent at the start of the stream to indicate that a new chat has been created." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseUserMessageSaved", "description": "Sent at the start of the stream to indicate that the user's message has been saved." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "user_message_saved" ] } } } ], "description": "Sent at the start of the stream to indicate that the user's message has been saved." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseAssistantMessageStarted", "description": "Sent when the assistant message entry has been created, before generation starts." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "assistant_message_started" ] } } } ], "description": "Sent when the assistant message entry has been created, before generation starts." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessageComplete", "description": "Sent when the assistant's response has been saved in full." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "assistant_message_completed" ] } } } ], "description": "Sent when the assistant's response has been saved in full." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessageTextDelta", "description": "Sent whenever a new text chunk is generated by the assistant." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "text_delta" ] } } } ], "description": "Sent whenever a new text chunk is generated by the assistant." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessageReasoningDelta", "description": "Sent whenever a new reasoning chunk is generated by the assistant." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "reasoning_delta" ] } } } ], "description": "Sent whenever a new reasoning chunk is generated by the assistant." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseToolCallProposed", "description": "Sent when the LLM proposes a tool call to be part of the assistant message." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "tool_call_proposed" ] } } } ], "description": "Sent when the LLM proposes a tool call to be part of the assistant message." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseToolCallUpdate", "description": "Sent to update the status of a tool call execution by the backend." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "tool_call_update" ] } } } ], "description": "Sent to update the status of a tool call execution by the backend." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseClientToolCall", "description": "Sent when the model calls a facet client tool: the turn is suspended\nuntil the client executes it and POSTs the result back." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "client_tool_call" ] } } } ], "description": "Sent when the model calls a facet client tool: the turn is suspended\nuntil the client executes it and POSTs the result back." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseError", "description": "Sent when an error occurs during message generation." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "error" ] } } } ], "description": "Sent when an error occurs during message generation." } ] }, "MessageSubmitStreamingResponseMessageComplete": { "type": "object", "required": [ "message_id", "content", "message" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPart" } }, "message": { "$ref": "#/components/schemas/ChatMessage" }, "message_id": { "type": "string", "format": "uuid" } } }, "MessageSubmitStreamingResponseMessageReasoningDelta": { "type": "object", "required": [ "message_id", "content_index", "new_text" ], "properties": { "content_index": { "type": "integer", "minimum": 0 }, "message_id": { "type": "string", "format": "uuid" }, "new_text": { "type": "string" } } }, "MessageSubmitStreamingResponseMessageTextDelta": { "type": "object", "required": [ "message_id", "content_index", "new_text" ], "properties": { "content_index": { "type": "integer", "minimum": 0 }, "message_id": { "type": "string", "format": "uuid" }, "new_text": { "type": "string" } } }, "MessageSubmitStreamingResponseToolCallProposed": { "type": "object", "required": [ "message_id", "content_index", "tool_call_id", "tool_name" ], "properties": { "content_index": { "type": "integer", "minimum": 0 }, "input": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "message_id": { "type": "string", "format": "uuid" }, "tool_call_id": { "type": "string" }, "tool_name": { "type": "string" } } }, "MessageSubmitStreamingResponseToolCallUpdate": { "type": "object", "required": [ "message_id", "content_index", "tool_call_id", "tool_name", "status" ], "properties": { "content_index": { "type": "integer", "minimum": 0 }, "input": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "message_id": { "type": "string", "format": "uuid" }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "progress": { "type": "number", "format": "double" }, "progress_message": { "type": "string" }, "status": { "$ref": "#/components/schemas/ToolCallStatus" }, "tool_call_id": { "type": "string" }, "tool_name": { "type": "string" }, "total": { "type": "number", "format": "double" } } }, "MessageSubmitStreamingResponseUserMessageSaved": { "type": "object", "required": [ "message_id", "message" ], "properties": { "message": { "$ref": "#/components/schemas/ChatMessage" }, "message_id": { "type": "string", "format": "uuid" } } }, "MultipartFormFile": { "type": "object", "required": [ "name", "file" ], "properties": { "file": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream" }, "name": { "type": "string" }, "outlook_provenance": { "type": "string", "description": "Optional version 1 OutlookFileProvenance JSON text (maximum 64 KiB).\nSend exactly once, before all file parts; applies to every file in this request.\nFiles with different origins must be uploaded in separate requests." } } }, "NativeJobResponse": { "type": "object", "required": [ "id", "chatId", "messageId", "state", "binding", "plan" ], "properties": { "binding": { "type": "object", "required": [ "backendOrigin", "accountId", "deviceId", "taskId", "jobId", "attemptId", "toolCallId", "planDigest" ], "properties": { "accountId": { "type": "string", "maxLength": 128, "minLength": 1 }, "attemptId": { "type": "string", "maxLength": 128, "minLength": 1 }, "backendOrigin": { "type": "string", "maxLength": 2048, "minLength": 1 }, "deviceId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,128}$" }, "jobId": { "type": "string", "maxLength": 128, "minLength": 1 }, "planDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "taskId": { "type": "string", "maxLength": 128, "minLength": 1 }, "toolCallId": { "type": "string", "maxLength": 128, "minLength": 1 } }, "additionalProperties": true }, "chatId": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "messageId": { "type": "string", "format": "uuid" }, "plan": { "type": "object", "required": [ "operation", "queryVariants", "maxHits", "maxArtifacts", "maxBytes", "executionSeconds", "expiresAt" ], "properties": { "executionSeconds": { "type": "integer", "maximum": 300, "minimum": 1 }, "expiresAt": { "type": "integer", "maximum": 9007199254740991, "minimum": 0 }, "maxArtifacts": { "type": "integer", "maximum": 20, "minimum": 1 }, "maxBytes": { "type": "integer", "maximum": 12582912, "minimum": 1 }, "maxHits": { "type": "integer", "maximum": 100, "minimum": 1 }, "operation": { "type": "string", "enum": [ "collect_evidence" ] }, "queryVariants": { "type": "array", "items": { "type": "string", "maxLength": 512, "minLength": 1 }, "maxItems": 8, "minItems": 1, "uniqueItems": true } }, "additionalProperties": true }, "receipt": { "type": "string" }, "serverOutcome": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "cancelled", "expired" ] } }, "additionalProperties": false }, "state": { "$ref": "#/components/schemas/AttemptState" } } }, "NotRetryableError": { "type": "object", "description": "Body of the `409` answers that mean \"not this run\".\n\nDistinct from [`GenerationRunningError`] for the reason 781-B's\n`NothingToReactError` is: that one says \"not now\", this one says \"not this\nrun\". `code` is what the client discriminates on.", "required": [ "code", "state", "chat_id" ], "properties": { "chat_id": { "type": "string", "format": "uuid", "description": "The child run the client asked to retry." }, "code": { "type": "string", "description": "Always `not_retryable`." }, "message": { "type": [ "string", "null" ] }, "state": { "$ref": "#/components/schemas/NotRetryableState" } } }, "NotRetryableState": { "type": "string", "description": "Why a run cannot be retried. A closed vocabulary, because the client\nswitches on it to choose between hiding the control, linking to the run\nthat already replaced this one, and showing a reason.", "enum": [ "retry_in_flight", "completed", "working", "not_a_task_run", "brief_unavailable", "concurrency_cap", "launch_refused" ] }, "NothingToReactError": { "type": "object", "description": "Body of the `409` `/react` answers when there is nothing to react to.\n\nDistinct from [`GenerationRunningError`] because the two are different\ndecisions: that one says \"not now\", this one says \"not this row, ever\".\n`code` is what the client discriminates on; `reason` is what it uses to\nchoose between suppressing the affordance and offering a re-anchor.", "required": [ "code", "chat_id", "task_result_message_id", "reason" ], "properties": { "chat_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "description": "Always `nothing_to_react`." }, "reason": { "type": "string", "description": "One of `not_a_task_result`, `not_delivered`, `already_reacted`,\n`tip_moved`." }, "task_result_message_id": { "type": "string", "format": "uuid" } } }, "OperationError": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string", "description": "Executor text, at most 1024 characters. Only a kind validator may forward it." } }, "additionalProperties": false }, "OperationOutcome": { "type": "string", "enum": [ "succeeded", "rejected", "failed", "unknown" ] }, "OperationPayload": { "oneOf": [ { "type": "null", "default": null }, { "type": "boolean" }, { "type": "number", "format": "double" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/OperationPayload" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/OperationPayload" }, "propertyNames": { "type": "string" } } ], "description": "JSON transport shape only: every payload still requires its compiled kind's\nvalidator. An explicit schema keeps generated clients from treating JSON as void." }, "OperationRequest": { "type": "object", "required": [ "attempt_id", "operation_id", "kind", "realm", "chat_id", "message_id", "tool_call_id", "account_id", "binding", "consent", "expires_at", "input" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "attempt_id": { "type": "string", "format": "uuid" }, "base_revision": { "type": "integer", "format": "int64", "minimum": 0 }, "binding": { "$ref": "#/components/schemas/ExecutorBinding" }, "chat_id": { "type": "string", "format": "uuid" }, "consent": { "$ref": "#/components/schemas/ConsentPolicy" }, "expires_at": { "type": "string", "format": "date-time" }, "input": { "$ref": "#/components/schemas/OperationPayload" }, "kind": { "type": "string" }, "message_id": { "type": "string", "format": "uuid" }, "operation_id": { "type": "string" }, "realm": { "$ref": "#/components/schemas/ExecutionRealm" }, "tool_call_id": { "type": "string" } }, "additionalProperties": false }, "OperationResult": { "type": "object", "required": [ "attempt_id", "operation_id", "outcome", "executor" ], "properties": { "attempt_id": { "type": "string", "format": "uuid" }, "base_revision": { "type": "integer", "format": "int64", "minimum": 0 }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OperationError" } ] }, "executor": { "$ref": "#/components/schemas/ExecutorBinding" }, "operation_id": { "type": "string" }, "outcome": { "$ref": "#/components/schemas/OperationOutcome" }, "result": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OperationValue" } ] } }, "additionalProperties": false }, "OperationValue": { "oneOf": [ { "type": "object", "required": [ "value", "type" ], "properties": { "type": { "type": "string", "enum": [ "value" ] }, "value": { "$ref": "#/components/schemas/OperationPayload" } } }, { "type": "object", "required": [ "reference", "type" ], "properties": { "reference": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "reference" ] } } }, { "type": "object", "required": [ "receipt", "type" ], "properties": { "receipt": { "$ref": "#/components/schemas/OperationPayload" }, "type": { "type": "string", "enum": [ "receipt" ] } } } ] }, "OrganizationGroup": { "type": "object", "description": "An organization group", "required": [ "id", "display_name", "subject_type_id" ], "properties": { "display_name": { "type": "string", "description": "The display name of the group" }, "id": { "type": "string", "description": "The unique ID of the group" }, "subject_type_id": { "type": "string", "description": "The subject type ID to use when creating a share grant (always \"organization_group_id\")" } } }, "OrganizationGroupsResponse": { "type": "object", "description": "Response for the organization groups endpoint", "required": [ "groups" ], "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationGroup" }, "description": "List of groups in the organization" } } }, "OrganizationUser": { "type": "object", "description": "An organization user", "required": [ "id", "display_name", "subject_type_id" ], "properties": { "display_name": { "type": "string", "description": "The display name of the user" }, "id": { "type": "string", "description": "The unique ID of the user" }, "job_title": { "type": [ "string", "null" ], "description": "The job title of the user" }, "mail": { "type": [ "string", "null" ], "description": "The email address of the user" }, "subject_type_id": { "type": "string", "description": "The subject type ID to use when creating a share grant (always \"organization_user_id\")" } } }, "OrganizationUsersResponse": { "type": "object", "description": "Response for the organization users endpoint", "required": [ "users" ], "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationUser" }, "description": "List of users in the organization" } } }, "OutlookExternalId": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "OutlookFileOrigin": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/OutlookMessageReference", "description": "The uploaded email's own identity; a thread export identifies only its anchor." }, "topLevelParent": { "$ref": "#/components/schemas/OutlookMessageReference", "description": "The outermost containing mailbox message, separate from the document's identity." } } }, "OutlookFileProvenance": { "type": "object", "required": [ "version", "origins" ], "properties": { "origins": { "type": "array", "items": { "$ref": "#/components/schemas/OutlookFileOrigin" }, "description": "All distinct origins, including multiple containing emails for identical bytes.", "minItems": 1 }, "version": { "type": "integer", "format": "int32", "description": "Contract version. Only version 1 is supported.", "maximum": 1, "minimum": 1 } } }, "OutlookMailboxReference": { "type": "object", "properties": { "emailAddress": { "type": "string", "description": "SMTP address of the owning mailbox, including shared mailboxes." }, "mailboxId": { "type": "string", "description": "Local mailbox ID, never a Graph mailbox identifier." }, "profileName": { "type": "string" } } }, "OutlookMessageReference": { "type": "object", "required": [ "external_ids" ], "properties": { "documentId": { "type": "string", "description": "Local catalog UUID, scoped to its originating sidecar installation." }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/OutlookExternalId" } }, "mailbox": { "$ref": "#/components/schemas/OutlookMailboxReference" } } }, "PendingToolCall": { "type": "object", "description": "A call of the parked batch that was never popped. The parked part is the\nonly record of these, so the continuation has to replay them from here.", "required": [ "call_id", "fn_name", "fn_arguments" ], "properties": { "call_id": { "type": "string" }, "fn_arguments": { "$ref": "#/components/schemas/Value" }, "fn_name": { "type": "string" } } }, "PromptOptimizerRequest": { "type": "object", "description": "Request to optimize a prompt using the configured prompt optimizer.", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "The prompt to optimize." } } }, "PromptOptimizerResponse": { "type": "object", "description": "Response containing the optimized prompt.", "required": [ "optimized_prompt" ], "properties": { "optimized_prompt": { "type": "string", "description": "The optimized prompt returned by the model." } } }, "ProvenanceRunMode": { "type": "string", "description": "How a delegated run's result gets back to the turn that started it, as\npersisted on [`crate::models::chat::ChatProvenance`].\n\nA superset of [`DelegationRunMode`], deliberately kept as its own type: the\nrequest wire stays at two variants, so `\"async\"` in a submit, edit or\nregenerate body is a deserialization failure rather than a mode a client can\nask for. `Wait` is never written - absence means it - so every envelope\nstored before this type existed deserializes unchanged.", "enum": [ "wait", "background", "async" ] }, "ReactToTaskResultRequest": { "type": "object", "description": "What a client asks `/react` to answer.", "required": [ "task_result_message_id" ], "properties": { "task_result_message_id": { "type": "string", "format": "uuid", "description": "The delivered `task_result` user row to react to.", "example": "00000000-0000-0000-0000-000000000000" } } }, "ReceiptResponse": { "type": "object", "required": [ "receipt", "result" ], "properties": { "receipt": { "type": "string" }, "result": { "$ref": "#/components/schemas/OperationResult" } } }, "ReceiptsResponse": { "type": "object", "required": [ "accountId", "jobs" ], "properties": { "accountId": { "type": "string" }, "after": { "type": "string", "format": "uuid" }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/NativeJobResponse" } } } }, "RecentChat": { "type": "object", "required": [ "id", "title_resolved", "last_message_at", "file_uploads", "is_pinned", "mcp_write_tools_enabled", "disabled_mcp_server_ids", "disabled_mcp_tools", "can_edit", "delegated_runs_in_flight", "created_via" ], "properties": { "active_generation_started_at": { "type": "string", "format": "date-time", "description": "Start time of the chat's generation, present only while it is running\nwith a fresh heartbeat" }, "archived_at": { "type": "string", "format": "date-time", "description": "When this chat was archived by the user." }, "assistant_id": { "type": "string", "description": "The assistant ID if this chat is based on an assistant" }, "assistant_name": { "type": "string", "description": "The name of the assistant if this chat is based on an assistant" }, "can_edit": { "type": "boolean", "description": "Whether the current user can edit this chat (e.g., edit messages)\n\nNOTE: Currently this is true only for the chat owner. In the future,\nthis may include collaborators/roles/policy-based permissions." }, "created_via": { "$ref": "#/components/schemas/ChatCreatedVia", "description": "Surface the chat was created from. `legacy` for chats that predate\nrecording it and could not be attributed afterwards." }, "delegated_run_outcome": { "type": "string", "description": "Terminal outcome of a delegated run: `completed` when the run landed a\nclean assistant answer, `failed` when it did not (unanswered, errored,\nor killed). Absent while the run is live and for chats that are not\ndelegated runs. Derived from the chat's own content, so it stays\naccurate long after the live generation status expires — a fresh\nclient sees the terminal state without ever having observed the run.", "example": "completed" }, "delegated_runs_in_flight": { "type": "boolean", "description": "Whether any async delegated run spawned from this chat is still owed\nback to it — unfinished, or holding an undelivered result. Clients use\nthis to keep the generation-status poll alive while a detached run is\noutstanding. Always present." }, "disabled_mcp_server_ids": { "type": "array", "items": { "type": "string" }, "description": "MCP servers the user switched off for this chat; their tools are not\noffered to the model." }, "disabled_mcp_tools": { "type": "array", "items": { "type": "string" }, "description": "`server/tool` patterns of MCP tools the user switched off for this\nchat; matching tools are not offered to the model." }, "file_uploads": { "type": "array", "items": { "$ref": "#/components/schemas/FileReference" }, "description": "Files uploaded to this chat" }, "id": { "type": "string" }, "is_pinned": { "type": "boolean", "description": "Whether this chat is pinned by its owner." }, "last_chat_provider_id": { "type": "string", "description": "The chat provider ID used for the most recent message" }, "last_message_at": { "type": "string", "format": "date-time", "description": "Time of the last message in the chat." }, "last_model": { "$ref": "#/components/schemas/ChatModel", "description": "The model information for the most recent message, if available" }, "last_selected_facets": { "type": "array", "items": { "type": "string" }, "description": "The facets selected for the most recent message" }, "mcp_write_tools_enabled": { "type": "boolean", "description": "Whether the model may be offered MCP write tools and client actions\nin this chat. Off, only tools the server marks read-only are offered." }, "origin_assistant_id": { "type": "string", "description": "The assistant bound to the origin chat at spawn time, if any." }, "origin_chat_id": { "type": "string", "description": "The origin chat this chat was spawned from, if any. May reference a\ndeleted chat." }, "origin_chat_title": { "type": "string", "description": "Resolved display title of the origin chat; absent when the origin no\nlonger exists." }, "pending_tool_approval_at": { "type": "string", "format": "date-time", "description": "Present while the chat's generation is stopped on an MCP tool approval\nawaiting the user's decision" }, "provenance_kind": { "type": "string", "description": "Provenance kind when the chat was spawned from another chat (e.g.\n`delegation` for a delegated run). Clients derive \"is delegated run\"\nfrom this value." }, "provenance_run_mode": { "type": "string", "description": "How a delegated run was dispatched. Present only for delegation\nprovenance, and only for a detached run: `background`, whose result\nnever flows back to the origin turn, or `async`, whose result is\ndelivered into the origin chat later as its own row. An awaited run\nomits it, since its answer already returned inline.", "example": "background" }, "retry_of": { "type": "string", "description": "The failed delegated run this one was started to replace. Present only\non a retry child. Clients use it to swap a failed run's retry button for\na link to the run that replaced it, durably - it survives a reload,\nwhere component state would not." }, "title_by_summary": { "type": [ "string", "null" ], "description": "Title of the chat as generated by summary automation." }, "title_by_user_provided": { "type": [ "string", "null" ], "description": "Title of the chat as explicitly provided by the user." }, "title_resolved": { "type": "string", "description": "Resolved chat title where user-provided title takes precedence over summary title." } } }, "RecentChatStats": { "type": "object", "description": "Statistics for a list of recent chats", "required": [ "total_count", "current_offset", "returned_count", "has_more" ], "properties": { "current_offset": { "type": "integer", "format": "int64", "description": "Current offset in the list", "minimum": 0 }, "has_more": { "type": "boolean", "description": "Whether there are more chats available" }, "returned_count": { "type": "integer", "description": "Number of chats in the current response", "minimum": 0 }, "total_count": { "type": "integer", "format": "int64", "description": "Total number of chats available" } } }, "RecentChatTypeFilter": { "type": "string", "description": "Kind of chat to restrict a recent chat listing to.", "enum": [ "chat", "assistant" ] }, "RecentChatsResponse": { "type": "object", "description": "Response for the recent_chats endpoint", "required": [ "chats", "stats" ], "properties": { "chats": { "type": "array", "items": { "$ref": "#/components/schemas/RecentChat" }, "description": "The list of recent chats" }, "stats": { "$ref": "#/components/schemas/RecentChatStats", "description": "Statistics about the chat list" } } }, "RegenerateMessageRequest": { "type": "object", "required": [ "current_message_id" ], "properties": { "action_facet": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ActionFacetRequest", "description": "Optional action facet to apply during this generation." } ] }, "chat_provider_id": { "type": "string", "description": "The ID of the chat provider to use for generation. If not provided, will use the highest priority model for the user.", "example": "primary" }, "current_message_id": { "type": "string", "format": "uuid", "description": "The ID of the message that should have a replacement response generated.", "example": "00000000-0000-0000-0000-000000000000" }, "delegation_run_mode": { "$ref": "#/components/schemas/DelegationRunMode", "description": "How delegated runs spawned by this message are awaited. Defaults to\n`wait`; `background` requires `delegation.allow_background`\nand is downgraded to `wait` server-side when the gate is off." }, "mentioned_assistant_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Assistants the user @-mentioned in this message as delegation targets.\nValidated server-side; requires `delegation.assistants.enabled`." }, "selected_facet_ids": { "type": "array", "items": { "type": "string" }, "description": "IDs of facets selected by the user for this generation." } } }, "RegenerateMessageStreamingResponseMessage": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseAssistantMessageStarted", "description": "Sent when the assistant message entry has been created, before generation starts." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "assistant_message_started" ] } } } ], "description": "Sent when the assistant message entry has been created, before generation starts." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessageComplete", "description": "Sent when the assistant's response has been saved in full." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "assistant_message_completed" ] } } } ], "description": "Sent when the assistant's response has been saved in full." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessageTextDelta", "description": "Sent whenever a new text chunk is generated by the assistant." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "text_delta" ] } } } ], "description": "Sent whenever a new text chunk is generated by the assistant." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseMessageReasoningDelta", "description": "Sent whenever a new reasoning chunk is generated by the assistant." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "reasoning_delta" ] } } } ], "description": "Sent whenever a new reasoning chunk is generated by the assistant." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseToolCallProposed", "description": "Sent when the LLM proposes a tool call to be part of the assistant message." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "tool_call_proposed" ] } } } ], "description": "Sent when the LLM proposes a tool call to be part of the assistant message." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseToolCallUpdate", "description": "Sent to update the status of a tool call execution by the backend." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "tool_call_update" ] } } } ], "description": "Sent to update the status of a tool call execution by the backend." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseClientToolCall", "description": "Sent when the model calls a facet client tool: the turn is suspended\nuntil the client executes it and POSTs the result back." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "client_tool_call" ] } } } ], "description": "Sent when the model calls a facet client tool: the turn is suspended\nuntil the client executes it and POSTs the result back." }, { "allOf": [ { "$ref": "#/components/schemas/MessageSubmitStreamingResponseError", "description": "Sent when an error occurs during message generation." }, { "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "error" ] } } } ], "description": "Sent when an error occurs during message generation." } ] }, "ResolveShareLinkResponse": { "type": "object", "required": [ "share_link" ], "properties": { "owner_display_name": { "type": [ "string", "null" ] }, "owner_picture": { "type": [ "string", "null" ] }, "share_link": { "$ref": "#/components/schemas/ShareLink" }, "title_resolved": { "type": [ "string", "null" ] } } }, "ResumeStreamRequest": { "type": "object", "required": [ "chat_id" ], "properties": { "chat_id": { "type": "string", "format": "uuid", "description": "The ID of the chat to resume streaming for.", "example": "00000000-0000-0000-0000-000000000000" } } }, "RetryDelegatedRunRequest": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "$ref": "#/components/schemas/RetryKind" } }, "additionalProperties": false }, "RetryDelegatedRunResponse": { "type": "object", "required": [ "child_chat_id" ], "properties": { "child_chat_id": { "type": "string", "description": "The new child run started to replace the failed one." } } }, "RetryKind": { "type": "string", "description": "What a client asks to have retried.\n\nExactly ONE variant, deliberately. The Foundations contract also describes\nretrying a stuck result *delivery*, but that half is not built, so\n`\"delivery\"` must be an unknown serde variant - a `422` the client can act\non - rather than a value this route accepts and then refuses with a `409`\nthat would read like a transient condition. Adding a variant here without\nthe rest of the work is what `retry_with_an_unknown_kind_is_422` exists to\ncatch.", "enum": [ "task" ] }, "SetShareLinkRequest": { "type": "object", "required": [ "resource_type", "resource_id", "enabled" ], "properties": { "enabled": { "type": "boolean" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string" } } }, "SetShareLinkResponse": { "type": "object", "required": [ "share_link" ], "properties": { "share_link": { "$ref": "#/components/schemas/ShareLink" } } }, "ShareGrant": { "type": "object", "description": "A share grant model", "required": [ "id", "resource_type", "resource_id", "subject_type", "subject_id_type", "subject_id", "role", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When this share grant was created" }, "group_profile": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationGroup", "description": "The group profile for organization group share grants." } ] }, "id": { "type": "string", "description": "The unique ID of the share grant" }, "resource_id": { "type": "string", "description": "The ID of the resource being shared" }, "resource_type": { "type": "string", "description": "The type of resource being shared (e.g., \"assistant\")" }, "role": { "type": "string", "description": "The role being granted (\"viewer\" or \"editor\")" }, "subject_id": { "type": "string", "description": "The ID of the subject being granted access. Organization-wide grants use \"__organization__\"." }, "subject_id_type": { "type": "string", "description": "The type of subject ID (e.g., \"id\", \"organization_group_id\", or \"organization_id\")" }, "subject_type": { "type": "string", "description": "The type of subject being granted access (e.g., \"user\", \"organization_group\", or \"organization\")" }, "updated_at": { "type": "string", "format": "date-time", "description": "When this share grant was last updated" }, "user_profile": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationUser", "description": "The user profile for organization user share grants." } ] } } }, "ShareGrantInput": { "type": "object", "description": "A share grant to create with the assistant", "required": [ "subject_type", "subject_id_type", "subject_id", "role" ], "properties": { "role": { "type": "string", "description": "The role to grant (\"viewer\" or \"editor\")" }, "subject_id": { "type": "string", "description": "The ID of the subject to grant access to. Organization-wide grants use \"__organization__\"." }, "subject_id_type": { "type": "string", "description": "The type of subject ID (e.g., \"id\", \"organization_group_id\", or \"organization_id\")" }, "subject_type": { "type": "string", "description": "The type of subject to grant access to (e.g., \"user\", \"organization_group\", or \"organization\")" } } }, "ShareLink": { "type": "object", "required": [ "id", "resource_type", "resource_id", "enabled", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ShareLinkForResourceResponse": { "type": "object", "properties": { "share_link": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShareLink" } ] } } }, "ShareLinkQuery": { "type": "object", "required": [ "resource_type", "resource_id" ], "properties": { "resource_id": { "type": "string" }, "resource_type": { "type": "string" } } }, "SharepointProviderMetadata": { "type": "object", "description": "SharePoint-specific metadata for linking files", "required": [ "drive_id", "item_id" ], "properties": { "drive_id": { "type": "string", "description": "The ID of the drive containing the file" }, "item_id": { "type": "string", "description": "The ID of the file item" } } }, "StartMcpServerOauthResponse": { "type": "object", "required": [ "authorization_url" ], "properties": { "authorization_url": { "type": "string" } } }, "StarterPromptInfo": { "type": "object", "required": [ "id", "title", "subtitle", "prompt" ], "properties": { "chat_provider": { "type": "string" }, "icon": { "type": "string" }, "id": { "type": "string" }, "prompt": { "type": "string" }, "selected_facets": { "type": "array", "items": { "type": "string" } }, "subtitle": { "type": "string" }, "title": { "type": "string" } } }, "StarterPromptsResponse": { "type": "object", "required": [ "starter_prompts" ], "properties": { "starter_prompts": { "type": "array", "items": { "$ref": "#/components/schemas/StarterPromptInfo" } } } }, "StartingAssistantInfo": { "type": "object", "description": "The resolved starting assistant for the calling user.", "required": [ "assistant_id", "source" ], "properties": { "assistant_hub_assistant_id": { "type": "string", "description": "The stable `assistant_hub_assistants.id` the pick or pin stores. Absent\nwhen the user picked an assistant that was never published to the hub,\nwhich has no hub row." }, "assistant_id": { "type": "string", "description": "The live `assistants.id` a client can open a chat with. For a hub\nassistant it is resolved at read time from the stable hub id, so it is\nright even after a republish minted a fresh clone." }, "audience": { "type": "string", "description": "The name of the audience (policy key) whose pin won for this user.\nPresent only when `source` is `audience_pin`." }, "source": { "$ref": "#/components/schemas/StartingAssistantSource", "description": "Whether the user's own pick or an admin's audience pin won." } } }, "StartingAssistantResponse": { "type": "object", "description": "Response for `GET /me/starting-assistant`.", "properties": { "starting_assistant": { "$ref": "#/components/schemas/StartingAssistantInfo", "description": "Absent when no pin applies to the calling user; the client shows the\nordinary welcome screen." } } }, "StartingAssistantSource": { "type": "string", "description": "Where a resolved starting assistant came from.", "enum": [ "user_pick", "audience_pin" ] }, "SubmissionOutcome": { "type": "object", "required": [ "status", "attempts_used", "max_attempts" ], "properties": { "attempts_used": { "type": "integer", "format": "int32", "minimum": 0 }, "max_attempts": { "type": "integer", "format": "int32", "minimum": 0 }, "reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubmissionReason" } ] }, "status": { "$ref": "#/components/schemas/SubmissionStatus" } } }, "SubmissionReason": { "type": "string", "enum": [ "validation_failed", "attempts_exhausted", "model_stopped", "recovery_reads_exhausted", "terminal_validation", "context_unavailable", "capability_unavailable", "provider_error", "timeout", "cancelled", "user_requested_answer", "user_stopped" ] }, "SubmissionRecovery": { "type": "string", "enum": [ "repair_arguments", "read_current_context", "cannot_continue" ] }, "SubmissionStatus": { "type": "string", "enum": [ "correcting", "accepted", "unresolved" ] }, "TaskResultInput": { "type": "object", "description": "The marker on a delivered task result's user row.\n\nDeliberately not the same shape as `ContentPartTaskResult`: that one is the\nrendered artifact the UI shows, this one is the bookkeeping that ties the\nrow back to the delivery record on the child chat.", "required": [ "delivery_id", "child_chat_id", "status", "scheduling", "sequence" ], "properties": { "child_chat_id": { "type": "string", "format": "uuid" }, "delivery_id": { "type": "string", "format": "uuid", "description": "Matches `ResultDelivery::delivery_id`; the idempotency key that makes\n\"has this already been delivered?\" answerable with a query." }, "reason": { "type": "string" }, "result_message_id": { "type": "string", "format": "uuid", "description": "The child's assistant row this result came from. Absent when the run\nfinished but its answer row is gone (`reason = \"result_missing\"`): the\ndelivery still happens, because the origin model has to learn the task\nfailed, but there is no row to point at." }, "scheduling": { "type": "string", "description": "Whether the delivery was meant to provoke a reaction turn. A `silent`\nresult is folded into the user's next message instead." }, "sequence": { "type": "integer", "format": "int32", "minimum": 0 }, "status": { "type": "string" } } }, "TokenUsageFileInput": { "type": "object", "properties": { "input_files_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "File upload IDs to include in estimation.", "example": "[\"00000000-0000-0000-0000-000000000000\"]" } } }, "TokenUsageNewChatInput": { "type": "object", "properties": { "assistant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional assistant ID for new chat context.", "example": "00000000-0000-0000-0000-000000000000" } } }, "TokenUsageRequest": { "type": "object", "properties": { "action_facet": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ActionFacetRequest", "description": "Optional action facet to apply during this estimation." } ] }, "chat_previous_message_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The previous message ID to anchor chat history context.\nPreferred over `previous_message_id` for new clients.", "example": "00000000-0000-0000-0000-000000000000" }, "chat_provider_id": { "type": "string", "description": "Optional chat provider ID to use for token estimation. If not provided, uses the default provider.", "example": "gpt-4o" }, "existing_chat_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of an existing chat to use. If provided, the chat with this ID will be used instead of creating a new one.", "example": "00000000-0000-0000-0000-000000000000" }, "file": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsageFileInput", "description": "File content inputs to include in the estimation." } ] }, "input_files_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The IDs of any files attached to this message. These files must already be uploaded to the file_uploads table.", "example": "[\"00000000-0000-0000-0000-000000000000\"]" }, "new_chat": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsageNewChatInput", "description": "Configuration for estimating a new chat context." } ] }, "new_message_content": { "type": [ "string", "null" ], "description": "Content for the new message being composed.\nPreferred over `user_message` for new clients.", "example": "Hello, world!" }, "previous_message_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of the message that this message is a response to. If this is the first message in the chat, this should be empty.", "example": "00000000-0000-0000-0000-000000000000" }, "selected_facet_ids": { "type": "array", "items": { "type": "string" }, "description": "IDs of facets selected by the user for this estimation." }, "system_prompt": { "type": [ "string", "null" ], "description": "Additional system prompt content to include in the estimation.", "example": "You are a concise legal assistant." }, "user_message": { "type": "string", "description": "The text of the message.", "example": "Hello, world!" }, "virtual_files": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/TokenUsageVirtualFile" }, "description": "Inline file payloads to include in the estimation without persisting\nthem. Used by clients (e.g. the Outlook add-in) that want to count\ntransient content — the previewed email body — toward the token budget\nwithout writing a `file_uploads` row that would later orphan if the\nuser dismissed the preview. Each entry is parsed in-place and included\nin the response's `file_details` alongside any `input_files_ids`." } } }, "TokenUsageResponse": { "type": "object", "description": "Response for the token_usage_estimate endpoint", "required": [ "stats", "file_details" ], "properties": { "file_details": { "type": "array", "items": { "$ref": "#/components/schemas/TokenUsageResponseFileItem" }, "description": "Detailed token usage for each file" }, "stats": { "$ref": "#/components/schemas/TokenUsageStats", "description": "Overall statistics about token usage" } } }, "TokenUsageResponseFileItem": { "type": "object", "description": "Token usage details for an individual file", "required": [ "id", "filename", "token_count" ], "properties": { "coverage": { "$ref": "#/components/schemas/Coverage" }, "filename": { "type": "string", "description": "The original filename of the file" }, "full_token_count": { "type": "integer", "minimum": 0 }, "id": { "type": "string", "description": "The unique ID of the file" }, "included_token_count": { "type": "integer", "minimum": 0 }, "inclusion_mode": { "$ref": "#/components/schemas/InclusionMode" }, "reason": { "type": "string" }, "token_count": { "type": "integer", "description": "Number of tokens used for this file's content", "minimum": 0 } } }, "TokenUsageStats": { "type": "object", "description": "Token usage statistics for the request", "required": [ "total_tokens", "user_message_tokens", "history_tokens", "file_tokens", "max_tokens", "remaining_tokens", "chat_provider_id" ], "properties": { "chat_provider_id": { "type": "string", "description": "The chat provider ID that was used for this estimation" }, "file_tokens": { "type": "integer", "description": "Number of tokens in file contents", "minimum": 0 }, "history_tokens": { "type": "integer", "description": "Number of tokens in previous messages (chat history)", "minimum": 0 }, "max_tokens": { "type": "integer", "format": "int32", "description": "The configured model's maximum token limit", "minimum": 0 }, "remaining_tokens": { "type": "integer", "format": "int32", "description": "Remaining tokens available for the model response", "minimum": 0 }, "total_tokens": { "type": "integer", "description": "Total number of tokens in the request", "minimum": 0 }, "user_message_tokens": { "type": "integer", "description": "Number of tokens in the user message", "minimum": 0 } } }, "TokenUsageVirtualFile": { "type": "object", "description": "Inline file content (not persisted) included in a token estimate. The\nserver decodes the base64 payload, runs the same parser the upload route\nuses, tokenizes the result, and discards the bytes once the response is\nsent. Per-file size cap matches the upload endpoint's\n`max_upload_size_bytes` config.", "required": [ "filename", "base64" ], "properties": { "base64": { "type": "string", "description": "Standard base64 (RFC 4648) of the raw file bytes." }, "content_type": { "type": [ "string", "null" ], "description": "Provided MIME type. Normalized via the same fallback rules as\n`/me/files` (e.g. `application/octet-stream` for `.eml` becomes\n`message/rfc822`).", "example": "message/rfc822" }, "filename": { "type": "string", "description": "Original filename (used for content-type fallback and tokenizer header).", "example": "preview.eml" } } }, "ToolApprovalAnnotations": { "type": "object", "description": "Snapshot of the MCP annotations used to decide whether a tool call needs\nuser approval. The values are normalized to the MCP defaults so an absent\nannotation remains auditable as the pessimistic interpretation.", "required": [ "readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint" ], "properties": { "destructiveHint": { "type": "boolean" }, "idempotentHint": { "type": "boolean" }, "openWorldHint": { "type": "boolean" }, "readOnlyHint": { "type": "boolean" } } }, "ToolApprovalDecision": { "type": "string", "description": "Decision submitted for a generation stopped at an MCP approval gate.\n\n`RejectAlways` needs no policy flag the way `ApproveAlways` needs\n`allow_always`: a denial is more restrictive than anything the policy does.", "enum": [ "approve", "reject", "approve_always", "reject_always", "withdraw" ] }, "ToolApprovalKind": { "type": "string", "description": "Which surface a durable approval stop belongs to. `McpTool` is the\ndefault so rows written before the other kinds existed keep parsing.", "enum": [ "mcp_tool", "delegated_task", "task_plan", "tool_call_limit", "client_tool" ] }, "ToolCallStatus": { "type": "string", "enum": [ "preparing", "in_progress", "success", "error" ] }, "ToolDisplayMetadata": { "type": "object", "description": "Inert display text from the tool descriptor, captured when approval is\nrequested. Never used to select a tool, evaluate policy or execute a call.", "required": [ "title", "description_truncated" ], "properties": { "description": { "type": [ "string", "null" ] }, "description_truncated": { "type": "boolean" }, "title": { "type": "string" } } }, "ToolUse": { "type": "object", "properties": { "ended_at": { "type": [ "string", "null" ], "default": null }, "input": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ], "default": null }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ], "default": null }, "progress": { "type": "number", "format": "double", "default": null }, "progress_message": { "type": [ "string", "null" ], "default": null }, "started_at": { "type": [ "string", "null" ], "default": null }, "status": { "oneOf": [ { "$ref": "#/components/schemas/ToolCallStatus" } ], "default": "in_progress" }, "tool_call_id": { "type": "string", "default": "" }, "tool_name": { "type": "string", "default": "" }, "total": { "type": "number", "format": "double", "default": null } } }, "UnarchiveChatResponse": { "type": "object", "description": "Response from the unarchive chat endpoint", "required": [ "chat_id" ], "properties": { "chat_id": { "type": "string", "description": "The ID of the unarchived chat" } } }, "UpdateAssistantRequest": { "type": "object", "description": "Request to update an existing assistant", "properties": { "default_chat_provider": { "type": [ "string", "null" ], "description": "Optional new default chat provider" }, "description": { "type": [ "string", "null" ], "description": "Optional new description for the assistant" }, "enforce_facet_settings": { "type": [ "boolean", "null" ], "description": "Optional new enforcement flag for assistant facet settings" }, "facet_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Optional new list of facet IDs for this assistant" }, "file_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Optional list of file upload IDs to associate with this assistant" }, "mcp_server_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Optional new list of MCP server IDs" }, "name": { "type": [ "string", "null" ], "description": "Optional new name for the assistant" }, "prompt": { "type": [ "string", "null" ], "description": "Optional new prompt for the assistant" } } }, "UpdateAssistantResponse": { "allOf": [ { "$ref": "#/components/schemas/AssistantWithFiles", "description": "The updated assistant with files" } ], "description": "Response when updating an assistant" }, "UpdateChatRequest": { "type": "object", "description": "Request to update mutable chat fields.", "properties": { "disabled_mcp_server_ids": { "type": "array", "items": { "type": "string" }, "description": "MCP servers to switch off for this chat; replaces the stored list.\nTheir tools are withheld from the model. Only ever narrows the set the\npolicy, assistant and facets allow." }, "disabled_mcp_tools": { "type": "array", "items": { "type": "string" }, "description": "`server/tool` patterns of MCP tools to switch off for this chat;\nreplaces the stored list. Matching tools are withheld from the model.\nOnly ever narrows the set the policy, assistant, facets and the\nserver list allow; a pattern naming a tool the server no longer\nexposes does nothing." }, "is_pinned": { "type": [ "boolean", "null" ], "description": "Whether the chat should be pinned." }, "mcp_write_tools_enabled": { "type": [ "boolean", "null" ], "description": "Whether the model may be offered MCP write tools and client actions\nin this chat. Off, only tools the server marks read-only are offered\nand client-action proposals are withheld." }, "title_by_user_provided": { "type": "string", "description": "Optional user-provided title update.\n- `\\\"some title\\\"` sets the title\n- `null` removes a previously set title\n- omitted is treated the same as `null`" } } }, "UpdateChatResponse": { "type": "object", "description": "Response for update_chat endpoint.", "required": [ "chat_id", "title_resolved", "is_pinned", "mcp_write_tools_enabled", "disabled_mcp_server_ids", "disabled_mcp_tools" ], "properties": { "chat_id": { "type": "string", "description": "The ID of the updated chat" }, "disabled_mcp_server_ids": { "type": "array", "items": { "type": "string" }, "description": "MCP servers the user switched off for this chat." }, "disabled_mcp_tools": { "type": "array", "items": { "type": "string" }, "description": "`server/tool` patterns of MCP tools the user switched off for this chat." }, "is_pinned": { "type": "boolean", "description": "Whether the chat is pinned by its owner." }, "mcp_write_tools_enabled": { "type": "boolean", "description": "Whether the model may be offered MCP write tools and client actions\nin this chat." }, "title_by_summary": { "type": [ "string", "null" ], "description": "Title of the chat as generated by summary automation." }, "title_by_user_provided": { "type": [ "string", "null" ], "description": "Title of the chat as explicitly provided by the user." }, "title_resolved": { "type": "string", "description": "Resolved chat title where user-provided title takes precedence over summary title." } } }, "UpdateProfilePreferencesRequest": { "type": "object", "properties": { "client_tool_decisions": { "type": "object", "description": "Replaces all per-tool client tool decisions, keyed by qualified `namespace/name`.", "additionalProperties": { "$ref": "#/components/schemas/ClientToolDecision" }, "propertyNames": { "type": "string" } }, "client_tool_file_approval": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ClientToolFileApproval" } ] }, "preference_assistant_additional_information": { "type": [ "string", "null" ], "description": "Additional contextual information about the user for the assistant." }, "preference_assistant_custom_instructions": { "type": [ "string", "null" ], "description": "Additional behaviour/style/tone preferences for the assistant." }, "preference_default_chat_provider": { "type": [ "string", "null" ], "description": "Preferred default chat provider/model ID for new chats." }, "preference_job_title": { "type": [ "string", "null" ], "description": "User's job title." }, "preference_nickname": { "type": [ "string", "null" ], "description": "Preferred name to address the user with." }, "preference_starting_assistant_cleared": { "type": "boolean", "description": "Set `true` to explicitly clear the start screen (welcome screen even\nthough an audience pin exists), `false` to inherit again. Clearing\nalso removes any own pick; picking also un-clears." }, "preference_starting_assistant_id": { "type": [ "string", "null" ], "description": "The user's own start-screen pick when it is an assistant that was never\npublished to the hub, as an `assistants.id`. Setting either pick field\nremoves the other." }, "preference_starting_hub_assistant_id": { "type": [ "string", "null" ], "description": "The user's own start-screen pick when it is a hub assistant, as an\n`assistant_hub_assistants.id` (NOT the clone's `assistants.id` — those\ngo stale on every hub republish). Explicit `null` removes the pick and\nreturns to inheriting any audience pin." } } }, "UsageBucket": { "type": "object", "required": [ "date", "invocations", "unique_users" ], "properties": { "date": { "type": "string", "format": "date" }, "invocations": { "type": "integer", "format": "int64" }, "unique_users": { "type": "integer", "format": "int64" } } }, "UserProfile": { "type": "object", "required": [ "id", "preferred_language", "groups", "organization_group_ids" ], "properties": { "client_tool_decisions": { "type": "object", "description": "Per-tool decisions keyed by qualified `namespace/name`; absent tools keep their default.", "additionalProperties": { "$ref": "#/components/schemas/ClientToolDecision" }, "propertyNames": { "type": "string" } }, "client_tool_file_approval": { "$ref": "#/components/schemas/ClientToolFileApproval", "description": "Effective decision, including the configured default when no user override exists." }, "email": { "type": "string", "description": "The user's email address. Shouldn't be used as a unique identifier, as it may change." }, "groups": { "type": "array", "items": { "type": "string" }, "description": "List of groups the user belongs to.\n\nDerived from the ID token's `groups` claim, or Microsoft Graph for Entra overage." }, "id": { "type": "string" }, "name": { "type": "string", "description": "The user's display name." }, "organization_group_ids": { "type": "array", "items": { "type": "string" }, "description": "Organization membership IDs from the token or Entra overage resolution.\n\nThese can be used as subject_id when creating share grants\nwith subject_id_type \"organization_group_id\"." }, "organization_user_id": { "type": "string", "description": "Organization user ID from the `oid` claim (Entra ID specific).\n\nThis can be used as the subject_id when creating share grants\nwith subject_id_type \"organization_user_id\"." }, "picture": { "type": "string", "description": "The user's profile picture URL." }, "preference_assistant_additional_information": { "type": "string", "description": "Additional contextual information about the user for the assistant." }, "preference_assistant_custom_instructions": { "type": "string", "description": "Additional behaviour/style/tone preferences for the assistant." }, "preference_default_chat_provider": { "type": "string", "description": "The user's preferred default chat provider/model ID." }, "preference_job_title": { "type": "string", "description": "User's job title." }, "preference_nickname": { "type": "string", "description": "Preferred name to address the user with." }, "preference_starting_assistant_cleared": { "type": "boolean", "description": "True when the user explicitly cleared their start screen. This is\ndeliberately distinct from \"never set\": a clear must keep suppressing\nan admin's audience pin, while \"never set\" inherits it." }, "preference_starting_assistant_id": { "type": "string", "description": "The user's own start-screen pick when it is an assistant that was never\npublished to the hub, stored as an `assistants.id`. At most one of the\ntwo pick fields is ever set." }, "preference_starting_hub_assistant_id": { "type": "string", "description": "The user's own start-screen pick when it is a hub assistant, stored as\nan `assistant_hub_assistants.id` — stable across hub republishes, unlike\nthe clone's `assistants.id`. The LIVE assistant id it points at is\nresolved per request by `GET /me/starting-assistant`." }, "preferred_language": { "type": "string", "description": "The user's preferred language.\n\nThe final determined language is intersected with our supported languages, to determine the final language.\n\nWill be a BCP 47 language tag (e.g. \"en\" or \"en-US\").\n\nThis is derived in the following order (highest priority first):\n- `i18n.language.language_detection_priority`\n- Default language from `i18n.language.default_language`\n- \"en\"" } } }, "UserToolApprovalDecisionEntry": { "type": "object", "required": [ "tool_name" ], "properties": { "decision": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UserToolDecision", "description": "`null` deactivates the tool's decision, back to the policy default." } ] }, "tool_name": { "type": "string" } } }, "UserToolApprovalSetting": { "type": "object", "required": [ "id", "mcp_server_id", "tool_name", "decision" ], "properties": { "decision": { "$ref": "#/components/schemas/UserToolDecision" }, "id": { "type": "string", "format": "uuid" }, "mcp_server_id": { "type": "string" }, "tool_name": { "type": "string" } } }, "UserToolApprovalSettingsResponse": { "type": "object", "required": [ "settings" ], "properties": { "settings": { "type": "array", "items": { "$ref": "#/components/schemas/UserToolApprovalSetting" } } } }, "UserToolDecision": { "type": "string", "description": "A user's persistent decision for one MCP tool. Rows exist only while a\ndecision is active; the absence of a row means the policy default applies.", "enum": [ "always_allow", "ask", "denied" ] }, "Value": {} } } }