{ "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", "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/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.", "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" } } ], "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" }, "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/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 or the decision is invalid" }, "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" }, "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" }, "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" }, "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" }, "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" } } ], "responses": { "200": { "description": "Successfully retrieved chats with pagination metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentChatsResponse" } } } }, "400": { "description": "Invalid origin_chat_id format" }, "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-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": { "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" } } }, "ApplyUserToolApprovalSettingsBatchRequest": { "type": "object", "required": [ "mcp_server_id", "decisions" ], "properties": { "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/UserToolApprovalDecisionEntry" } }, "mcp_server_id": { "type": "string" } } }, "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" } } }, "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." }, "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" }, "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" }, "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." } } }, "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 }, "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" ], "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." }, "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" }, "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" }, "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" } } }, "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`." }, "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." }, "tool_call_id": { "type": "string", "description": "The `tool_call_id` from the `client_tool_call` event being answered." } } }, "ClientToolResultResponse": { "type": "object", "required": [ "delivered" ], "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)." } } }, "CompleteMcpServerOauthResponse": { "type": "object", "required": [ "connection_status" ], "properties": { "connection_status": { "$ref": "#/components/schemas/McpServerStatusValue" } } }, "ContentPart": { "oneOf": [ { "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/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." } ] }, "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." } } }, "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/DelegationRunMode", "description": "How the run relates to its origin turn; the preamble tells a background\ndelegate its answer is read in place rather than returned. Absent means\nawaited, so markers persisted before the field existed keep rendering\nthe 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": "" } } }, "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" }, "approved_at": { "type": "string" }, "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" }, "input": { "$ref": "#/components/schemas/Value" }, "mcp_server_id": { "type": "string" }, "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": { "never_allow": { "type": "boolean", "description": "Both fields default, so rejections stored before standing denials\nexisted still parse." }, "rejected_at": { "type": "string" }, "tool_call_id": { "type": "string" }, "user_tool_approval_setting_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "ContinueStreamRequest": { "type": "object", "description": "Rehydrates a generation that was deliberately stopped for MCP tool approval.", "required": [ "message_id", "decision" ], "properties": { "decision": { "$ref": "#/components/schemas/ToolApprovalDecision" }, "message_id": { "type": "string", "format": "uuid", "description": "The assistant message/generation that contains the pending approval 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." } ] }, "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" } } }, "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" }, "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" }, "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" } } }, "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" }, "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." }, "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" } } }, "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.)" } } }, "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" ], "properties": { "annotated": { "type": "boolean", "description": "Whether the server declared any hints at all. Defaults are the\npessimistic reading, so an unannotated tool is not read-only." }, "destructive_hint": { "type": "boolean" }, "idempotent_hint": { "type": "boolean" }, "open_world_hint": { "type": "boolean" }, "read_only_hint": { "type": "boolean" } } }, "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" ] }, "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" } } }, "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" } } }, "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." } } }, "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" ], "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." }, "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" }, "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 as `background` — the mark of a detached run\nwhose result never flowed back to the origin turn. An awaited run\nomits it, since its answer already returned inline.", "example": "background" }, "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" } } }, "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" ] }, "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": { "filename": { "type": "string", "description": "The original filename of the file" }, "id": { "type": "string", "description": "The unique ID of the file" }, "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" ] }, "ToolCallStatus": { "type": "string", "enum": [ "in_progress", "success", "error" ] }, "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": { "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": { "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\nThis is derived from the `groups` claim in the ID token.\nIf the claim is not present, this will be an empty list." }, "id": { "type": "string" }, "name": { "type": "string", "description": "The user's display name." }, "organization_group_ids": { "type": "array", "items": { "type": "string" }, "description": "Organization group IDs from the `groups` claim.\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": {} } } }