openapi: 3.0.0 info: title: Langdock API version: 3.0.0 servers: - url: https://api.langdock.com description: Production security: - bearerAuth: [] paths: /openai/{region}/v1/chat/completions: post: tags: - Chat summary: Creates a model response for the given chat conversation. parameters: - name: region in: path required: true description: The region of the API to use. schema: type: string enum: ["eu", "us", "global", "ch"] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateChatCompletionRequest" example: model: "gpt-4o-mini" messages: - role: "system" content: "You are a helpful agent." - role: "user" content: "Write a short poem about cats." responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/CreateChatCompletionResponse" example: choices: - message: content: "In moonlit shadows soft they prowl,\nWith eyes aglow in night's dark cowl." role: assistant index: 0 finish_reason: "stop" logprobs: null created: 1721722200 id: "chatcmpl-8o4sq3sSzGVqS0aQyjlXuuEGVZnSj" model: "gpt-4o-2024-05-13" object: "chat.completion" system_fingerprint: "fp_asd28019bf" usage: completion_tokens: 34 prompt_tokens: 14 total_tokens: 48 security: - bearerAuth: [] /openai/{region}/v1/responses: post: tags: - Responses summary: Creates a stateless model response. description: Creates a stateless OpenAI-compatible response. Supports text generation, streaming, and function tools. Do not send store=true, previous_response_id, background=true, or hosted tools. operationId: createResponse parameters: - name: region in: path required: true description: The region of the API to use. schema: type: string enum: ["eu", "us", "global", "ch"] requestBody: required: true content: application/json: schema: type: object required: - model - input properties: model: type: string description: The model ID. Use the models endpoint to list models available in your workspace. input: description: The input text or full conversation state to process. oneOf: - type: string - type: array items: {} - type: object additionalProperties: true instructions: type: string nullable: true description: Instructions added to the model context. max_output_tokens: type: integer minimum: 1 nullable: true description: The maximum number of output tokens. temperature: type: number nullable: true description: Controls response randomness. top_p: type: number nullable: true description: Controls nucleus sampling. stream: type: boolean nullable: true default: false description: Whether to return native Responses API server sent events. tools: type: array description: Function tool definitions. Hosted tools are not supported. items: type: object required: - type - name properties: type: type: string enum: ["function"] name: type: string minLength: 1 description: type: string nullable: true parameters: type: object nullable: true additionalProperties: true strict: type: boolean nullable: true tool_choice: description: Controls whether the model can call a function. oneOf: - type: string enum: ["none", "auto", "required"] - type: object required: - type - name properties: type: type: string enum: ["function"] name: type: string minLength: 1 parallel_tool_calls: type: boolean nullable: true description: Whether the model can return multiple function calls. reasoning: type: object description: OpenAI Responses reasoning configuration. additionalProperties: true text: type: object description: OpenAI Responses text output configuration. additionalProperties: true metadata: type: object nullable: true description: String metadata attached to the request. additionalProperties: type: string store: type: boolean nullable: true enum: [false] description: Responses are not persisted. Omit this field or set it to false. background: type: boolean nullable: true enum: [false] description: Background responses are not supported. include: type: array nullable: true items: type: string description: Additional response fields to include. truncation: type: string nullable: true enum: ["auto", "disabled"] service_tier: type: string nullable: true description: The OpenAI service tier forwarded to the model provider. example: model: "gpt-5-mini" input: "Write a short poem about cats." store: false responses: "200": description: Successful response or event stream. content: application/json: schema: $ref: "#/components/schemas/CreateResponseResponse" example: id: "resp_09e99d1f7f163d10016a678387353481" object: "response" created_at: 1785168775 status: "completed" model: "gpt-5-mini-2025-08-07" output: - id: "rs_09e99d1f7f163d10016a678387f47881" type: "reasoning" content: [] summary: [] - id: "msg_09e99d1f7f163d10016a67838935a881" type: "message" status: "completed" role: "assistant" content: - type: "output_text" annotations: [] logprobs: [] text: "Whiskers sketch moonlight on the sill,\npaws treading silence, soft and still.\nEyes like lanterns, sly and bright,\nturning midnight into light.\nA velvet sigh, a sudden purr—\nthe world made small, the heart made her." usage: input_tokens: 13 input_tokens_details: cached_tokens: 0 output_tokens: 154 output_tokens_details: reasoning_tokens: 64 total_tokens: 167 text/event-stream: schema: type: string description: Native OpenAI Responses API server sent events. "400": description: Invalid fields, unsupported features, or an unavailable model. "401": description: Missing, invalid, or expired API key. "403": description: API key without the Completion API scope. "413": description: Request body exceeds 20 MB. "429": description: Usage or rate limit exceeded. "500": description: Internal server or upstream provider error. default: description: Error returned by the upstream model provider. content: application/json: schema: type: object required: - error properties: error: type: object required: - message - type properties: message: type: string type: type: string code: type: string nullable: true param: type: string nullable: true security: - bearerAuth: [] /openai/{region}/v1/images/generations: post: tags: - Images summary: Generates one standard image as base64. description: Generates one standard-resolution image with a Completion API key. Returns b64_json only. Does not support n other than 1, URL output, HD, or image edits. A detected safety refusal returns 400 with a stable content filter message. operationId: createImage parameters: - name: region in: path required: true description: The region of the API to use. Must be eu or us. schema: type: string enum: ["eu", "us"] default: eu requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - model - prompt properties: model: type: string minLength: 1 description: Image generation model ID from your workspace. GET /openai/{region}/v1/models lists chat models, not image models. prompt: type: string minLength: 1 description: The image description. n: type: integer enum: [1] description: Number of images. Only 1 is supported. size: type: string enum: ["auto", "1024x1024", "1536x1024", "1024x1536"] default: auto description: Output size. auto and 1024x1024 map to square, 1536x1024 to landscape, and 1024x1536 to portrait. quality: type: string enum: ["auto", "low", "medium", "high"] description: Quality hint forwarded to the image model. Not every image model uses it. response_format: type: string enum: ["b64_json"] description: Response format. Only b64_json is supported. user: type: string description: Optional end-user identifier. Accepted for OpenAI compatibility. example: model: "your-image-model-id" prompt: "A lighthouse at dusk" n: 1 size: "1024x1024" response_format: "b64_json" responses: "200": description: OK headers: ld-model-id: description: The image model ID used for the request. schema: type: string content: application/json: schema: type: object required: - created - data properties: created: type: integer description: Unix timestamp in seconds. data: type: array minItems: 1 maxItems: 1 items: type: object required: - b64_json properties: b64_json: type: string description: Base64-encoded image. revised_prompt: type: string description: Revised prompt when the model returns one. example: created: 1721722200 data: - b64_json: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==" revised_prompt: "A coastal lighthouse at dusk, warm lantern light." "400": description: Invalid fields, an unavailable image model, no image models in the region, or a detected safety refusal by the image model. Refused requests are not billed. content: application/json: schema: type: object properties: message: description: Error message. Validation errors return a list of issues instead of a string. example: message: "The image generation request was blocked by the content filter of the Image Model." "401": description: Missing, invalid, or expired API key. "403": description: API key without the Completion API scope. "429": description: Usage or rate limit exceeded. "504": description: The model did not respond in time. Please retry. "500": description: Internal server or upstream provider error. security: - bearerAuth: [] /openai/{region}/v1/embeddings: post: tags: - Embeddings summary: Creates embeddings for the given input text. parameters: - name: region in: path required: true description: The region of the API to use. schema: type: string enum: ["eu", "us"] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateEmbeddingRequest" example: model: "text-embedding-ada-002" input: "The quick brown fox jumps over the lazy dog" encoding_format: "float" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/CreateEmbeddingResponse" example: data: - embedding: [0.0023064255, -0.009327292, ...] index: 0 object: "embedding" model: "text-embedding-ada-002" object: "list" usage: prompt_tokens: 9 total_tokens: 9 "400": description: Bad Request content: application/json: schema: type: object properties: message: type: string oneOf: - example: "No embedding models available for the ${region} region" description: Error message indicating either no models are available in the region or the requested model is not available "401": description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: "The provided API key is invalid." "429": description: Rate Limit Exceeded content: application/json: schema: type: object properties: message: type: string example: "Rate limit for public API exceeded" "500": description: Internal Server Error content: application/json: schema: type: object properties: message: type: string example: "Internal Server Error" security: - bearerAuth: [] /anthropic/{region}/v1/messages: post: tags: - Messages summary: Create a Message description: |- Create a Message. Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. The Messages API can be used for either single queries or stateless multi-turn conversations. parameters: - name: region in: path required: true description: The region of the API to use. schema: type: string enum: ["eu", "us"] operationId: messages_post responses: "200": description: Message object. content: application/json: schema: $ref: "#/components/schemas/Message" 4XX: description: |- Error response. See Anthropic's [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "504": description: The model did not respond in time on a non-streaming request. content: application/json: schema: type: object properties: message: type: string example: The model did not respond in time. Please retry. requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateMessageParams" required: true security: - bearerAuth: [] /mistral/{region}/v1/fim/completions: post: summary: Fim Completion description: FIM completion. parameters: - name: region in: path required: true description: The region of the API to use. schema: type: string enum: ["eu"] operationId: fim_completion_v1_fim_completions_post requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FIMCompletionRequest" example: model: "codestral-2501" prompt: "function removeSpecialCharactersWithRegex(str: string) {" max_tokens: 64 responses: "200": description: Successful Response content: application/json: schema: { $ref: "#/components/schemas/FIMCompletionResponse" } example: data: "asd" id: "245c52bc936f53ba90327800c73d1c3e" object: "chat.completion" model: "codestral" usage: prompt_tokens: 16 completion_tokens: 102 total_tokens: 118 created: 1732902806 choices: - index: 0 message: content: "\n // Use a regular expression to match any non-alphanumeric character and replace it with an empty string\n return str.replace(/[^a-zA-Z0-9]/g, '');\n}\n\n// Test the function\nconst inputString = \"Hello, World! 123\";\nconst outputString = removeSpecialCharactersWithRegex(inputString);\nconsole.log(outputString); // Output: \"HelloWorld123\"" prefix: false role: "assistant" finish_reason: "stop" text/event-stream: schema: $ref: "#/components/schemas/CompletionEvent" tags: - fim /google/{region}/v1beta/models/{model}:generateContent: post: tags: - Google summary: Generate Content description: |- Generate content using Google Gemini models. This endpoint mirrors the structure of the official Vertex AI generateContent API while adding API-key based authentication and region selection. parameters: - name: region in: path required: true description: The region of the API to use. schema: type: string enum: ["eu", "us"] - name: model in: path required: true description: The model ID (e.g., gemini-2.5-pro, gemini-2.5-flash). schema: type: string operationId: google_generate_content_post requestBody: required: true content: application/json: schema: type: object properties: contents: type: array description: Conversation history. Parts may be text, functionCall, or functionResponse. items: type: object properties: role: type: string enum: ["user", "model"] parts: type: array items: type: object properties: text: type: string thoughtSignature: type: string description: Return unchanged on the follow-up turn (required for Gemini 3). functionCall: type: object properties: name: type: string args: type: object id: type: string description: Return unchanged on the follow-up turn (required for Gemini 3). functionResponse: type: object properties: name: type: string response: type: object id: type: string description: Return unchanged on the follow-up turn (required for Gemini 3). required: - contents example: contents: - role: "user" parts: - text: "Write a short haiku about the ocean." responses: "200": description: Successful Response content: application/json: schema: type: object properties: candidates: type: array items: type: object properties: content: type: object finishReason: type: string usageMetadata: type: object 4XX: description: Error response content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" security: - bearerAuth: [] /knowledge: get: summary: List Knowledge bases accessible to the API key parameters: - name: limit in: query required: false description: Number of Knowledge bases to return. Default 50. Maximum 100. schema: type: integer minimum: 1 maximum: 100 default: 50 - name: cursor in: query required: false description: UUID of the last Knowledge base from the previous page schema: type: string format: uuid responses: "200": description: Knowledge bases retrieved successfully security: - bearerAuth: [] /knowledge/{folderId}/access: post: summary: Grant Knowledge base access to people or workspace API keys parameters: - name: folderId in: path required: true description: The ID of the knowledge folder schema: type: string requestBody: required: true content: application/json: schema: type: object required: - targetIds - role properties: targetIds: type: array items: type: string format: uuid minItems: 1 maxItems: 100 role: type: string enum: - USER - EDITOR responses: "200": description: Access granted successfully security: - bearerAuth: [] patch: summary: Change Knowledge base access for a person or workspace API key parameters: - name: folderId in: path required: true description: The ID of the knowledge folder schema: type: string requestBody: required: true content: application/json: schema: type: object required: - type - targetId - role properties: type: type: string enum: - USER - API_KEY targetId: type: string format: uuid role: type: string enum: - USER - EDITOR responses: "200": description: Access updated successfully security: - bearerAuth: [] delete: summary: Revoke Knowledge base access for a person or workspace API key parameters: - name: folderId in: path required: true description: The ID of the knowledge folder schema: type: string requestBody: required: true content: application/json: schema: type: object required: - type - targetId properties: type: type: string enum: - USER - API_KEY targetId: type: string format: uuid responses: "200": description: Access revoked successfully security: - bearerAuth: [] /knowledge/{folderId}/folder: patch: summary: Update a Knowledge base name or description parameters: - name: folderId in: path required: true description: The ID of the knowledge folder schema: type: string requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: type: string responses: "200": description: Knowledge base updated successfully security: - bearerAuth: [] /knowledge/search: post: summary: Search through all files in data folders shared with the API Key parameters: [] requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string description: The search query example: "API Documentation" responses: "200": description: Successfully found search result security: - bearerAuth: [] /knowledge/{folderId}: post: summary: Upload a file to a knowledge folder parameters: - name: folderId in: path required: true description: The ID of the knowledge folder schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: The file to upload url: type: string description: The associated URL responses: "200": description: File uploaded successfully "400": description: Invalid request or file validation failed content: application/json: schema: oneOf: - type: object additionalProperties: false required: - message - code properties: message: type: string example: The file "quarterly-report.pdf" is declared as a PDF but its content does not start with the expected PDF header. code: type: string enum: - BAD_REQUEST - type: object additionalProperties: false required: - message - errors properties: message: type: string example: Invalid request errors: type: array items: type: object "401": description: Invalid or missing API key content: application/json: schema: type: object required: - message properties: message: type: string example: The provided API key is invalid. "403": description: API key does not have access to the knowledge folder content: application/json: schema: oneOf: - type: object additionalProperties: false required: - message - code properties: message: type: string example: Knowledge folder not shared with this API key. Please share the folder with the API key in the Langdock App to upload or update files. code: type: string enum: - FORBIDDEN - type: object additionalProperties: false required: - message - error - details properties: message: type: string example: Insufficient API key permissions. error: type: string enum: - INSUFFICIENT_SCOPES details: type: object required: - required - missing properties: required: type: array items: type: string example: KNOWLEDGE_FOLDER_API missing: type: array items: type: string example: KNOWLEDGE_FOLDER_API - type: object additionalProperties: false required: - message properties: message: type: string example: Forbidden "404": description: Knowledge folder not found content: application/json: schema: type: object required: - message - code properties: message: type: string example: Knowledge folder not found code: type: string enum: - NOT_FOUND "408": description: Upload timed out content: application/json: schema: type: object required: - message - code properties: message: type: string example: Upload request timed out. Please try again with a smaller file or check your connection. code: type: string enum: - REQUEST_TIMEOUT "413": description: File exceeds the size limit content: application/json: schema: type: object required: - message - code properties: message: type: string example: File size exceeds the maximum allowed size of 256MB. Please upload a smaller file. code: type: string enum: - PAYLOAD_TOO_LARGE "429": description: Rate limit exceeded content: application/json: schema: type: object required: - message properties: message: type: string example: You have exceeded the maximum number of requests per minute (50) code: type: string enum: - TOO_MANY_REQUESTS "500": description: Unexpected server error content: application/json: schema: type: object required: - message properties: message: type: string example: Internal server error "503": description: Storage capacity exceeded content: application/json: schema: type: object required: - message - code properties: message: type: string example: Storage capacity exceeded. Please contact your administrator. code: type: string enum: - SERVICE_UNAVAILABLE security: - bearerAuth: [] patch: summary: Update a file in a knowledge folder parameters: - name: folderId in: path required: true description: The ID of the knowledge folder schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: The new file to upload url: type: string description: URL that is shown to the user if the file is used in an answer attachmentId: type: string description: The ID of the attachment to update responses: "200": description: Attachment updated successfully "400": description: Invalid request or file validation failed content: application/json: schema: oneOf: - type: object additionalProperties: false required: - message - code properties: message: type: string example: The file "updated-report.pdf" is declared as a PDF but its content does not start with the expected PDF header. code: type: string enum: - BAD_REQUEST - type: object additionalProperties: false required: - message - errors properties: message: type: string example: Invalid request errors: type: array items: type: object "401": description: Invalid or missing API key content: application/json: schema: type: object required: - message properties: message: type: string example: The provided API key is invalid. "403": description: API key does not have access to the knowledge folder content: application/json: schema: oneOf: - type: object additionalProperties: false required: - message - code properties: message: type: string example: Knowledge folder not shared with this API key. Please share the folder with the API key in the Langdock App to upload or update files. code: type: string enum: - FORBIDDEN - type: object additionalProperties: false required: - message - error - details properties: message: type: string example: Insufficient API key permissions. error: type: string enum: - INSUFFICIENT_SCOPES details: type: object required: - required - missing properties: required: type: array items: type: string example: KNOWLEDGE_FOLDER_API missing: type: array items: type: string example: KNOWLEDGE_FOLDER_API - type: object additionalProperties: false required: - message properties: message: type: string example: Forbidden "404": description: Knowledge folder or attachment not found content: application/json: schema: type: object required: - message - code properties: message: type: string example: Attachment with ID '550e8400-e29b-41d4-a716-446655440000' not found in this knowledge folder. code: type: string enum: - NOT_FOUND "408": description: Upload timed out content: application/json: schema: type: object required: - message - code properties: message: type: string example: Upload request timed out. Please try again with a smaller file or check your connection. code: type: string enum: - REQUEST_TIMEOUT "413": description: File exceeds the size limit content: application/json: schema: type: object required: - message - code properties: message: type: string example: File size exceeds the maximum allowed size of 256MB. Please upload a smaller file. code: type: string enum: - PAYLOAD_TOO_LARGE "429": description: Rate limit exceeded content: application/json: schema: type: object required: - message properties: message: type: string example: You have exceeded the maximum number of requests per minute (50) code: type: string enum: - TOO_MANY_REQUESTS "500": description: Unexpected server error content: application/json: schema: type: object required: - message properties: message: type: string example: Internal server error "503": description: Storage capacity exceeded content: application/json: schema: type: object required: - message - code properties: message: type: string example: Storage capacity exceeded. Please contact your administrator. code: type: string enum: - SERVICE_UNAVAILABLE security: - bearerAuth: [] /knowledge/{folderId}/list: get: summary: Retrieve files from a knowledge folder parameters: - name: folderId in: path required: true description: The ID of the knowledge folder schema: type: string responses: "200": description: List of files retrieved successfully security: - bearerAuth: [] /knowledge/{folderId}/{attachmentId}: delete: summary: Delete a file from a knowledge folder parameters: - name: folderId in: path required: true description: The ID of the knowledge folder schema: type: string - name: attachmentId in: path required: true description: The ID of the attachment to delete schema: type: string responses: "200": description: Attachment deleted successfully security: - bearerAuth: [] /agent/v1/chat/completions: post: tags: - Agent summary: Creates a chat completion with an agent (Vercel AI SDK compatible) description: Creates a model response using Vercel AI SDK compatible UIMessage format parameters: [] requestBody: required: true content: application/json: examples: streamingEnabled: summary: Request with streaming enabled value: agentId: "agent_123" messages: - id: "msg_1" role: "user" parts: - type: "text" text: "Hello, how can you help me?" stream: true schema: type: object oneOf: - type: object required: [agentId, messages] properties: agentId: type: string description: ID of an existing agent to use messages: type: array description: Array of UIMessage objects (Vercel AI SDK format) items: type: object required: - id - role - parts properties: id: type: string description: Unique message identifier role: type: string enum: [user, assistant, system, tool] description: Extra history messages with role system stay as user context. A last message that is not user is dropped. parts: type: array items: type: object required: - type properties: type: type: string enum: [text, file, tool-invocation, tool-result] text: type: string description: Text content for text parts url: type: string description: File URL for file parts name: type: string description: File name mimeType: type: string description: MIME type of the file toolCallId: type: string description: Tool call identifier toolName: type: string description: Name of the tool args: type: object description: Tool arguments result: type: object description: Tool result stream: type: boolean default: false output: $ref: "#/components/schemas/StructuredOutputConfig" imageResponseFormat: type: string enum: [url, b64_json] description: 'Response format for images generated by the agent. "url" returns a signed URL, "b64_json" returns base64-encoded image data.' responses: "200": description: Successful chat completion content: application/json: schema: type: object description: UIMessage response (Vercel AI SDK format) required: - id - role - parts properties: id: type: string role: type: string enum: [assistant] parts: type: array items: type: object output: description: Structured output if requested "400": description: Invalid request parameters, or an attached integration file the API key cannot read. One unreadable file stops the call even when other files are readable, and for that error the message and `details.attachmentIds` list the attachment IDs. "429": description: Rate limit exceeded, or the integration rate-limited the access check for an attached integration file. For the access check, the message and `details.attachmentIds` list the attachment IDs. "500": description: Internal server error "503": description: Access check unavailable for an attached integration file. The message lists the attachment IDs, and the response has no `details`. /agent/v1/create: post: operationId: createAgentV2 summary: Creates a new agent description: Creates a new agent in your workspace programmatically. tags: [Agent Build] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AssistantCreateRequest" responses: "201": description: Agent created successfully content: application/json: schema: type: object required: - status - message - agent properties: status: type: string enum: [success] message: type: string agent: $ref: "#/components/schemas/AssistantDetails" /agent/v1/update: patch: operationId: updateAgentV2 summary: Updates an existing agent description: Updates an existing agent in your workspace. Configuration updates apply to the draft; access changes take effect immediately without publishing. When `actions` is provided, the array replaces the draft list. Ids already on the draft that are missing or soft-deleted are dropped. Ids already on the draft whose integration is not enabled stay. A brand-new missing or unavailable id returns 400. The success body includes `preservedUnavailableActionIds` only when unavailable draft ids were kept. tags: [Agent Build] requestBody: required: true content: application/json: schema: allOf: - type: object required: [agentId] properties: agentId: type: string format: uuid - $ref: "#/components/schemas/AssistantWriteRequest" responses: "200": description: Agent updated successfully content: application/json: schema: type: object required: - status - message - agent properties: status: type: string enum: [success] message: type: string example: "Agent updated successfully" agent: $ref: "#/components/schemas/AssistantDetails" preservedUnavailableActionIds: type: array items: type: string format: uuid description: Unavailable action ids already on the draft that were kept. Omitted when empty. /agent/v1/publish: post: operationId: publishAgentV2 summary: Publishes a draft agent as a new version description: Publishes the current draft of an agent as a new version. Mirrors the "Update" button in the agent editor — only agents (not projects) are supported, and the draft must differ from the latest published version. tags: [Agent Build] requestBody: required: true content: application/json: schema: type: object required: [agentId] properties: agentId: type: string format: uuid description: UUID of the agent to publish description: type: string minLength: 1 maxLength: 500 description: Optional change description shown in version history responses: "200": description: Agent published successfully content: application/json: schema: type: object required: - status - message - version properties: status: type: string message: type: string version: type: object properties: id: type: string format: uuid version: type: integer createdAt: type: string format: date-time "403": description: API key lacks edit access, agent is in a different workspace, or the resource is a project "409": description: No draft changes to publish /agent/v1/get: get: operationId: getAgentV2 summary: Retrieves details of an existing agent description: Retrieves the current settings and details available for an existing agent. Returns the published version when one exists, otherwise the draft. The `actions` array omits missing and soft-deleted action ids and still includes live actions that are unavailable in the workspace. tags: [Agent Build] parameters: - name: agentId in: query required: true schema: type: string format: uuid responses: "200": description: Agent retrieved successfully content: application/json: schema: type: object required: - status - agent properties: status: type: string agent: $ref: "#/components/schemas/AssistantDetails" /agent/v1/models: get: tags: - Agent summary: Lists the available models description: Returns a list of models that are available for use with the API. parameters: [] responses: "200": description: List of available models content: application/json: schema: type: object required: - object - data properties: object: type: string enum: [list] data: type: array items: type: object properties: id: type: string description: Value to send as model. The deployment name when it maps to one accessible row, otherwise the model UUID. name: type: string description: Deployment name for the row. object: type: string created: type: integer region: type: string description: Region where the model is available. supportsExtendedThinking: type: boolean description: Whether this model supports extended thinking mode. /attachment/v1/upload: post: operationId: uploadAttachment summary: Upload an attachment description: Upload a file that can be referenced in Agent conversations. tags: [Attachments] parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file to upload responses: "200": description: Successfully uploaded file content: application/json: schema: type: object required: - attachmentId - file properties: attachmentId: type: string format: uuid description: Unique identifier for the uploaded attachment example: 550e8400-e29b-41d4-a716-446655440000 file: type: object required: - name - mimeType - sizeInBytes properties: name: type: string description: Original filename example: example.pdf mimeType: type: string description: MIME type of the file example: application/pdf sizeInBytes: type: integer description: Size of the file in bytes example: 1234567 example: attachmentId: 550e8400-e29b-41d4-a716-446655440000 file: name: example.pdf mimeType: application/pdf sizeInBytes: 1234567 "400": description: Invalid upload request or file validation failed content: application/json: schema: oneOf: - type: object additionalProperties: false required: - message - code properties: message: type: string description: The reason the file failed validation example: The file "example.pdf" is declared as a PDF but its content does not start with the expected PDF header. code: type: string enum: - BAD_REQUEST - type: object additionalProperties: false required: - error properties: error: type: string example: No file provided - type: object additionalProperties: false required: - message properties: message: type: string example: File name or mime type not found examples: fileValidation: summary: File validation failed value: message: The file "example.pdf" is declared as a PDF but its content does not start with the expected PDF header. code: BAD_REQUEST missingFile: summary: No file provided value: error: No file provided missingMetadata: summary: File metadata missing value: message: File name or mime type not found "401": description: Invalid API key content: application/json: schema: type: object required: - message properties: message: type: string example: The provided API key is invalid. example: message: The provided API key is invalid. "403": description: API key does not have the required scope content: application/json: schema: type: object required: - message properties: message: type: string example: Insufficient API key permissions. error: type: string example: INSUFFICIENT_SCOPES details: type: object required: - required - missing properties: required: type: array items: type: string example: KNOWLEDGE_FOLDER_API missing: type: array items: type: string example: KNOWLEDGE_FOLDER_API example: message: Insufficient API key permissions. error: INSUFFICIENT_SCOPES details: required: - KNOWLEDGE_FOLDER_API missing: - KNOWLEDGE_FOLDER_API "406": description: File type not allowed content: application/json: schema: type: object required: - message properties: message: type: string description: The reason the file type was blocked example: File type not allowed. Detected executable content. example: message: File type not allowed. Detected executable content. "413": description: File exceeds the size limit content: application/json: schema: type: object required: - message properties: message: type: string description: The file size limit that was exceeded example: File size exceeds the limit. Max size for this file type is 256MB example: message: File size exceeds the limit. Max size for this file type is 256MB "429": description: Rate limit exceeded content: application/json: schema: type: object required: - message properties: message: type: string example: You have exceeded the maximum number of requests per minute (500) example: message: You have exceeded the maximum number of requests per minute (500) "500": description: Internal server error content: application/json: schema: type: object required: - message properties: message: type: string example: Internal server error example: message: Internal server error /attachment/v1/delete: delete: operationId: deleteAttachment summary: Delete an attachment description: Soft-deletes an attachment by ID. The attachment must be created by the key owner or belong to a Knowledge base shared with the API key. tags: [Attachments] parameters: [] requestBody: required: true content: application/json: schema: type: object required: - attachmentId properties: attachmentId: type: string format: uuid description: The ID of the attachment to delete responses: "200": description: Attachment deleted successfully content: application/json: schema: type: object required: - success - message - attachmentId properties: success: type: boolean example: true message: type: string example: "Attachment deleted successfully" attachmentId: type: string format: uuid description: The ID of the deleted attachment "400": description: Invalid request body content: application/json: schema: type: object properties: message: type: string errors: type: array items: {} "401": description: Invalid API key content: application/json: schema: type: object properties: error: type: string "403": description: API key does not have access to this attachment content: application/json: schema: type: object properties: message: type: string "404": description: Attachment not found content: application/json: schema: type: object properties: message: type: string "500": description: Internal server error content: application/json: schema: type: object properties: message: type: string /skills/v1: get: operationId: listSkills summary: List Skills description: Returns Skills in your workspace. tags: [Skills] parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 250 default: 50 description: Number of Skills to return. - name: cursor in: query required: false schema: type: string format: uuid description: Cursor from the previous response for pagination. - name: query in: query required: false schema: type: string description: Search query for matching Skills. - name: slug in: query required: false schema: type: string maxLength: 100 pattern: "^[a-z0-9-]+$" description: Filter by Skill slug. responses: "200": description: Skills returned successfully content: application/json: schema: $ref: "#/components/schemas/ListSkillsResponse" "400": description: Invalid query parameter "401": description: Invalid or missing API key "403": description: Missing required scope or access "429": description: Rate limit exceeded "500": description: Internal server error post: operationId: createSkill summary: Create a Skill description: Creates a Skill in your workspace. tags: [Skills] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateSkillRequest" responses: "201": description: Skill created successfully content: application/json: schema: $ref: "#/components/schemas/SkillResponse" "400": description: Invalid request body "401": description: Invalid or missing API key "403": description: Missing required scope or create permission "409": description: Skill slug conflict "429": description: Rate limit exceeded "500": description: Internal server error /skills/v1/{skillId}: get: operationId: getSkill summary: Get a Skill description: Retrieves a Skill by ID from your workspace, including metadata for every stored file. tags: [Skills] parameters: - $ref: "#/components/parameters/SkillId" responses: "200": description: Skill returned successfully content: application/json: schema: $ref: "#/components/schemas/GetSkillResponse" "400": description: Invalid Skill ID "401": description: Invalid or missing API key "403": description: Missing required scope or access "404": description: Skill not found "429": description: Rate limit exceeded "500": description: Internal server error patch: operationId: updateSkill summary: Update a Skill description: Updates an existing Skill in your workspace. tags: [Skills] parameters: - $ref: "#/components/parameters/SkillId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateSkillRequest" responses: "200": description: Skill updated successfully content: application/json: schema: $ref: "#/components/schemas/SkillResponse" "400": description: Invalid request body "401": description: Invalid or missing API key "403": description: Missing required scope or editor access "404": description: Skill not found "409": description: Skill slug conflict "429": description: Rate limit exceeded "500": description: Internal server error delete: operationId: deleteSkill summary: Delete a Skill description: Permanently deletes a Skill from your workspace. tags: [Skills] parameters: - $ref: "#/components/parameters/SkillId" responses: "200": description: Skill deleted successfully content: application/json: schema: type: object required: - success properties: success: type: boolean example: true "400": description: Invalid Skill ID "401": description: Invalid or missing API key "403": description: Missing required scope or owner access "404": description: Skill not found "429": description: Rate limit exceeded "500": description: Internal server error /skills/v1/{skillId}/files: get: operationId: getSkillFile summary: Get a Skill file description: Retrieves a stored Skill file by path from your workspace. tags: [Skills] parameters: - $ref: "#/components/parameters/SkillId" - name: path in: query required: true description: Relative path of the file inside the Skill. schema: type: string minLength: 1 maxLength: 255 responses: "200": description: File returned successfully content: application/json: schema: $ref: "#/components/schemas/SkillFileContent" "400": description: Invalid Skill ID, invalid path, unsupported file type, invalid UTF-8, or file larger than 512 KB "401": description: Invalid or missing API key "403": description: Missing required scope or access "404": description: Skill or file not found "429": description: Rate limit exceeded "500": description: Internal server error /skills/v1/import: post: operationId: importSkill summary: Import a Skill description: Creates or updates a Skill from a SKILL.md file or zip archive. tags: [Skills] requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/ImportSkillRequest" responses: "200": description: Existing Skill updated successfully content: application/json: schema: $ref: "#/components/schemas/ImportSkillResponse" "201": description: Skill created successfully content: application/json: schema: $ref: "#/components/schemas/ImportSkillResponse" "400": description: Invalid form data or zip archive "401": description: Invalid or missing API key "403": description: Missing required scope or Skill permission "409": description: Existing slug conflict or ambiguous upsert slug "413": description: Uploaded file is too large "429": description: Rate limit exceeded "500": description: Internal server error /prompts/v1: get: operationId: listPrompts summary: List prompts description: Returns prompts you can access in your workspace. tags: [Prompts] parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 250 default: 50 description: Number of prompts to return. - name: cursor in: query required: false schema: type: string format: uuid description: Cursor from the previous response for pagination. - name: query in: query required: false schema: type: string description: Search query matched against prompt title and content. - name: promptFolderId in: query required: false schema: type: string format: uuid description: Filter by prompt folder UUID. - name: sharedWithWorkspace in: query required: false schema: type: string enum: ["true", "false"] description: Filter by workspace sharing. responses: "200": description: Prompts returned successfully content: application/json: schema: $ref: "#/components/schemas/ListPromptsResponse" "400": description: Invalid query parameter "401": description: Invalid or missing API key "403": description: Missing required scope or access "429": description: Rate limit exceeded "500": description: Internal server error post: operationId: createPrompt summary: Create a prompt description: Creates a prompt in your workspace. tags: [Prompts] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreatePromptRequest" responses: "201": description: Prompt created successfully content: application/json: schema: $ref: "#/components/schemas/PromptResponse" "400": description: Invalid request body "401": description: Invalid or missing API key "403": description: Missing required scope, share permission, or folder write access "404": description: Prompt folder not found "429": description: Rate limit exceeded "500": description: Internal server error /prompts/v1/{promptId}: get: operationId: getPrompt summary: Get a prompt description: Retrieves a prompt by ID from your workspace. tags: [Prompts] parameters: - $ref: "#/components/parameters/PromptId" responses: "200": description: Prompt returned successfully content: application/json: schema: $ref: "#/components/schemas/PromptResponse" "400": description: Invalid prompt ID "401": description: Invalid or missing API key "403": description: Missing required scope or access "404": description: Prompt not found "429": description: Rate limit exceeded "500": description: Internal server error patch: operationId: updatePrompt summary: Update a prompt description: Updates an existing prompt in your workspace. tags: [Prompts] parameters: - $ref: "#/components/parameters/PromptId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdatePromptRequest" responses: "200": description: Prompt updated successfully content: application/json: schema: $ref: "#/components/schemas/PromptResponse" "400": description: Invalid request body "401": description: Invalid or missing API key "403": description: Missing required scope, write access, or share permission "404": description: Prompt or prompt folder not found "429": description: Rate limit exceeded "500": description: Internal server error delete: operationId: deletePrompt summary: Delete a prompt description: Permanently deletes a prompt from your workspace. tags: [Prompts] parameters: - $ref: "#/components/parameters/PromptId" responses: "200": description: Prompt deleted successfully content: application/json: schema: type: object required: - success properties: success: type: boolean example: true "400": description: Invalid prompt ID "401": description: Invalid or missing API key "403": description: Missing required scope or write access "404": description: Prompt not found "429": description: Rate limit exceeded "500": description: Internal server error /prompts/v1/folders: get: operationId: listPromptFolders summary: List prompt folders description: Returns prompt folders you can access in your workspace. tags: [Prompts] parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 250 default: 50 description: Number of folders to return. - name: cursor in: query required: false schema: type: string format: uuid description: Cursor from the previous response for pagination. - name: query in: query required: false schema: type: string description: Search query matched against folder name. - name: sharedWithWorkspace in: query required: false schema: type: string enum: ["true", "false"] description: Filter by workspace sharing. responses: "200": description: Prompt folders returned successfully content: application/json: schema: $ref: "#/components/schemas/ListPromptFoldersResponse" "400": description: Invalid query parameter "401": description: Invalid or missing API key "403": description: Missing required scope or access "429": description: Rate limit exceeded "500": description: Internal server error post: operationId: createPromptFolder summary: Create a prompt folder description: Creates a prompt folder in your workspace. tags: [Prompts] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreatePromptFolderRequest" responses: "201": description: Prompt folder created successfully content: application/json: schema: $ref: "#/components/schemas/PromptFolderResponse" "400": description: Invalid request body "401": description: Invalid or missing API key "403": description: Missing required scope or share permission "404": description: Group not found "429": description: Rate limit exceeded "500": description: Internal server error /prompts/v1/folders/{folderId}: get: operationId: getPromptFolder summary: Get a prompt folder description: Retrieves a prompt folder by ID from your workspace. tags: [Prompts] parameters: - $ref: "#/components/parameters/PromptFolderId" responses: "200": description: Prompt folder returned successfully content: application/json: schema: $ref: "#/components/schemas/PromptFolderResponse" "400": description: Invalid folder ID "401": description: Invalid or missing API key "403": description: Missing required scope or access "404": description: Prompt folder not found "429": description: Rate limit exceeded "500": description: Internal server error patch: operationId: updatePromptFolder summary: Update a prompt folder description: Updates an existing prompt folder in your workspace. tags: [Prompts] parameters: - $ref: "#/components/parameters/PromptFolderId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdatePromptFolderRequest" responses: "200": description: Prompt folder updated successfully content: application/json: schema: $ref: "#/components/schemas/PromptFolderResponse" "400": description: Invalid request body "401": description: Invalid or missing API key "403": description: Missing required scope or manage access "404": description: Prompt folder or group not found "429": description: Rate limit exceeded "500": description: Internal server error delete: operationId: deletePromptFolder summary: Delete a prompt folder description: Permanently deletes a prompt folder and the prompts in it. tags: [Prompts] parameters: - $ref: "#/components/parameters/PromptFolderId" responses: "200": description: Prompt folder deleted successfully content: application/json: schema: type: object required: - success properties: success: type: boolean example: true "400": description: Invalid folder ID "401": description: Invalid or missing API key "403": description: Missing required scope or manage access "404": description: Prompt folder not found "429": description: Rate limit exceeded "500": description: Internal server error /export/agents: post: tags: - Usage Export summary: Export agent usage data description: Export detailed usage data for all agents in the workspace parameters: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UsageExportModelGroupByRequest" example: from: date: "2024-01-01T00:00:00.000Z" timezone: "UTC" to: date: "2024-01-31T23:59:59.999Z" timezone: "UTC" responses: "200": description: Export successful content: application/json: schema: $ref: "#/components/schemas/UsageExportResponse" example: success: true data: filePath: "assistants-usage/workspace-id/assistants-usage-2024-01-01-2024-01-31-abc12345.csv" downloadUrl: "https://storage.example.com/signed-url" dataType: "assistants" recordCount: 1250 dateRange: from: "2024-01-01T00:00:00.000Z" to: "2024-01-31T23:59:59.999Z" "400": description: Bad Request - Export too large or invalid date range content: application/json: schema: $ref: "#/components/schemas/UsageExportError" example: message: "Export too large: more than 1,000,000 usage rows for the selected date range. Try a shorter date range and combine the CSV files." code: "USAGE_EXPORT_TOO_LARGE" details: usageRows: 1500000 limit: 1000000 "401": description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: "#/components/schemas/UsageExportError" example: message: "The provided API key is invalid." "404": description: No data found for the selected period content: application/json: schema: $ref: "#/components/schemas/UsageExportError" example: message: "No usage data found for the selected period" code: "NOT_FOUND" /export/users: post: tags: - Usage Export summary: Export user usage data description: Export detailed usage data for all users in the workspace (subject to privacy settings) parameters: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UsageExportUsersRequest" responses: "200": description: Export successful content: application/json: schema: $ref: "#/components/schemas/UsageExportResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/UsageExportError" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/UsageExportError" "404": description: No data found content: application/json: schema: $ref: "#/components/schemas/UsageExportError" /export/projects: post: tags: - Usage Export summary: Export project usage data description: Export detailed usage data for all projects in the workspace parameters: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UsageExportRequest" responses: "200": description: Export successful content: application/json: schema: $ref: "#/components/schemas/UsageExportResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/UsageExportError" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/UsageExportError" "404": description: No data found content: application/json: schema: $ref: "#/components/schemas/UsageExportError" /export/models: post: tags: - Usage Export summary: Export model usage data description: Export detailed usage data for all AI models used in the workspace parameters: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UsageExportModelsRequest" responses: "200": description: Export successful content: application/json: schema: $ref: "#/components/schemas/UsageExportResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/UsageExportError" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/UsageExportError" "404": description: No data found content: application/json: schema: $ref: "#/components/schemas/UsageExportError" /export/workflows: post: tags: - Usage Export summary: Export workflow usage data description: Export cost, run counts, and monthly cap utilization for workflows in the workspace parameters: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UsageExportRequest" responses: "200": description: Export successful content: application/json: schema: $ref: "#/components/schemas/UsageExportResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/UsageExportError" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/UsageExportError" "404": description: No data found content: application/json: schema: $ref: "#/components/schemas/UsageExportError" /export/api-keys: post: tags: - Usage Export summary: Export API key usage data description: Export detailed usage and cost data grouped by API key parameters: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UsageExportModelGroupByRequest" example: from: date: "2024-01-01T00:00:00.000Z" timezone: "UTC" to: date: "2024-01-31T23:59:59.999Z" timezone: "UTC" group_by: "model" responses: "200": description: Export successful content: application/json: schema: $ref: "#/components/schemas/UsageExportResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/UsageExportError" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/UsageExportError" "404": description: No data found content: application/json: schema: $ref: "#/components/schemas/UsageExportError" /automations/v1: get: operationId: listScheduledTasks tags: - Scheduled Tasks summary: List scheduled tasks description: Returns scheduled tasks owned by this key's member or service account, newest first. parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 250 default: 50 description: Number of scheduled tasks to return. - name: cursor in: query required: false schema: type: string format: uuid description: Task UUID from nextCursor in the previous response. responses: "200": description: Scheduled tasks returned successfully. nextCursor is present only when another page exists. Each task includes runCount. "400": description: Invalid limit or cursor "401": description: Invalid or missing API key, or the key user was not found "403": description: Missing AUTOMATION_API, Scheduled Tasks disabled, or the key has no access "405": description: Method not allowed "429": description: Rate limit exceeded "500": description: Internal server error post: operationId: createScheduledTask tags: - Scheduled Tasks summary: Create a scheduled task description: Creates a scheduled task owned by this key's member or service account. New tasks start active. The response does not include runCount. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - name - prompt - frequency properties: name: type: string minLength: 1 maxLength: 200 prompt: type: string minLength: 1 maxLength: 120000 frequency: type: string enum: - MANUAL - DAILY - WEEKDAYS - WEEKLY - MONTHLY - SELECTED_WEEKDAYS timeOfDay: type: string nullable: true description: 24 hour HH:mm. Required unless frequency is MANUAL. dayOfWeek: type: integer minimum: 0 maximum: 6 nullable: true description: Required for WEEKLY. 0 is Sunday and 6 is Saturday. dayOfMonth: type: integer minimum: 1 maximum: 31 nullable: true description: Required for MONTHLY. daysOfWeek: type: array maxItems: 7 items: type: integer minimum: 0 maximum: 6 description: Required for SELECTED_WEEKDAYS. timezone: type: string nullable: true maxLength: 64 description: IANA timezone. Empty or omitted on a scheduled frequency is stored as UTC. modelMode: type: string enum: - UNSET - EXPLICIT - AUTO modelId: type: string format: uuid nullable: true description: Required in the same request when modelMode is EXPLICIT. assistantId: type: string format: uuid nullable: true taggedAssistantId: type: string format: uuid nullable: true taggedIntegrationIds: type: array maxItems: 20 items: type: string format: uuid taggedKnowledgeFolderIds: type: array maxItems: 20 items: type: string format: uuid taggedWorkflowIds: type: array maxItems: 20 items: type: string format: uuid taggedSkillSlugs: type: array maxItems: 20 items: type: string maxLength: 100 attachmentIds: type: array maxItems: 20 items: type: string format: uuid responses: "201": description: Scheduled task created. The automation object does not include runCount. "400": description: Invalid body, or message AUTOMATION_LIMIT_REACHED "401": description: Invalid or missing API key, or the key user was not found "403": description: Missing AUTOMATION_API, Scheduled Tasks disabled, no product access, TRIAL_EXPIRED, or AUTOMATION_TAG_ACCESS_DENIED "405": description: Method not allowed "429": description: Rate limit exceeded "500": description: Internal server error /automations/v1/{automationId}: get: operationId: getScheduledTask tags: - Scheduled Tasks summary: Get a scheduled task description: Returns one scheduled task owned by this key's member or service account, including runCount. parameters: - name: automationId in: path required: true schema: type: string format: uuid responses: "200": description: Scheduled task returned successfully "400": description: Invalid task id "401": description: Invalid or missing API key, or the key user was not found "403": description: Missing AUTOMATION_API, Scheduled Tasks disabled, or the key has no access "404": description: Message AUTOMATION_NOT_FOUND "405": description: Method not allowed "429": description: Rate limit exceeded "500": description: Internal server error patch: operationId: updateScheduledTask tags: - Scheduled Tasks summary: Update a scheduled task description: Updates one scheduled task owned by this key's member or service account. Send at least one field. The response does not include runCount. The merged schedule is validated. parameters: - name: automationId in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object additionalProperties: false minProperties: 1 properties: name: type: string minLength: 1 maxLength: 200 prompt: type: string minLength: 1 maxLength: 120000 frequency: type: string enum: - MANUAL - DAILY - WEEKDAYS - WEEKLY - MONTHLY - SELECTED_WEEKDAYS timeOfDay: type: string nullable: true description: 24 hour HH:mm. Omitted keeps the stored value. dayOfWeek: type: integer minimum: 0 maximum: 6 nullable: true description: 0 is Sunday and 6 is Saturday. Omitted keeps the stored value. dayOfMonth: type: integer minimum: 1 maximum: 31 nullable: true description: Omitted keeps the stored value. daysOfWeek: type: array maxItems: 7 items: type: integer minimum: 0 maximum: 6 description: Omitted keeps the stored value. timezone: type: string nullable: true maxLength: 64 description: IANA timezone. Omitted keeps the stored value. Empty is stored as UTC on a scheduled frequency. modelMode: type: string enum: - UNSET - EXPLICIT - AUTO modelId: type: string format: uuid nullable: true description: Required in this request when modelMode is EXPLICIT. assistantId: type: string format: uuid nullable: true taggedAssistantId: type: string format: uuid nullable: true taggedIntegrationIds: type: array maxItems: 20 items: type: string format: uuid taggedKnowledgeFolderIds: type: array maxItems: 20 items: type: string format: uuid taggedWorkflowIds: type: array maxItems: 20 items: type: string format: uuid taggedSkillSlugs: type: array maxItems: 20 items: type: string maxLength: 100 attachmentIds: type: array maxItems: 20 items: type: string format: uuid responses: "200": description: Scheduled task updated. The automation object does not include runCount. "400": description: Invalid body, message At least one field must be provided, or an incomplete merged schedule "401": description: Invalid or missing API key, or the key user was not found "403": description: Missing AUTOMATION_API, Scheduled Tasks disabled, no product access, or AUTOMATION_TAG_ACCESS_DENIED "404": description: Message AUTOMATION_NOT_FOUND "405": description: Method not allowed "429": description: Rate limit exceeded "500": description: Internal server error delete: operationId: deleteScheduledTask tags: - Scheduled Tasks summary: Delete a scheduled task description: Deletes a scheduled task owned by this key's member or service account. parameters: - name: automationId in: path required: true schema: type: string format: uuid responses: "200": description: Scheduled task deleted "400": description: Invalid task id "401": description: Invalid or missing API key, or the key user was not found "403": description: Missing AUTOMATION_API, Scheduled Tasks disabled, or the key has no access "404": description: Message AUTOMATION_NOT_FOUND "405": description: Method not allowed "429": description: Rate limit exceeded "500": description: Internal server error /automations/v1/{automationId}/pause: post: operationId: pauseScheduledTask tags: - Scheduled Tasks summary: Pause a scheduled task description: Sets active to false. The response does not include runCount. parameters: - name: automationId in: path required: true schema: type: string format: uuid responses: "200": description: Scheduled task paused "400": description: Invalid task id "401": description: Invalid or missing API key, or the key user was not found "403": description: Missing AUTOMATION_API, Scheduled Tasks disabled, or the key has no access "404": description: Message AUTOMATION_NOT_FOUND "405": description: Method not allowed "429": description: Rate limit exceeded "500": description: Internal server error /automations/v1/{automationId}/resume: post: operationId: resumeScheduledTask tags: - Scheduled Tasks summary: Resume a scheduled task description: Sets active to true. The response does not include runCount. parameters: - name: automationId in: path required: true schema: type: string format: uuid responses: "200": description: Scheduled task resumed "400": description: Invalid task id "401": description: Invalid or missing API key, or the key user was not found "403": description: Missing AUTOMATION_API, Scheduled Tasks disabled, no product access, or code TRIAL_EXPIRED with message Your trial has expired. Upgrade to continue. "404": description: Message AUTOMATION_NOT_FOUND "405": description: Method not allowed "429": description: Rate limit exceeded "500": description: Internal server error /automations/v1/{automationId}/run: post: operationId: runScheduledTask tags: - Scheduled Tasks summary: Run a scheduled task description: Enqueues one run and returns immediately. conversationId is null. A paused task can be run, and active stays unchanged. parameters: - name: automationId in: path required: true schema: type: string format: uuid responses: "200": description: Run queued. Body is runId and conversationId null. "400": description: Invalid task id "401": description: Invalid or missing API key, or the key user was not found "403": description: Missing AUTOMATION_API, Scheduled Tasks disabled, no product access, or TRIAL_EXPIRED "404": description: Message AUTOMATION_NOT_FOUND "405": description: Method not allowed "429": description: Rate limit exceeded "500": description: Internal server error /workflows/v1/list: get: operationId: listWorkflows tags: - Workflows summary: List workflows description: Returns non-template workflows visible to the API key user. parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 250 default: 50 description: Number of workflows to return. - name: cursor in: query required: false schema: type: string format: uuid description: Workflow UUID from nextCursor in the previous response. responses: "200": description: Workflows returned successfully "400": description: Invalid query parameter "401": description: Invalid or missing API key "403": description: Missing WORKFLOW_API scope "429": description: Rate limit exceeded "500": description: Internal server error /workflows/v1/create: post: operationId: createWorkflow tags: - Workflows summary: Create a workflow description: Creates an inactive unpublished draft owned by the API key user. requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string maxLength: 60 description: type: string maxLength: 500 timezone: type: string description: Valid IANA timezone. initialTriggerKind: type: string enum: - manual - webhook - scheduled - form - integration - meeting_end description: Starter trigger. Do not send this together with nodes and edges. nodes: type: array items: type: object description: Draft nodes. Must be sent together with edges. edges: type: array items: type: object description: Draft edges. Must be sent together with nodes. shareWith: type: object properties: userIds: type: array items: type: string format: uuid maxItems: 100 groupIds: type: array items: type: string format: uuid maxItems: 100 role: type: string enum: - user - editor default: editor limits: type: object description: Execution caps. Send null on a field to clear it. properties: monthlyCostUsd: type: number minimum: 1 maximum: 10000 nullable: true perRunCostUsd: type: number minimum: 1 maximum: 100 nullable: true maxExecutionsPerHour: type: integer minimum: 1 maximum: 5000 nullable: true responses: "200": description: Workflow created successfully "400": description: Invalid body, mixed initialTriggerKind with a graph, or nodes without edges "401": description: Invalid or missing API key "403": description: Missing WORKFLOW_WRITE_API scope, createWorkflows, or shareWorkflows. meeting_end without Meetings returns MEETINGS_FEATURE_FLAG_DISABLED. "404": description: A shareWith target is unknown or cannot be shared "429": description: Rate limit exceeded "500": description: Internal server error /workflows/v1/get: get: operationId: getWorkflow tags: - Workflows summary: Get a workflow description: Returns a workflow the API key user can view, including the draft graph, published graph, version history, and execution limits. parameters: - name: workflowId in: query required: true schema: type: string format: uuid description: UUID of the workflow. responses: "200": description: Workflow returned successfully "400": description: Invalid workflow ID "401": description: Invalid or missing API key "403": description: Missing WORKFLOW_API scope "404": description: Workflow not found, or the key user cannot view it "429": description: Rate limit exceeded "500": description: Internal server error /workflows/v1/update: patch: operationId: updateWorkflow tags: - Workflows summary: Update a workflow description: Updates metadata or the draft graph. Updating the draft does not publish a new version. requestBody: required: true content: application/json: schema: type: object required: - workflowId properties: workflowId: type: string format: uuid name: type: string maxLength: 60 description: type: string maxLength: 500 status: type: string enum: - ACTIVE - INACTIVE timezone: type: string description: Valid IANA timezone. nodes: type: array items: type: object edges: type: array items: type: object patch: type: object description: Incremental graph operations. Cannot be sent with nodes and edges or with metadata. limits: type: object description: Execution caps. Omitted fields stay unchanged. Send null on a field to clear it. responses: "200": description: Workflow updated successfully "400": description: Invalid body, mixed graph and metadata, nodes without edges, no fields, or activate without a published version "401": description: Invalid or missing API key "403": description: Missing WORKFLOW_WRITE_API scope or editor access. A missing workflow, a template, or a workflow in another workspace also returns this status. "429": description: Rate limit exceeded "500": description: Internal server error /workflows/v1/publish: post: operationId: publishWorkflow tags: - Workflows summary: Publish a workflow description: Publishes the current draft as a new production version. requestBody: required: true content: application/json: schema: type: object required: - workflowId - bumpType properties: workflowId: type: string format: uuid bumpType: type: string enum: - major - minor - patch description: type: string maxLength: 255 timezone: type: string description: Valid IANA timezone. Stored only when a valid name is sent. responses: "200": description: Workflow published successfully "400": description: Invalid body, disconnected trigger, webhook auth required, template workflow, or missing draft "401": description: Invalid or missing API key "403": description: Missing WORKFLOW_WRITE_API scope or editor access. A missing workflow, a template, or a workflow in another workspace also returns this status. "429": description: Rate limit exceeded "500": description: Internal server error /workflows/v1/delete: delete: operationId: deleteWorkflow tags: - Workflows summary: Delete a workflow description: Permanently deletes a workflow, including its draft and published versions. parameters: - name: workflowId in: query required: true schema: type: string format: uuid description: UUID of the workflow. responses: "200": description: Workflow permanently deleted "400": description: Invalid workflow ID "401": description: Invalid or missing API key "403": description: Missing WORKFLOW_DELETE_API scope "404": description: Workflow not found, or the key user cannot edit it "429": description: Rate limit exceeded "500": description: Internal server error /workflows/v1/runs: get: operationId: listWorkflowRuns tags: - Workflows summary: List workflow runs description: Returns paginated runs and node executions for a workflow the API key user can edit. parameters: - name: workflowId in: query required: true schema: type: string format: uuid description: UUID of the workflow. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 description: Number of runs to return. - name: cursor in: query required: false schema: type: string format: uuid description: Run UUID from nextCursor in the previous response. - name: runId in: query required: false schema: type: string format: uuid description: Filter to a single run UUID. - name: runMode in: query required: false schema: type: string enum: - test - production - name: status in: query required: false schema: type: string enum: - PENDING - IN_PROGRESS - AWAITING_INPUT - COMPLETED - FAILED - CANCELLED - name: from in: query required: false schema: type: string description: Start of the run creation range. ISO 8601 timestamp or YYYY-MM-DD. Must be sent together with to. - name: to in: query required: false schema: type: string description: End of the run creation range. Must be equal to or later than from. - name: version in: query required: false schema: type: string description: Workflow version used for the run. Version 0 is the draft used for test runs. responses: "200": description: Workflow runs returned successfully "400": description: Invalid query, from without to, to earlier than from, or runMode that disagrees with version "401": description: Invalid or missing API key "403": description: Missing WORKFLOW_API scope or editor access. A missing workflow, a template, or a workflow in another workspace also returns this status. "429": description: Rate limit exceeded "500": description: Internal server error /workflows/{workflowId}/runs: get: operationId: exportWorkflowRunData tags: - Workflow Run Export summary: Export workflow run data description: | Returns flattened workflow run and node execution rows for the selected workflow. The date range filters workflow run creation time. The endpoint requires a workspace API key with the `WORKFLOW_API` scope and owner or editor access. Workspace administrators can access workflows without a workflow share, but a User share does not grant access. security: - bearerAuth: [] parameters: - name: workflowId in: path required: true description: ID of the workflow to export. schema: type: string format: uuid - name: from in: query required: true description: | Start of the export range. Use an ISO 8601 date or timestamp. A date-only value starts at 00:00:00.000 UTC. schema: type: string example: "2026-08-01" - name: to in: query required: true description: | End of the export range. Use an ISO 8601 date or timestamp. A date-only value ends at 23:59:59.999 UTC. schema: type: string example: "2026-08-31" responses: "200": description: Workflow run export content: application/json: schema: $ref: "#/components/schemas/WorkflowRunExportResponse" example: data: - run_id: "7d2a1c4e-2f6a-4b9f-8c31-1a6d8e4f2b90" run_number: 42 run_status: "COMPLETED" run_created_at: "2026-08-12T09:15:00.000Z" run_updated_at: "2026-08-12T09:15:08.000Z" workflow_version: "3" trigger_mode: "WEBHOOK" node_execution_id: "2b8c1d4e-6f7a-4b90-9c12-3d5e7f8a1b20" node_id: "9c1f2d3e-7a4b-4c58-8d19-2e6f0b7a4c31" node_type: "agent" node_status: "COMPLETED" node_created_at: "2026-08-12T09:15:01.000Z" node_updated_at: "2026-08-12T09:15:06.000Z" failure_code: null input: customer_id: "customer-42" input_error: null output: category: "support" output_error: null logs: [] data_redacted: false execution_data_expired_at: null "400": description: Invalid request or export exceeds a configured limit content: application/json: schema: $ref: "#/components/schemas/WorkflowRunExportError" example: message: "Workflow run exports are limited to 10,000 runs. Select a smaller date range." code: "WORKFLOW_RUN_EXPORT_LIMIT_EXCEEDED" details: maxRuns: 10000 "401": description: Missing or invalid API key content: application/json: schema: $ref: "#/components/schemas/WorkflowRunExportError" "403": description: Missing scope or workflow access content: application/json: schema: $ref: "#/components/schemas/WorkflowRunExportError" "405": description: Method not allowed "429": description: Rate limit exceeded content: application/json: schema: $ref: "#/components/schemas/WorkflowRunExportError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/WorkflowRunExportError" /user-management/v1/invite: post: tags: - User Management summary: Invite users to workspace description: | Sends workspace invitations to one or more users by email. Each user can optionally be assigned a specific role. If no role is specified, the default role `member` is used. Users who are already members of the workspace are silently skipped. Users with pending join requests are automatically approved. Invalid email addresses are reported in the response but do not cause the entire request to fail. An invitation email is sent to each successfully invited user. If the workspace does not have SAML enabled, the email includes a magic link for passwordless sign-in. If SAML and Allow External Authentication are enabled, users outside the workspace's verified domains receive a magic link. SAML remains enforced for users from verified domains. parameters: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/InviteUsersRequest" examples: single_user: summary: Invite a single user value: users: - email: "jane.doe@example.com" multiple_users_with_roles: summary: Invite multiple users with roles value: users: - email: "alice@example.com" role: "admin" - email: "bob@example.com" role: "member" - email: "carol@example.com" responses: "200": description: Invitations processed successfully content: application/json: schema: $ref: "#/components/schemas/InviteUsersResponse" examples: all_successful: summary: All invitations sent value: status: "success" message: "Invitations processed" successfulInvites: - "alice@example.com" - "bob@example.com" invalidEmails: [] partial_success: summary: Some emails were invalid value: status: "success" message: "Invitations processed" successfulInvites: - "alice@example.com" invalidEmails: - "not-a-valid-email" "400": description: Invalid request body content: application/json: schema: $ref: "#/components/schemas/InviteUsersError" examples: missing_users: summary: Missing or empty users array value: message: "Invalid request body" errors: - code: "too_small" minimum: 1 type: "array" inclusive: true exact: false message: "Array must contain at least 1 element(s)" path: ["users"] invalid_role: summary: Invalid role value value: message: "Invalid request body" errors: - code: "invalid_enum_value" options: ["member", "editor", "admin"] received: "superadmin" message: "Invalid enum value. Expected 'member' | 'editor' | 'admin', received 'superadmin'" path: ["users", 0, "role"] "401": description: Unauthorized - API key is missing, invalid, or the key creator was not found content: application/json: schema: $ref: "#/components/schemas/InviteUsersError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/InviteUsersError" /user-management/v1/deactivate-user: post: tags: - User Management summary: Deactivate a workspace user description: | Removes a user from the workspace by email. The user immediately loses access, but all their data (conversations, assistants, files, integrations) is preserved and restored if they are re-added later. parameters: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UserEmailRequest" examples: deactivate_user: summary: Deactivate a user value: email: "user@example.com" responses: "200": description: User deactivated successfully content: application/json: schema: $ref: "#/components/schemas/UserManagementResponse" examples: success: summary: User deactivated value: status: "success" message: "User deactivated" "401": description: Unauthorized - API key is missing, invalid, or the key creator was not found content: application/json: schema: $ref: "#/components/schemas/UserManagementError" "404": description: User not found or not an active member content: application/json: schema: $ref: "#/components/schemas/UserManagementError" examples: not_found: summary: User not found value: message: "User not found or not an active member" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/UserManagementError" /user-management/v1/update-user-role: post: tags: - User Management summary: Change a member's system role description: | Changes an active human member's workspace system role by email. Send `member`, `editor`, or `admin`. Custom roles are not part of this endpoint. The call is authorized by the workspace API key's `USER_MANAGEMENT_API` scope and does not run as the person who created the key. parameters: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateUserRoleRequest" examples: update_role: summary: Change a member to editor value: email: "user@example.com" role: "editor" responses: "200": description: Role updated successfully content: application/json: schema: $ref: "#/components/schemas/UpdateUserRoleResponse" examples: success: summary: Role updated value: status: "success" email: "user@example.com" role: "editor" "400": description: Invalid role or request body, or the change would leave the workspace without an active admin content: application/json: schema: $ref: "#/components/schemas/UserManagementError" examples: last_admin: summary: Last remaining admin value: code: "BAD_REQUEST" message: "A workspace must retain at least one active admin." invalid_role: summary: Invalid role value value: message: "Invalid request" errors: - code: "invalid_value" values: - member - editor - admin path: - role message: 'Invalid option: expected one of "member"|"editor"|"admin"' "401": description: API key is missing, invalid, or expired content: application/json: schema: $ref: "#/components/schemas/UserManagementError" "403": description: API key is missing the USER_MANAGEMENT_API scope content: application/json: schema: $ref: "#/components/schemas/UserManagementError" examples: insufficient_scopes: summary: Missing scope value: message: "Insufficient API key permissions." error: "INSUFFICIENT_SCOPES" details: required: - USER_MANAGEMENT_API missing: - USER_MANAGEMENT_API "404": description: User is not an active human member of this workspace content: application/json: schema: $ref: "#/components/schemas/UserManagementError" examples: not_found: summary: User not found value: code: "NOT_FOUND" message: "User is not an active member of this workspace" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/UserManagementError" /audit-logs/{workspace_id}: get: tags: - Audit Logs summary: List audit logs description: | Returns audit log entries for a workspace with cursor-based pagination. Requires an API key with the `AUDIT_LOG_API` scope. operationId: listAuditLogs security: - bearerAuth: [] parameters: - name: workspace_id in: path required: true description: > Workspace UUID. Must match the workspace associated with the API key; requests with a mismatched workspace_id are rejected with 403. schema: type: string format: uuid - name: cursor in: query required: false description: Cursor for pagination (ID of last item from previous page) schema: type: string format: uuid - name: limit in: query required: false description: Maximum number of items to return (default 50, max 50) schema: type: integer minimum: 1 maximum: 50 default: 50 - name: from in: query required: false description: Start of date range filter (ISO 8601) schema: type: string format: date-time - name: to in: query required: false description: End of date range filter (ISO 8601) schema: type: string format: date-time - name: entity_type in: query required: false description: Filter by entity type (e.g. "User", "Workspace") schema: type: string - name: actor_id in: query required: false description: Filter by actor UUID schema: type: string format: uuid responses: "200": description: Paginated list of audit log entries content: application/json: schema: $ref: "#/components/schemas/AuditLogListResponse" examples: example: value: data: - id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" created_at: "2026-02-09T14:30:00Z" actor_id: "u1234567-89ab-cdef-0123-456789abcdef" actor_type: "USER" actor_name: "jane.doe@example.com" action: "user.updated" entity_type: "User" entity_id: "u7654321-89ab-cdef-0123-456789abcdef" ip_address: "203.0.113.42" user_agent: "Mozilla/5.0" changes: before: role: "MEMBER" after: role: "ADMIN" snapshot: null next_cursor: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" "400": description: Invalid request parameters "401": description: Missing or invalid API key "403": description: Insufficient API key scopes or workspace_id does not match the API key's workspace "429": description: Rate limit exceeded "500": description: Internal server error components: parameters: SkillId: name: skillId in: path required: true description: UUID of the Skill. schema: type: string format: uuid PromptId: name: promptId in: path required: true description: UUID of the prompt. schema: type: string format: uuid PromptFolderId: name: folderId in: path required: true description: UUID of the prompt folder. schema: type: string format: uuid schemas: Skill: type: object required: - id - name - slug - description - instructions - integrationIds - createdAt - updatedAt properties: id: type: string format: uuid description: Unique identifier for the Skill. name: type: string maxLength: 64 description: Skill name. slug: type: string maxLength: 100 pattern: "^[a-z0-9-]+$" description: Stable Skill slug. description: type: string maxLength: 1024 description: Description used to explain when the Skill should apply. instructions: type: string maxLength: 50000 description: Skill instructions. integrationIds: type: array items: type: string format: uuid description: Integration IDs attached to the Skill. Each integration must be enabled in your workspace. createdAt: type: string format: date-time description: ISO 8601 timestamp for Skill creation. updatedAt: type: string format: date-time description: ISO 8601 timestamp for the latest Skill update. SkillResponse: type: object required: - skill properties: skill: $ref: "#/components/schemas/Skill" GetSkillResponse: type: object required: - skill - files properties: skill: $ref: "#/components/schemas/Skill" files: type: array description: Stored Skill files, ordered by path. Includes text and binary files. Does not include file contents. items: $ref: "#/components/schemas/SkillFile" SkillFile: type: object required: - path - sizeBytes - extension - hasScript - sha256 properties: path: type: string description: Relative path inside the Skill. sizeBytes: type: integer description: File size in bytes. extension: type: string description: Lowercase file extension, including the leading dot. hasScript: type: boolean description: Whether the file is a script file (`.py`, `.sh`, `.js`, or `.ts`). sha256: type: string description: Lowercase SHA-256 hash of the original file bytes. SkillFileContent: allOf: - $ref: "#/components/schemas/SkillFile" - type: object required: - content properties: content: type: string description: UTF-8 file contents. ListSkillsResponse: type: object required: - skills properties: skills: type: array items: $ref: "#/components/schemas/Skill" nextCursor: type: string format: uuid description: Cursor for the next page, if more results are available. CreateSkillRequest: type: object required: - name - instructions additionalProperties: false properties: name: type: string maxLength: 64 minLength: 1 description: Skill name. slug: type: string maxLength: 100 pattern: "^[a-z0-9-]+$" description: Stable Skill slug. description: type: string maxLength: 1024 description: Description used to explain when the Skill should apply. instructions: type: string maxLength: 50000 minLength: 1 description: Skill instructions. integrationIds: type: array items: type: string format: uuid description: Integration IDs to attach to the Skill. UpdateSkillRequest: type: object minProperties: 1 additionalProperties: false properties: name: type: string maxLength: 64 minLength: 1 description: Skill name. slug: type: string maxLength: 100 pattern: "^[a-z0-9-]+$" description: Stable Skill slug. description: type: string maxLength: 1024 description: Description used to explain when the Skill should apply. instructions: type: string maxLength: 50000 minLength: 1 description: Skill instructions. integrationIds: type: array items: type: string format: uuid description: Integration IDs to attach to the Skill. Replaces the current integration list. ImportSkillRequest: type: object required: - file - fileType properties: file: type: string format: binary description: SKILL.md, .zip, or .skill file content. fileType: type: string enum: [md, zip] description: File parser to use. mode: type: string enum: [create, upsert] default: create description: Whether to create a Skill or update an editable Skill with the same slug. integrationIds: type: string description: JSON-encoded array of integration UUIDs. ImportedSkillFile: type: object required: - path - sizeBytes - extension - hasScript properties: path: type: string description: File path inside the imported Skill. sizeBytes: type: integer description: File size in bytes. extension: type: string description: File extension. hasScript: type: boolean description: Whether the file is a script file. ImportSkillResponse: type: object required: - skill - files properties: skill: $ref: "#/components/schemas/Skill" files: type: array items: $ref: "#/components/schemas/ImportedSkillFile" Prompt: type: object required: - id - title - prompt - sharedWithWorkspace properties: id: type: string format: uuid description: Unique identifier for the prompt. title: type: string minLength: 2 maxLength: 100 description: Prompt title. prompt: type: string minLength: 2 maxLength: 120000 description: Prompt content. createdBy: type: string format: uuid nullable: true description: User ID of the prompt creator. promptFolderId: type: string format: uuid nullable: true description: Folder ID the prompt is assigned to. sharedWithWorkspace: type: boolean description: Whether the prompt is shared with the workspace. createdAt: type: string format: date-time nullable: true description: ISO 8601 timestamp for prompt creation. updatedAt: type: string format: date-time nullable: true description: ISO 8601 timestamp for the latest prompt update. PromptResponse: type: object required: - prompt properties: prompt: $ref: "#/components/schemas/Prompt" ListPromptsResponse: type: object required: - prompts properties: prompts: type: array items: $ref: "#/components/schemas/Prompt" nextCursor: type: string format: uuid description: Cursor for the next page, if more results are available. CreatePromptRequest: type: object required: - title - prompt additionalProperties: false properties: title: type: string minLength: 2 maxLength: 100 description: Prompt title. prompt: type: string minLength: 2 maxLength: 120000 description: Prompt content. promptFolderId: type: string format: uuid description: Folder UUID to assign. Cannot be set when sharedWithWorkspace is true. sharedWithWorkspace: type: boolean description: Share the prompt with the workspace. Cannot be true when promptFolderId is set. UpdatePromptRequest: type: object minProperties: 1 additionalProperties: false properties: title: type: string minLength: 2 maxLength: 100 description: Prompt title. prompt: type: string minLength: 2 maxLength: 120000 description: Prompt content. promptFolderId: type: string format: uuid nullable: true description: Folder UUID to assign, or null to remove the folder. sharedWithWorkspace: type: boolean description: Share the prompt with the workspace. PromptFolder: type: object required: - id - name - createdBy - sharedWithWorkspace - createdAt - updatedAt properties: id: type: string format: uuid description: Unique identifier for the prompt folder. name: type: string minLength: 2 maxLength: 50 description: Folder name. createdBy: type: string format: uuid description: User ID of the folder creator. sharedWithWorkspace: type: boolean description: Whether the folder is shared with the workspace. sharedWithGroupId: type: string format: uuid nullable: true description: Group ID the folder is shared with. createdAt: type: string format: date-time description: ISO 8601 timestamp for folder creation. updatedAt: type: string format: date-time description: ISO 8601 timestamp for the latest folder update. PromptFolderResponse: type: object required: - folder properties: folder: $ref: "#/components/schemas/PromptFolder" ListPromptFoldersResponse: type: object required: - folders properties: folders: type: array items: $ref: "#/components/schemas/PromptFolder" nextCursor: type: string format: uuid description: Cursor for the next page, if more results are available. CreatePromptFolderRequest: type: object required: - name additionalProperties: false properties: name: type: string minLength: 2 maxLength: 50 description: Folder name. sharedWithWorkspace: type: boolean description: Share the folder with the workspace. Cannot be true when sharedWithGroupId is set. sharedWithGroupId: type: string format: uuid description: Group UUID to share with. Cannot be set when sharedWithWorkspace is true. UpdatePromptFolderRequest: type: object minProperties: 1 additionalProperties: false properties: name: type: string minLength: 2 maxLength: 50 description: Folder name. sharedWithWorkspace: type: boolean description: Share the folder with the workspace. sharedWithGroupId: type: string format: uuid nullable: true description: Group UUID to share with, or null to disconnect the group. # Agent API schemas AgentAccessChange: type: object additionalProperties: false required: [id, role] properties: id: type: string format: uuid description: User or group UUID. role: type: string nullable: true enum: [user, editor, null] description: Use or edit access. Set null to revoke this direct grant. AgentAccessUpdate: type: object additionalProperties: false description: Sharing changes under the Agent API scope and the key owner's workspace sharing permissions. Updating access requires an explicit editor or owner key grant. New user and group grants send in-app notifications after commit; repeated grants, role changes, and revocations do not. No email is sent. Omitted targets and empty arrays leave access unchanged. Owner and API-key grants cannot be changed. Admin-managed sharing cannot be updated. properties: users: type: array maxItems: 100 description: User grants to add, change, or revoke. New grants require active users in the same workspace. Revocation also supports inactive or former users. IDs must be unique. items: $ref: "#/components/schemas/AgentAccessChange" groups: type: array maxItems: 100 description: Group grants to add, change, or revoke. Groups must belong to the workspace and be manageable by the key owner unless workspace permissions allow sharing with any group. IDs must be unique. items: $ref: "#/components/schemas/AgentAccessChange" workspace: type: string nullable: true enum: [user, editor, null] description: Workspace-wide role, or null to revoke workspace access. AgentAccessGrant: type: object required: [id, role] properties: id: type: string format: uuid role: type: string enum: [user, editor] AgentAccessConfiguration: type: object description: Current direct sharing settings, returned only when the API key has an explicit editor or owner grant on the agent. Owner and API-key grants are excluded. Sharing is independent of the agent's published version. required: [users, groups, workspace, sharingManagedByAdmin] properties: users: type: array items: $ref: "#/components/schemas/AgentAccessGrant" groups: type: array items: $ref: "#/components/schemas/AgentAccessGrant" workspace: type: string nullable: true enum: [user, editor, null] sharingManagedByAdmin: type: boolean readOnly: true description: Whether sharing is managed by an administrator and cannot be changed through this API. AssistantActionRequest: type: object required: - actionId properties: actionId: type: string format: uuid description: UUID of the action. Create requires an enabled workspace integration. Update also accepts ids already on the draft as described on PATCH /agent/v1/update. requiresConfirmation: type: boolean default: true description: Whether to require user confirmation before executing AssistantInputFieldRequest: type: object required: - slug - type - label - order properties: slug: type: string minLength: 1 maxLength: 64 description: Unique identifier for the field type: type: string enum: [TEXT, MULTI_LINE_TEXT, NUMBER, CHECKBOX, FILE, SELECT, MULTI_SELECT, DATE, EMAIL] description: Field type label: type: string minLength: 1 maxLength: 255 description: Display label for the field description: type: string maxLength: 512 description: Help text for the field required: type: boolean default: false description: Whether the field is required order: type: integer minimum: 0 description: Display order options: type: array default: [] items: type: string minLength: 1 maxLength: 255 description: Options for SELECT and MULTI_SELECT fields fileTypes: type: string nullable: true maxLength: 255 description: Allowed file types for FILE fields emailDomain: type: string nullable: true description: Allowed email domain for EMAIL fields AssistantWriteRequest: type: object properties: access: $ref: "#/components/schemas/AgentAccessUpdate" name: type: string minLength: 1 maxLength: 80 description: Name of the agent or assistant description: type: string maxLength: 800 description: Description of what the agent or assistant does. Send an empty string to clear it during an update. instruction: type: string maxLength: 50000 description: System prompt or instructions. Send an empty string to clear it during an update. inputType: type: string enum: [PROMPT, STRUCTURED, INTEGRATION, SCHEDULED, WEBHOOK] description: Input type emoji: type: string nullable: true maxLength: 16 description: Emoji icon model: type: string description: id from GET /agent/v1/models. Unique deployment names and Anthropic aliases stay valid. When several accessible rows share a name, send the UUID id. creativity: type: number minimum: 0 maximum: 1 description: Temperature for response generation conversationStarters: type: array maxItems: 20 items: type: string minLength: 1 maxLength: 255 description: Suggested prompts actions: type: array items: $ref: "#/components/schemas/AssistantActionRequest" description: Actions that the agent or assistant can use. On update, the array replaces the draft list. inputFields: type: array items: $ref: "#/components/schemas/AssistantInputFieldRequest" description: Form fields for STRUCTURED input webSearch: type: boolean description: Enable web search imageGeneration: type: boolean description: Enable image generation dataAnalyst: type: boolean deprecated: true description: Deprecated. Accepted for compatibility and ignored. extendedThinking: type: boolean description: Enable extended thinking attachments: type: array maxItems: 50 items: type: string format: uuid description: Attachment UUIDs knowledgeFolderIds: type: array items: type: string format: uuid description: Folder UUIDs AssistantCreateRequest: allOf: - $ref: "#/components/schemas/AssistantWriteRequest" - type: object required: - name properties: inputType: default: PROMPT creativity: default: 0.3 conversationStarters: default: [] actions: default: [] inputFields: default: [] webSearch: default: false imageGeneration: default: false dataAnalyst: default: false extendedThinking: default: false attachments: default: [] knowledgeFolderIds: default: [] AssistantDetails: type: object required: - id - name - description - instruction - emojiIcon - model - temperature - conversationStarters - inputType - webSearchEnabled - imageGenerationEnabled - canvasEnabled - extendedThinking - actions - inputFields - attachments - knowledgeFolderIds - createdAt - updatedAt properties: access: $ref: "#/components/schemas/AgentAccessConfiguration" id: type: string format: uuid description: Unique identifier for the agent name: type: string description: Name of the agent description: type: string nullable: true description: Description of what the agent does instruction: type: string nullable: true description: System prompt/instructions for the agent emojiIcon: type: string nullable: true description: Emoji icon for the agent model: type: string nullable: true description: Model ID to use (see Models for Agent API) temperature: type: number minimum: 0 maximum: 1 description: Temperature/creativity setting for response generation conversationStarters: type: array items: type: string description: Array of suggested prompts to help users get started inputType: type: string enum: [PROMPT, STRUCTURED, INTEGRATION, SCHEDULED, WEBHOOK] description: Input type for the agent webSearchEnabled: type: boolean description: Whether web search capability is enabled imageGenerationEnabled: type: boolean description: Whether image generation capability is enabled canvasEnabled: type: boolean description: Whether canvas capability is enabled extendedThinking: type: boolean description: Whether extended thinking is enabled. Only supported on models that expose this capability; enabling it on an unsupported model returns a 400 error. actions: type: array items: type: object required: - actionId - requiresConfirmation properties: actionId: type: string format: uuid description: UUID of a live action. Missing and soft-deleted ids are omitted. Live unavailable actions remain. requiresConfirmation: type: boolean description: Whether user confirmation is required before executing description: Live actions on the returned version. Missing and soft-deleted ids are omitted. Live unavailable actions remain. inputFields: type: array items: type: object required: - type - label - description - required - order properties: type: type: string enum: [TEXT, MULTI_LINE_TEXT, NUMBER, CHECKBOX, FILE, SELECT, MULTI_SELECT, DATE, EMAIL] description: Field type label: type: string description: Display label for the field description: type: string nullable: true description: Help text for the field required: type: boolean description: Whether the field is required order: type: integer minimum: 0 description: Display order (0-indexed) description: Array of form field definitions (for STRUCTURED input type) attachments: type: array items: type: string format: uuid description: Array of attachment UUIDs associated with the agent knowledgeFolderIds: type: array items: type: string format: uuid description: Array of Folder UUIDs associated with the agent createdAt: type: string format: date-time description: Timestamp when the agent was created updatedAt: type: string format: date-time description: Timestamp when the agent was last updated # OpenAI schemas ChatCompletionRequestMessageContentPart: oneOf: - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartImage" x-oaiExpandable: true ChatCompletionRequestMessageContentPartImage: type: object title: Image content part properties: type: type: string enum: ["image_url"] description: The type of the content part. image_url: type: object properties: url: type: string description: Either a URL of the image or the base64 encoded image data. format: uri detail: type: string description: Specifies the detail level of the image. Learn more in the [Vision guide](https://platform.openai.com/docs/guides/vision/low-or-high-fidelity-image-understanding). enum: ["auto", "low", "high"] default: "auto" required: - url required: - type - image_url ChatCompletionRequestMessageContentPartText: type: object title: Text content part properties: type: type: string enum: ["text"] description: The type of the content part. text: type: string description: The text content. required: - type - text ChatCompletionRequestMessage: oneOf: - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" x-oaiExpandable: true ChatCompletionRequestSystemMessage: type: object title: System message properties: content: description: The contents of the system message. type: string role: type: string enum: ["system"] description: The role of the messages author, in this case `system`. name: type: string description: An optional name for the participant. Provides the model information to differentiate between participants of the same role. required: - content - role ChatCompletionRequestUserMessage: type: object title: User message properties: content: description: | The contents of the user message. oneOf: - type: string description: The text contents of the message. title: Text content - type: array description: An array of content parts with a defined type, each can be of type `text` or `image_url` when passing in images. You can pass multiple images by adding multiple `image_url` content parts. Image input is only supported when using the `gpt-4-visual-preview` model. title: Array of content parts items: $ref: "#/components/schemas/ChatCompletionRequestMessageContentPart" minItems: 1 x-oaiExpandable: true role: type: string enum: ["user"] description: The role of the messages author, in this case `user`. name: type: string description: An optional name for the participant. Provides the model information to differentiate between participants of the same role. required: - content - role ChatCompletionRequestAssistantMessage: type: object title: Assistant message properties: content: nullable: true type: string description: | The contents of the assistant message. Required unless `tool_calls` or `function_call` is specified. role: type: string enum: ["assistant"] description: The role of the messages author, in this case `assistant`. name: type: string description: An optional name for the participant. Provides the model information to differentiate between participants of the same role. tool_calls: $ref: "#/components/schemas/ChatCompletionMessageToolCalls" function_call: type: object deprecated: true description: "Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model." nullable: true properties: arguments: type: string description: The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. name: type: string description: The name of the function to call. required: - arguments - name required: - role ChatCompletionRequestToolMessage: type: object title: Tool message properties: role: type: string enum: ["tool"] description: The role of the messages author, in this case `tool`. content: type: string description: The contents of the tool message. tool_call_id: type: string description: Tool call that this message is responding to. required: - role - content - tool_call_id ChatCompletionRequestFunctionMessage: type: object title: Function message deprecated: true properties: role: type: string enum: ["function"] description: The role of the messages author, in this case `function`. content: nullable: true type: string description: The contents of the function message. name: type: string description: The name of the function to call. required: - role - content - name FunctionParameters: type: object description: "The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/reference) for documentation about the format. \n\nOmitting `parameters` defines a function with an empty parameter list." additionalProperties: true ChatCompletionFunctions: type: object deprecated: true properties: description: type: string description: A description of what the function does, used by the model to choose when and how to call the function. name: type: string description: The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. parameters: $ref: "#/components/schemas/FunctionParameters" required: - name ChatCompletionFunctionCallOption: type: object description: > Specifying a particular function via `{"name": "my_function"}` forces the model to call that function. properties: name: type: string description: The name of the function to call. required: - name ChatCompletionTool: type: object properties: type: type: string enum: ["function"] description: The type of the tool. Currently, only `function` is supported. function: $ref: "#/components/schemas/FunctionObject" required: - type - function FunctionObject: type: object properties: description: type: string description: A description of what the function does, used by the model to choose when and how to call the function. name: type: string description: The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. parameters: $ref: "#/components/schemas/FunctionParameters" required: - name ChatCompletionToolChoiceOption: description: | Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present. oneOf: - type: string description: > `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. enum: [none, auto, required] - $ref: "#/components/schemas/ChatCompletionNamedToolChoice" x-oaiExpandable: true ChatCompletionNamedToolChoice: type: object description: Specifies a tool the model should use. Use to force the model to call a specific function. properties: type: type: string enum: ["function"] description: The type of the tool. Currently, only `function` is supported. function: type: object properties: name: type: string description: The name of the function to call. required: - name required: - type - function ChatCompletionMessageToolCalls: type: array description: The tool calls generated by the model, such as function calls. items: $ref: "#/components/schemas/ChatCompletionMessageToolCall" ChatCompletionMessageToolCall: type: object properties: # TODO: index included when streaming id: type: string description: The ID of the tool call. type: type: string enum: ["function"] description: The type of the tool. Currently, only `function` is supported. function: type: object description: The function that the model called. properties: name: type: string description: The name of the function to call. arguments: type: string description: The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. required: - name - arguments required: - id - type - function ChatCompletionResponseMessage: type: object description: A chat completion message generated by the model. properties: content: type: string description: The contents of the message. nullable: true tool_calls: $ref: "#/components/schemas/ChatCompletionMessageToolCalls" role: type: string enum: ["assistant"] description: The role of the author of this message. function_call: type: object deprecated: true description: "Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model." properties: arguments: type: string description: The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. name: type: string description: The name of the function to call. required: - name - arguments required: - role - content CreateCompletionRequest: type: object properties: model: description: &model_description | ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see OpenAI's [Model overview](https://platform.openai.com/docs/models/overview) for descriptions of them. anyOf: - type: string - type: string enum: ["gpt-3.5-turbo-instruct", "davinci-002", "babbage-002"] x-oaiTypeLabel: string prompt: description: &completions_prompt_description | The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays. Note that <|endoftext|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document. default: "<|endoftext|>" nullable: true oneOf: - type: string default: "" example: "This is a test." - type: array items: type: string default: "" example: "This is a test." - type: array minItems: 1 items: type: integer example: "[1212, 318, 257, 1332, 13]" - type: array minItems: 1 items: type: array minItems: 1 items: type: integer example: "[[1212, 318, 257, 1332, 13]]" best_of: type: integer default: 1 minimum: 0 maximum: 20 nullable: true description: &completions_best_of_description | Generates `best_of` completions server-side and returns the "best" (the one with the highest log probability per token). Results cannot be streamed. When used with `n`, `best_of` controls the number of candidate completions and `n` specifies how many to return – `best_of` must be greater than `n`. **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`. echo: type: boolean default: false nullable: true description: &completions_echo_description > Echo back the prompt in addition to the completion frequency_penalty: type: number default: 0 minimum: -2 maximum: 2 nullable: true description: &completions_frequency_penalty_description | Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation/parameter-details) logit_bias: &completions_logit_bias type: object x-oaiTypeLabel: map default: null nullable: true additionalProperties: type: integer description: &completions_logit_bias_description | Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this [tokenizer tool](/tokenizer?view=bpe) to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. As an example, you can pass `{"50256": -100}` to prevent the <|endoftext|> token from being generated. logprobs: &completions_logprobs_configuration type: integer minimum: 0 maximum: 5 default: null nullable: true description: &completions_logprobs_description | Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response. The maximum value for `logprobs` is 5. max_tokens: type: integer minimum: 0 default: 16 example: 16 nullable: true description: &completions_max_tokens_description | The maximum number of [tokens](/tokenizer) that can be generated in the completion. The token count of your prompt plus `max_tokens` cannot exceed the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. presence_penalty: type: number default: 0 minimum: -2 maximum: 2 nullable: true description: &completions_presence_penalty_description | Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation/parameter-details) seed: &completions_seed_param type: integer minimum: -9223372036854775808 maximum: 9223372036854775807 nullable: true description: | If specified, OpenAI's system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend. stop: description: &completions_stop_description > Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence. default: null nullable: true oneOf: - type: string default: <|endoftext|> example: "\n" nullable: true - type: array minItems: 1 maxItems: 4 items: type: string example: '["\n"]' stream: description: > Whether to stream back partial progress. If set, tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions). type: boolean nullable: true default: false suffix: description: | The suffix that comes after a completion of inserted text. This parameter is only supported for `gpt-3.5-turbo-instruct`. default: null nullable: true type: string example: "test." temperature: type: number minimum: 0 maximum: 2 default: 1 example: 1 nullable: true description: &completions_temperature_description | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. top_p: type: number minimum: 0 maximum: 1 default: 1 example: 1 nullable: true description: &completions_top_p_description | An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both. user: &end_user_param_configuration type: string example: user-1234 description: | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids). required: - model - prompt CreateResponseResponse: type: object description: A response returned by the OpenAI-compatible Responses endpoint. required: - id - object - created_at - status - model - output properties: id: type: string description: Unique identifier for the response. example: "resp_09e99d1f7f163d10016a678387353481" object: type: string enum: ["response"] description: The object type, which is always `response`. created_at: type: integer description: Unix timestamp in seconds when the response was created. example: 1785168775 completed_at: type: integer nullable: true description: Unix timestamp in seconds when the response completed. example: 1785168778 background: type: boolean enum: [false] description: Langdock does not support background responses. status: type: string enum: ["completed", "failed", "in_progress", "cancelled", "queued", "incomplete"] description: Current response status. example: "completed" model: type: string description: Model used to generate the response. example: "gpt-5-mini-2025-08-07" output: type: array description: Output items generated by the model. items: oneOf: - $ref: "#/components/schemas/ResponseReasoningItem" - $ref: "#/components/schemas/ResponseOutputMessage" - $ref: "#/components/schemas/ResponseFunctionToolCall" output_text: type: string description: Aggregated text from all `output_text` items. error: type: object nullable: true description: Error information when the response failed. properties: code: type: string nullable: true message: type: string incomplete_details: type: object nullable: true description: Details explaining why the response is incomplete. properties: reason: type: string enum: ["max_output_tokens", "content_filter"] instructions: type: string nullable: true description: Instructions used for the response. max_output_tokens: type: integer nullable: true description: Maximum number of output tokens configured for the response. parallel_tool_calls: type: boolean description: Whether the model can return multiple function calls. reasoning: type: object nullable: true description: Reasoning configuration used for the response. additionalProperties: true store: type: boolean enum: [false] description: Langdock Responses are never persisted. temperature: type: number nullable: true description: Sampling temperature used for the response. text: type: object nullable: true description: Text output configuration used for the response. additionalProperties: true service_tier: type: string nullable: true description: Service tier used to process the response. tool_choice: description: Tool choice used for the response. oneOf: - type: string - type: object additionalProperties: true tools: type: array description: Function tools available to the model. items: type: object additionalProperties: true top_p: type: number nullable: true description: Nucleus sampling value used for the response. truncation: type: string enum: ["auto", "disabled"] description: Truncation strategy used for the response. usage: $ref: "#/components/schemas/ResponseUsage" metadata: type: object nullable: true description: Metadata attached to the request. additionalProperties: type: string additionalProperties: true ResponseReasoningItem: type: object description: Reasoning information generated by a reasoning model. required: - id - type - summary properties: id: type: string example: "rs_123" type: type: string enum: ["reasoning"] summary: type: array items: type: object additionalProperties: true content: type: array items: type: object additionalProperties: true encrypted_content: type: string nullable: true description: Encrypted reasoning content when requested. status: type: string nullable: true enum: ["in_progress", "completed", "incomplete"] additionalProperties: true ResponseOutputMessage: type: object description: A message generated by the model. required: - id - type - status - role - content properties: id: type: string example: "msg_09e99d1f7f163d10016a67838935a881" type: type: string enum: ["message"] status: type: string enum: ["in_progress", "completed", "incomplete"] role: type: string enum: ["assistant"] content: type: array items: oneOf: - $ref: "#/components/schemas/ResponseOutputText" - $ref: "#/components/schemas/ResponseOutputRefusal" additionalProperties: true ResponseOutputText: type: object description: Text generated by the model. required: - type - text - annotations properties: type: type: string enum: ["output_text"] text: type: string example: "Whiskers sketch moonlight on the sill,\npaws treading silence, soft and still." annotations: type: array items: type: object additionalProperties: true logprobs: type: array items: type: object additionalProperties: true additionalProperties: true ResponseOutputRefusal: type: object description: A refusal returned by the model. required: - type - refusal properties: type: type: string enum: ["refusal"] refusal: type: string additionalProperties: true ResponseFunctionToolCall: type: object description: A function call requested by the model. required: - id - type - call_id - name - arguments properties: id: type: string example: "fc_123" type: type: string enum: ["function_call"] status: type: string enum: ["in_progress", "completed", "incomplete"] call_id: type: string example: "call_123" name: type: string example: "lookup_weather" arguments: type: string description: JSON-encoded arguments for the function. example: '{"city":"Berlin"}' additionalProperties: true ResponseUsage: type: object description: Token usage for the response. required: - input_tokens - output_tokens - total_tokens properties: input_tokens: type: integer example: 13 input_tokens_details: type: object properties: cached_tokens: type: integer example: 0 additionalProperties: true output_tokens: type: integer example: 154 output_tokens_details: type: object properties: reasoning_tokens: type: integer example: 64 additionalProperties: true total_tokens: type: integer example: 167 additionalProperties: true CreateChatCompletionRequest: type: object properties: messages: description: A list of messages comprising the conversation so far. [Example Python code](https://cookbook.openai.com/examples/how_to_format_inputs_to_chatgpt_models). type: array minItems: 1 items: $ref: "#/components/schemas/ChatCompletionRequestMessage" model: description: ID of the model to use. See the [model endpoint compatibility](https://platform.openai.com/docs/models/model-endpoint-compatibility) table for details on which models work with the Chat API. example: "gpt-4-turbo" anyOf: - type: string - type: string enum: ["gpt-4o", "gpt-4o-mini", "gpt-4", "gpt-3.5-turbo"] x-oaiTypeLabel: string frequency_penalty: type: number default: 0 minimum: -2 maximum: 2 nullable: true description: *completions_frequency_penalty_description logit_bias: type: object x-oaiTypeLabel: map default: null nullable: true additionalProperties: type: integer description: | Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. logprobs: description: Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the `content` of `message`. type: boolean default: false nullable: true top_logprobs: description: An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. `logprobs` must be set to `true` if this parameter is used. type: integer minimum: 0 maximum: 20 nullable: true max_tokens: description: | The maximum number of tokens that can be generated in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. type: integer nullable: true presence_penalty: type: number default: 0 minimum: -2 maximum: 2 nullable: true description: *completions_presence_penalty_description response_format: type: object description: | An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than `gpt-3.5-turbo-1106`. Setting to `{ "type": "json_object" }` enables JSON mode, which guarantees the message the model generates is valid JSON. **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. properties: type: type: string enum: ["text", "json_object"] example: "json_object" default: "text" description: Must be one of `text` or `json_object`. seed: type: integer minimum: -9223372036854775808 maximum: 9223372036854775807 nullable: true description: | This feature is in Beta. If specified, OpenAI's system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend. x-oaiMeta: beta: true stop: description: | Up to 4 sequences where the API will stop generating further tokens. default: null oneOf: - type: string nullable: true - type: array minItems: 1 maxItems: 4 items: type: string stream: description: > If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions). type: boolean nullable: true default: false temperature: type: number minimum: 0 maximum: 2 default: 1 example: 1 nullable: true description: *completions_temperature_description top_p: type: number minimum: 0 maximum: 1 default: 1 example: 1 nullable: true description: *completions_top_p_description tools: type: array description: > A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported. items: $ref: "#/components/schemas/ChatCompletionTool" tool_choice: $ref: "#/components/schemas/ChatCompletionToolChoiceOption" reasoning_effort: type: string nullable: true description: | Constrains how much effort the model spends on reasoning before responding. Lower values produce faster, cheaper responses; higher values produce more thorough reasoning. Supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Not all values are supported by all models. enum: ["none", "minimal", "low", "medium", "high", "xhigh"] user: *end_user_param_configuration function_call: deprecated: true description: | Deprecated in favor of `tool_choice`. Controls which (if any) function is called by the model. `none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function. Specifying a particular function via `{"name": "my_function"}` forces the model to call that function. `none` is the default when no functions are present. `auto` is the default if functions are present. oneOf: - type: string description: > `none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function. enum: [none, auto] - $ref: "#/components/schemas/ChatCompletionFunctionCallOption" x-oaiExpandable: true functions: deprecated: true description: | Deprecated in favor of `tools`. A list of functions the model may generate JSON inputs for. type: array minItems: 1 maxItems: 128 items: $ref: "#/components/schemas/ChatCompletionFunctions" required: - model - messages CreateChatCompletionResponse: type: object description: Represents a chat completion response returned by model, based on the provided input. properties: id: type: string description: A unique identifier for the chat completion. choices: type: array description: A list of chat completion choices. Can be more than one if `n` is greater than 1. items: type: object required: - finish_reason - index - message - logprobs properties: finish_reason: type: string description: &chat_completion_finish_reason_description | The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `content_filter` if content was omitted due to a flag from OpenAI's content filters, `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function. enum: [ "stop", "length", "tool_calls", "content_filter", "function_call", ] index: type: integer description: The index of the choice in the list of choices. message: $ref: "#/components/schemas/ChatCompletionResponseMessage" logprobs: &chat_completion_response_logprobs description: Log probability information for the choice. type: object nullable: true properties: content: description: A list of message content tokens with log probability information. type: array items: $ref: "#/components/schemas/ChatCompletionTokenLogprob" nullable: true required: - content created: type: integer description: The Unix timestamp (in seconds) of when the chat completion was created. model: type: string description: The model used for the chat completion. system_fingerprint: type: string description: | This fingerprint represents the backend configuration that the model runs with. Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism. object: type: string description: The object type, which is always `chat.completion`. enum: [chat.completion] usage: $ref: "#/components/schemas/CompletionUsage" required: - choices - created - id - model - object x-oaiMeta: name: The chat completion object group: chat example: &chat_completion_example | { "id": "chatcmpl-123", "object": "chat.completion", "created": 1677652288, "model": "gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "\n\nHello there, how may I assist you today?", }, "logprobs": null, "finish_reason": "stop" }], "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 } ChatCompletionTokenLogprob: type: object properties: token: &chat_completion_response_logprobs_token description: The token. type: string logprob: &chat_completion_response_logprobs_token_logprob description: The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely. type: number bytes: &chat_completion_response_logprobs_bytes description: A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token. type: array items: type: integer nullable: true top_logprobs: description: List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned. type: array items: type: object properties: token: *chat_completion_response_logprobs_token logprob: *chat_completion_response_logprobs_token_logprob bytes: *chat_completion_response_logprobs_bytes required: - token - logprob - bytes required: - token - logprob - bytes - top_logprobs CompletionUsage: type: object description: Usage statistics for the completion request. properties: completion_tokens: type: integer description: Number of tokens in the generated completion. prompt_tokens: type: integer description: Number of tokens in the prompt. prompt_tokens_details: type: object description: Breakdown of tokens used in the prompt. properties: cached_tokens: type: integer description: Number of prompt tokens served from the provider's prompt cache. example: 0 additionalProperties: true total_tokens: type: integer description: Total number of tokens used in the request (prompt + completion). required: - prompt_tokens - completion_tokens - total_tokens #============== Anthropic schemas ============== APIError: properties: type: default: api_error enum: - api_error title: Type type: string message: default: Internal server error title: Message type: string required: - type - message title: APIError type: object AuthenticationError: properties: type: default: authentication_error enum: - authentication_error title: Type type: string message: default: Authentication error title: Message type: string required: - type - message title: AuthenticationError type: object Base64ImageSource: additionalProperties: false properties: type: enum: - base64 title: Type type: string media_type: enum: - image/jpeg - image/png - image/gif - image/webp title: Media Type type: string data: format: byte title: Data type: string required: - type - media_type - data title: Base64ImageSource type: object CacheControlEphemeral: additionalProperties: false description: |- Marks this block as a prompt caching breakpoint. The prompt prefix up to and including this block is cached and reused across requests. If the requested model resolves to a provider route without prompt caching support, the request returns `400 Bad Request`. See the [Anthropic prompt caching guide](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details. properties: type: enum: - ephemeral title: Type type: string required: - type title: CacheControlEphemeral type: object CreateMessageParams: additionalProperties: false example: max_tokens: 1024 messages: - content: Write a haiku about cats. role: user model: claude-sonnet-4-20250514 properties: model: $ref: "#/components/schemas/Model" messages: description: |- Input messages. Anthropic's models are trained to operate on alternating `user` and `agent` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. The first message must always use the `user` role. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. Example with a single `user` message: ```json [{"role": "user", "content": "Hello, Claude"}] ``` Example with multiple conversational turns: ```json [ {"role": "user", "content": "Hello there."}, {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, {"role": "user", "content": "Can you explain LLMs in plain English?"}, ] ``` Example with a partially-filled response from Claude: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("}, ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: ```json {"role": "user", "content": "Hello, Claude"} ``` ```json {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} ``` Starting with Claude 3 models, you can also send image content blocks: ```json {"role": "user", "content": [ { "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "/9j/4AAQSkZJRg...", } }, {"type": "text", "text": "What is in this image?"} ]} ``` We currently support the `base64` source type for images, and the `image/jpeg`, `image/png`, `image/gif`, and `image/webp` media types. See [examples](https://platform.claude.com/docs/en/api/messages-examples#vision) for more input examples. Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/docs/system-prompts), you can use the top-level `system` parameter â€" there is no `"system"` role for input messages in the Messages API. items: $ref: "#/components/schemas/InputMessage" title: Messages type: array max_tokens: description: |- The maximum number of tokens to generate before stopping. Note that Anthropic's models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/docs/models-overview) for details. example: - 1024 minimum: 1 title: Max Tokens type: integer stop_sequences: description: |- Custom text sequences that will cause the model to stop generating. Anthropic's models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. items: type: string title: Stop Sequences type: array stream: description: |- Whether to incrementally stream the response using server-sent events. See [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming) for details. title: Stream type: boolean system: anyOf: - type: string x-stainless-skip: - go - items: $ref: "#/components/schemas/RequestTextBlock" type: array description: |- System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See Anthropic's [guide to system prompts](https://platform.claude.com/docs/en/docs/system-prompts). example: - - text: Today's date is 2024-06-01. type: text - Today's date is 2023-01-01. title: System temperature: description: |- Amount of randomness injected into the response. Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. Note that even with `temperature` of `0.0`, the results will not be fully deterministic. example: - 1 maximum: 1 minimum: 0 title: Temperature type: number tool_choice: description: How the model should use the provided tools. The model can use a specific tool, any available tool, or decide by itself. discriminator: mapping: any: "#/components/schemas/ToolChoiceAny" auto: "#/components/schemas/ToolChoiceAuto" tool: "#/components/schemas/ToolChoiceTool" propertyName: type oneOf: - $ref: "#/components/schemas/ToolChoiceAuto" - $ref: "#/components/schemas/ToolChoiceAny" - $ref: "#/components/schemas/ToolChoiceTool" title: Tool Choice tools: description: |- Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. Each tool definition includes: * `name`: Name of the tool. * `description`: Optional, but strongly-recommended description of the tool. * `input_schema`: [JSON schema](https://json-schema.org/) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ] ``` And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": { "ticker": "^GSPC" } } ] ``` You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See Anthropic's [guide](https://platform.claude.com/docs/en/docs/tool-use) for more details. example: - description: Get the current weather in a given location input_schema: properties: location: description: The city and state, e.g. San Francisco, CA type: string unit: description: Unit for the output - one of (celsius, fahrenheit) type: string required: - location type: object name: get_weather items: $ref: "#/components/schemas/Tool" title: Tools type: array top_k: description: |- Only sample from the top K options for each subsequent token. Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-write-expert-prompts-for-chatgpt-gpt-4-and-other-language-models-23133dc85550/). Recommended for advanced use cases only. You usually only need to use `temperature`. example: - 5 minimum: 0 title: Top K type: integer top_p: description: |- Use nucleus sampling. In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. Recommended for advanced use cases only. You usually only need to use `temperature`. example: - 0.7 maximum: 1 minimum: 0 title: Top P type: number thinking: $ref: "#/components/schemas/ThinkingConfig" required: - model - messages - max_tokens title: CreateMessageParams type: object ErrorResponse: properties: type: default: error enum: - error title: Type type: string error: discriminator: mapping: api_error: "#/components/schemas/APIError" authentication_error: "#/components/schemas/AuthenticationError" invalid_request_error: "#/components/schemas/InvalidRequestError" not_found_error: "#/components/schemas/NotFoundError" overloaded_error: "#/components/schemas/OverloadedError" permission_error: "#/components/schemas/PermissionError" rate_limit_error: "#/components/schemas/RateLimitError" propertyName: type oneOf: - $ref: "#/components/schemas/InvalidRequestError" - $ref: "#/components/schemas/AuthenticationError" - $ref: "#/components/schemas/PermissionError" - $ref: "#/components/schemas/NotFoundError" - $ref: "#/components/schemas/RateLimitError" - $ref: "#/components/schemas/APIError" - $ref: "#/components/schemas/OverloadedError" title: Error required: - type - error title: ErrorResponse type: object InputMessage: additionalProperties: false properties: role: enum: - user - agent title: Role type: string content: anyOf: - type: string x-stainless-skip: - go - items: discriminator: mapping: image: "#/components/schemas/RequestImageBlock" text: "#/components/schemas/RequestTextBlock" tool_result: "#/components/schemas/RequestToolResultBlock" tool_use: "#/components/schemas/RequestToolUseBlock" propertyName: type oneOf: - $ref: "#/components/schemas/RequestTextBlock" - $ref: "#/components/schemas/RequestImageBlock" - $ref: "#/components/schemas/RequestToolUseBlock" - $ref: "#/components/schemas/RequestToolResultBlock" x-stainless-python-extend-union: - ContentBlock x-stainless-python-extend-union-imports: - from .content_block import ContentBlock type: array example: - type: text text: What is a quaternion? title: Content required: - role - content title: InputMessage type: object InputSchema: additionalProperties: true properties: type: enum: - object title: Type type: string properties: anyOf: - type: object default: null title: Properties required: - type title: InputSchema type: object InvalidRequestError: properties: type: default: invalid_request_error enum: - invalid_request_error title: Type type: string message: default: Invalid request title: Message type: string required: - type - message title: InvalidRequestError type: object Message: example: - content: - text: Here is a haiku about cats:\n\nFeline grace and charm,\nPurring softly by the fire,\nCats reign supreme. type: text id: msg_013Zva2CMHLNnXjNJJKqJ2EF model: claude-3-haiku-20240307 role: assistant stop_reason: end_turn stop_sequence: null type: message usage: input_tokens: 14 output_tokens: 35 properties: id: description: |- Unique object identifier. The format and length of IDs may change over time. example: - msg_013Zva2CMHLNnXjNJJKqJ2EF title: Id type: string type: default: message description: |- Object type. For Messages, this is always `"message"`. enum: - message title: Type type: string role: default: assistant description: |- Conversational role of the generated message. This will always be `"assistant"`. enum: - agent title: Role type: string content: description: |- Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{"type": "text", "text": "Hi, I'm Claude."}] ``` If the request input `messages` ended with an `agent` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("} ] ``` Then the response `content` might be: ```json [{"type": "text", "text": "B)"}] ``` example: - - text: Hi! My name is Claude. type: text items: $ref: "#/components/schemas/ContentBlock" title: Content type: array model: $ref: "#/components/schemas/Model" stop_reason: anyOf: - enum: - end_turn - max_tokens - stop_sequence - tool_use type: string description: |- The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. title: Stop Reason stop_sequence: anyOf: - type: string default: null description: |- Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. title: Stop Sequence usage: allOf: - $ref: "#/components/schemas/Usage" description: |- Input and output token counts, representing the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. example: - input_tokens: 2095 output_tokens: 503 required: - id - type - role - content - model - stop_reason - stop_sequence - usage title: Message type: object x-stainless-python-custom-imports: - from .content_block import ContentBlock as ContentBlock NotFoundError: properties: type: default: not_found_error enum: - not_found_error title: Type type: string message: default: Not found title: Message type: string required: - type - message title: NotFoundError type: object OverloadedError: properties: type: default: overloaded_error enum: - overloaded_error title: Type type: string message: default: Overloaded title: Message type: string required: - type - message title: OverloadedError type: object PermissionError: properties: type: default: permission_error enum: - permission_error title: Type type: string message: default: Permission denied title: Message type: string required: - type - message title: PermissionError type: object RateLimitError: properties: type: default: rate_limit_error enum: - rate_limit_error title: Type type: string message: default: Rate limited title: Message type: string required: - type - message title: RateLimitError type: object RequestImageBlock: additionalProperties: false properties: type: enum: - image title: Type type: string source: discriminator: mapping: base64: "#/components/schemas/Base64ImageSource" propertyName: type oneOf: - $ref: "#/components/schemas/Base64ImageSource" title: Source cache_control: allOf: - $ref: "#/components/schemas/CacheControlEphemeral" title: Cache Control required: - type - source title: Image type: object RequestTextBlock: additionalProperties: false properties: type: enum: - text title: Type type: string text: minLength: 1 title: Text type: string cache_control: allOf: - $ref: "#/components/schemas/CacheControlEphemeral" title: Cache Control required: - type - text title: Text type: object RequestToolResultBlock: additionalProperties: false properties: type: enum: - tool_result title: Type type: string tool_use_id: pattern: ^[a-zA-Z0-9_-]+$ title: Tool Use Id type: string is_error: default: false title: Is Error type: boolean content: anyOf: - type: string x-stainless-skip: - go - items: discriminator: mapping: image: "#/components/schemas/RequestImageBlock" text: "#/components/schemas/RequestTextBlock" propertyName: type oneOf: - $ref: "#/components/schemas/RequestTextBlock" - $ref: "#/components/schemas/RequestImageBlock" type: array x-stainless-naming: python: type_name: Content title: Content cache_control: allOf: - $ref: "#/components/schemas/CacheControlEphemeral" title: Cache Control required: - type - tool_use_id title: Tool Result type: object RequestToolUseBlock: additionalProperties: false properties: type: enum: - tool_use title: Type type: string id: pattern: ^[a-zA-Z0-9_-]+$ title: Id type: string name: maxLength: 64 minLength: 1 pattern: ^[a-zA-Z0-9_-]{1,64}$ title: Name type: string input: title: Input type: object cache_control: allOf: - $ref: "#/components/schemas/CacheControlEphemeral" title: Cache Control required: - type - id - name - input title: Tool Use type: object ResponseTextBlock: properties: type: default: text enum: - text title: Type type: string text: maxLength: 5000000 minLength: 0 title: Text type: string required: - type - text title: Text type: object ResponseToolUseBlock: properties: type: default: tool_use enum: - tool_use title: Type type: string id: pattern: ^[a-zA-Z0-9_-]+$ title: Id type: string name: minLength: 1 title: Name type: string input: title: Input type: object required: - type - id - name - input title: Tool Use type: object Tool: additionalProperties: false properties: description: description: |- Description of what this tool does. Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. example: - Get the current weather in a given location title: Description type: string name: maxLength: 64 minLength: 1 pattern: ^[a-zA-Z0-9_-]{1,64}$ title: Name type: string input_schema: allOf: - $ref: "#/components/schemas/InputSchema" description: |- [JSON schema](https://json-schema.org/) for this tool's input. This defines the shape of the `input` that your tool accepts and that the model will produce. example: - properties: location: description: The city and state, e.g. San Francisco, CA type: string unit: description: Unit for the output - one of (celsius, fahrenheit) type: string required: - location type: object cache_control: allOf: - $ref: "#/components/schemas/CacheControlEphemeral" title: Cache Control required: - name - input_schema title: Tool type: object ToolChoiceAny: additionalProperties: false description: The model will use any available tools. properties: type: enum: - any title: Type type: string required: - type title: ToolChoiceAny type: object ToolChoiceAuto: additionalProperties: false description: The model will automatically decide whether to use tools. properties: type: enum: - auto title: Type type: string required: - type title: ToolChoiceAuto type: object ToolChoiceTool: additionalProperties: false description: The model will use the specified tool with `tool_choice.name`. properties: type: enum: - tool title: Type type: string name: description: The name of the tool to use. title: Name type: string required: - type - name title: ToolChoiceTool type: object Usage: properties: input_tokens: description: The number of input tokens which were used. example: - 2095 title: Input Tokens type: integer output_tokens: description: The number of output tokens which were used. example: - 503 title: Output Tokens type: integer cache_creation_input_tokens: description: The number of input tokens written to the cache when creating a new cache entry. example: - 2051 title: Cache Creation Input Tokens type: integer cache_read_input_tokens: description: The number of input tokens read from the cache. example: - 2051 title: Cache Read Input Tokens type: integer required: - input_tokens - output_tokens title: Usage type: object ContentBlock: discriminator: mapping: text: "#/components/schemas/ResponseTextBlock" tool_use: "#/components/schemas/ResponseToolUseBlock" thinking: "#/components/schemas/ResponseThinkingBlock" propertyName: type oneOf: - $ref: "#/components/schemas/ResponseTextBlock" - $ref: "#/components/schemas/ResponseToolUseBlock" - $ref: "#/components/schemas/ResponseThinkingBlock" ResponseThinkingBlock: type: object description: A thinking content block containing Claude's reasoning process when extended thinking is enabled. properties: type: type: string enum: ["thinking"] description: The type of content block. thinking: type: string description: Claude's internal reasoning process. signature: type: string description: A signature verifying the thinking block's authenticity. required: - type - thinking ThinkingConfig: type: object title: Thinking description: |- Configuration for enabling Claude's extended thinking. When enabled, responses include `thinking` content blocks showing Claude's reasoning process before the final answer. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details. properties: type: type: string enum: ["enabled"] description: Must be "enabled" to activate extended thinking. budget_tokens: type: integer minimum: 1024 description: Maximum number of tokens Claude can use for thinking. Must be ≥1024 and less than max_tokens. required: - type - budget_tokens Model: title: Model description: The model that will complete your prompt. See [models](https://platform.claude.com/docs/en/docs/models-overview) for additional details and options. type: string #============== Mistral schemas ============== AssistantMessage: properties: content: title: Content anyOf: - type: string - items: $ref: "#/components/schemas/ContentChunk" type: array tool_calls: anyOf: - items: $ref: "#/components/schemas/ToolCall" type: array title: Tool Calls prefix: type: boolean title: Prefix default: false role: type: string default: assistant title: Role enum: - assistant additionalProperties: false type: object title: AgentMessage FIMCompletionRequest: properties: model: anyOf: - type: string title: Model default: codestral-2501 description: |- ID of the model to use. Only compatible for now with: - `codestral-2501` temperature: anyOf: - type: number maximum: 1.5 minimum: 0 title: Temperature description: What sampling temperature to use, we recommend between 0.0 and 0.7. Higher values like 0.7 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. The default value varies depending on the model you are targeting. Call the `/models` endpoint to retrieve the appropriate value. top_p: type: number maximum: 1 minimum: 0 title: Top P default: 1 description: Nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both. max_tokens: anyOf: - type: integer minimum: 0 title: Max Tokens description: The maximum number of tokens to generate in the completion. The token count of your prompt plus `max_tokens` cannot exceed the model's context length. stream: type: boolean title: Stream default: false description: "Whether to stream back partial progress. If set, tokens will be sent as data-only server-side events as they become available, with the stream terminated by a data: [DONE] message. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON." stop: anyOf: - type: string - items: type: string type: array title: Stop description: Stop generation if this token is detected. Or if one of these tokens is detected when providing an array random_seed: anyOf: - type: integer minimum: 0 title: Random Seed description: The seed to use for random sampling. If set, different calls will generate deterministic results. prompt: type: string title: Prompt description: The text/code to complete. suffix: anyOf: - type: string title: Suffix default: "" description: Optional text/code that adds more context for the model. When given a `prompt` and a `suffix` the model will fill what is between them. When `suffix` is not provided, the model will simply execute completion starting with `prompt`. min_tokens: anyOf: - type: integer minimum: 0 title: Min Tokens description: The minimum number of tokens to generate in the completion. additionalProperties: false type: object required: - prompt - model title: FIMCompletionRequest FunctionCall: properties: name: type: string title: Name arguments: title: Arguments anyOf: - type: object additionalProperties: true - type: string additionalProperties: false type: object required: - name - arguments title: FunctionCall ImageURL: properties: url: type: string title: Url detail: anyOf: - type: string title: Detail additionalProperties: false type: object required: - url title: ImageURL ImageURLChunk: properties: type: type: string enum: - image_url title: Type default: image_url image_url: anyOf: - $ref: "#/components/schemas/ImageURL" - type: string title: Image Url additionalProperties: false type: object required: - image_url title: ImageURLChunk description: '{"type":"image_url","image_url":{"url":"data:image/png;base64,iVBORw0' TextChunk: properties: type: type: string enum: - text title: Type default: text text: type: string title: Text additionalProperties: false type: object required: - text title: TextChunk ToolCall: properties: id: type: string title: Id default: "null" type: $ref: "#/components/schemas/ToolTypes" default: function function: $ref: "#/components/schemas/FunctionCall" additionalProperties: false type: object required: - function title: ToolCall ToolTypes: type: string enum: - function title: ToolTypes ContentChunk: oneOf: - $ref: "#/components/schemas/TextChunk" - $ref: "#/components/schemas/ImageURLChunk" discriminator: propertyName: type mapping: image_url: "#/components/schemas/ImageURLChunk" text: "#/components/schemas/TextChunk" title: ContentChunk UsageInfo: title: UsageInfo type: object properties: prompt_tokens: type: integer example: 16 completion_tokens: type: integer example: 34 total_tokens: type: integer example: 50 required: - prompt_tokens - completion_tokens - total_tokens ResponseBase: type: object title: ResponseBase properties: id: type: string example: cmpl-e5cc70bb28c444948073e77776eb30ef object: type: string example: chat.completion model: type: string example: mistral-small-latest usage: $ref: "#/components/schemas/UsageInfo" ChatCompletionChoice: title: ChatCompletionChoice type: object required: - index - finish_reason - message properties: index: type: integer example: 0 message: $ref: "#/components/schemas/AssistantMessage" finish_reason: type: string enum: - stop - length - model_length - error - tool_calls example: stop DeltaMessage: title: DeltaMessage type: object properties: role: anyOf: - type: string content: anyOf: - type: string - items: $ref: "#/components/schemas/ContentChunk" type: array tool_calls: anyOf: - type: array items: $ref: "#/components/schemas/ToolCall" ChatCompletionResponseBase: allOf: - $ref: "#/components/schemas/ResponseBase" - type: object title: ChatCompletionResponseBase properties: created: type: integer example: 1702256327 ChatCompletionResponse: allOf: - $ref: "#/components/schemas/ChatCompletionResponseBase" - type: object title: ChatCompletionResponse properties: choices: type: array items: $ref: "#/components/schemas/ChatCompletionChoice" required: - id - object - data - model - usage FIMCompletionResponse: allOf: - $ref: "#/components/schemas/ChatCompletionResponse" - type: object properties: model: type: string example: codestral-latest CompletionEvent: title: CompletionEvent type: object required: - data properties: data: $ref: "#/components/schemas/CompletionChunk" CompletionChunk: title: CompletionChunk type: object required: - id - model - choices properties: id: type: string object: type: string created: type: integer model: type: string usage: $ref: "#/components/schemas/UsageInfo" choices: type: array items: $ref: "#/components/schemas/CompletionResponseStreamChoice" CompletionResponseStreamChoice: title: CompletionResponseStreamChoice type: object required: - index - delta - finish_reason properties: index: type: integer delta: $ref: "#/components/schemas/DeltaMessage" finish_reason: type: string enum: - stop - length - error - tool_calls CreateEmbeddingRequest: type: object properties: input: description: Input text to get embeddings for, encoded as a string or array of tokens. To get embeddings for multiple inputs in a single request, pass an array of strings or array of tokens, e.g. `["text1", "text2"]`. Each input must not exceed 8192 tokens in length. oneOf: - type: string - type: array items: type: string - type: array items: type: number - type: array items: type: array items: type: number model: description: ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see OpenAI's [Model overview](https://platform.openai.com/docs/models/overview) for descriptions of them. oneOf: - type: string - type: string enum: [ "text-embedding-ada-002", "text-embedding-3-small", "text-embedding-3-large", ] encoding_format: description: The format to return the embeddings in. Can be either `float` or `base64`. type: string enum: ["float", "base64"] default: "float" dimensions: description: The number of dimensions the resulting output embeddings should have. Only supported in `text-embedding-3` and later models. type: integer minimum: 1 user: description: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. type: string required: - model - input Embedding: type: object properties: index: type: integer description: The index of the embedding in the list of embeddings. embedding: type: array items: type: number description: The embedding vector, which is a list of floats. The length of vector depends on the model as listed in the [embedding guide](https://platform.openai.com/docs/guides/embeddings). object: type: string enum: ["embedding"] description: The object type, which is always "embedding". required: - index - embedding - object CreateEmbeddingResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/Embedding" description: The list of embeddings generated by the model. model: type: string description: The name of the model used to generate the embedding. object: type: string enum: ["list"] description: The object type, which is always "list". usage: type: object properties: prompt_tokens: type: integer description: The number of tokens used for the prompt(s). total_tokens: type: integer description: The total number of tokens used by the request. required: - prompt_tokens - total_tokens required: - data - model - object - usage StructuredOutputConfig: type: object description: Specification for structured output format. When type is object/array and no schema is provided, the response will be JSON but can have any structure. When the type is enum, you must provide an enum parameter with an array of strings as options. properties: type: type: string enum: [object, array, enum] description: The type of structured output schema: type: object description: JSON Schema definition for the output (required for object/array types with specific structure). Search for "JSON to JSON Schema" in the web to find a tool to convert any JSON into the required JSON Schema format. enum: type: array items: type: string description: Array of allowed values (required for enum type). Values must be of type string. oneOf: - properties: type: enum: [enum] enum: type: array items: type: string - properties: type: enum: [object, array] schema: type: object - properties: type: enum: [object, array] UsageExportRequest: type: object description: Request body for usage export endpoints properties: from: type: object description: Start date and timezone for the export properties: date: type: string format: date-time description: Start date in ISO 8601 format example: "2024-01-01T00:00:00.000Z" timezone: type: string description: Timezone for the date range example: "UTC" required: - date - timezone to: type: object description: End date and timezone for the export properties: date: type: string format: date-time description: End date in ISO 8601 format example: "2024-01-31T23:59:59.999Z" timezone: type: string description: Timezone for the date range example: "UTC" required: - date - timezone required: - from - to UsageExportModelGroupByRequest: allOf: - $ref: "#/components/schemas/UsageExportRequest" - type: object properties: group_by: type: string description: Optional aggregation dimension. enum: ["model"] UsageExportUsersRequest: allOf: - $ref: "#/components/schemas/UsageExportRequest" - type: object properties: group_by: type: string description: Optional aggregation dimension. `department` and `company_name` group usage without user identity. enum: ["model", "department", "company_name"] breakdown: type: string description: Optional split of a department or company group by agent or model. Valid only when `group_by` is `department` or `company_name`. enum: ["agent", "model"] UsageExportModelsRequest: allOf: - $ref: "#/components/schemas/UsageExportRequest" - type: object properties: group_by: type: string description: Optional aggregation dimension. `deployment` is only available for BYOK workspaces. enum: ["source", "deployment"] UsageExportResponse: type: object description: Successful response from usage export endpoints properties: success: type: boolean description: Indicates if the export was successful example: true data: type: object description: Export data information properties: filePath: type: string description: Path to the generated export file example: "agents-usage/workspace-id/agents-usage-2024-01-01-2024-01-31-abc12345.csv" downloadUrl: type: string format: uri description: Signed URL to download the export file example: "https://storage.example.com/signed-url" dataType: type: string description: Type of data exported enum: ["assistants", "agents", "api_keys", "users", "projects", "models", "workflows"] example: "assistants" recordCount: type: integer description: Number of records in the export example: 1250 dateRange: type: object description: Actual date range of the exported data properties: from: type: string format: date-time description: Start date of the export example: "2024-01-01T00:00:00.000Z" to: type: string format: date-time description: End date of the export example: "2024-01-31T23:59:59.999Z" required: - from - to required: - filePath - downloadUrl - dataType - recordCount - dateRange required: - success - data UsageExportError: type: object description: Error response from usage export endpoints properties: message: type: string description: Detailed error message example: "No usage data found for the selected period" code: type: string description: Machine-readable error code example: "NOT_FOUND" details: type: object description: Additional error context. Oversized exports include the scanned row counts and the configured row limit. required: - message WorkflowRunExportResponse: type: object description: Flattened workflow run and node execution rows. required: - data properties: data: type: array items: $ref: "#/components/schemas/WorkflowRunExportRow" WorkflowRunExportRow: type: object description: Data for one workflow run and its node execution. required: - run_id - run_number - run_status - run_created_at - run_updated_at - workflow_version - trigger_mode - node_execution_id - node_id - node_type - node_status - node_created_at - node_updated_at - failure_code - input - input_error - output - output_error - logs - data_redacted - execution_data_expired_at properties: run_id: type: string format: uuid description: ID of the workflow run. run_number: type: integer description: Sequential number of the run within the workflow. run_status: type: string enum: [PENDING, IN_PROGRESS, AWAITING_INPUT, COMPLETED, FAILED, CANCELLED] description: Status of the workflow run. run_created_at: type: string format: date-time description: Creation time of the workflow run. run_updated_at: type: string format: date-time description: Last update time of the workflow run. workflow_version: type: string description: Version of the workflow used for the run. trigger_mode: type: string nullable: true enum: [WEBHOOK, FORM, SCHEDULED, INTEGRATION_POLLING, MANUAL] description: Mode that triggered the run. node_execution_id: type: string format: uuid nullable: true description: ID of the node execution. node_id: type: string format: uuid nullable: true description: ID of the workflow node. node_type: type: string nullable: true description: Type of the workflow node. node_status: type: string nullable: true enum: [NONE, IN_PROGRESS, AWAITING_INPUT, COMPLETED, FAILED, CANCELLED] description: Status of the node execution. node_created_at: type: string format: date-time nullable: true description: Creation time of the node execution. node_updated_at: type: string format: date-time nullable: true description: Last update time of the node execution. failure_code: type: string nullable: true description: Failure code when the node execution fails. input: nullable: true description: Input data for the node execution. oneOf: - type: object additionalProperties: true - type: array items: {} - type: string - type: number - type: boolean input_error: nullable: true description: Error data for the node input. oneOf: - type: object additionalProperties: true - type: array items: {} - type: string - type: number - type: boolean output: nullable: true description: Output data for the node execution. oneOf: - type: object additionalProperties: true - type: array items: {} - type: string - type: number - type: boolean output_error: nullable: true description: Error data for the node output. oneOf: - type: object additionalProperties: true - type: array items: {} - type: string - type: number - type: boolean logs: nullable: true description: Logs generated during the node execution. oneOf: - type: object additionalProperties: true - type: array items: {} - type: string - type: number - type: boolean data_redacted: type: boolean description: Whether payload fields were omitted because access to the node data could not be established. execution_data_expired_at: type: string format: date-time nullable: true description: Time when detailed execution data expired. WorkflowRunExportError: type: object description: Error response from the Workflow Run Export API. properties: message: type: string description: Error message. code: type: string description: Machine-readable error code, when available. details: type: object additionalProperties: true description: Additional error context, when available. errors: type: array items: type: object additionalProperties: true description: Validation details for malformed query parameters. required: - message AuditLog: type: object properties: id: type: string format: uuid description: Unique audit log entry ID created_at: type: string format: date-time description: When the event occurred actor_id: type: string format: uuid nullable: true description: ID of the actor who performed the action actor_type: type: string enum: [USER, API_KEY, SYSTEM, SCIM] description: Type of actor actor_name: type: string nullable: true description: Human-readable actor name (e.g. email, API key name, "SCIM") action: type: string description: | Action in dot notation: `{entity}.{operation}`, where `entity` is the snake_case model name and `operation` is one of `created`, `updated`, or `deleted`. example: "user.updated" entity_type: type: string description: | PascalCase model name of the affected entity (e.g. `User`, `Workspace`, `Group`, `IntegrationConnection`). entity_id: type: string description: ID of the affected entity ip_address: type: string nullable: true description: IP address of the request user_agent: type: string nullable: true description: User-Agent header of the request changes: type: object nullable: true description: "Structured diff with `before` and `after` objects containing only changed fields" properties: before: type: object description: Field values before the change after: type: object description: Field values after the change snapshot: type: object nullable: true description: Full entity snapshot or additional event metadata (e.g. on delete/create events, or extra context like failed login details) AuditLogListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/AuditLog" next_cursor: type: string format: uuid nullable: true description: Cursor for the next page, null if no more results # User Management API schemas InviteUsersRequest: type: object required: - users properties: users: type: array minItems: 1 description: List of users to invite. At least one user is required. items: type: object required: - email properties: email: type: string format: email description: Email address of the user to invite example: "jane.doe@example.com" role: type: string enum: - member - editor - admin description: "Role to assign. If omitted, defaults to `member`." example: "member" InviteUsersResponse: type: object properties: status: type: string enum: - success description: Always "success" when the request is processed example: "success" message: type: string description: Human-readable summary of the result example: "Invitations processed" successfulInvites: type: array items: type: string format: email description: Email addresses that were successfully invited example: - "alice@example.com" - "bob@example.com" invalidEmails: type: array items: type: string description: Email addresses that failed deeper validation (e.g., unreachable domain) example: [] required: - status - message - successfulInvites - invalidEmails InviteUsersError: type: object properties: message: type: string description: Error message example: "Invalid request body" errors: type: array items: type: object description: Detailed validation errors (present on 400 responses) error: type: string description: Additional error details (present on 500 responses) required: - message UserEmailRequest: type: object required: - email properties: email: type: string format: email description: Email address of the user example: "user@example.com" UpdateUserRoleRequest: type: object additionalProperties: false required: - email - role properties: email: type: string format: email description: Email address of the active workspace member example: "user@example.com" role: type: string enum: - member - editor - admin description: Workspace system role. Values are lowercase. example: "editor" UpdateUserRoleResponse: type: object properties: status: type: string enum: - success description: Always "success" when the role is updated example: "success" email: type: string format: email description: Email address of the updated member example: "user@example.com" role: type: string enum: - member - editor - admin description: System role after the update example: "editor" required: - status - email - role UserManagementResponse: type: object properties: status: type: string enum: - success description: Always "success" when the request is processed example: "success" message: type: string description: Human-readable summary of the result example: "User deactivated" required: - status - message UserManagementError: type: object properties: message: type: string description: Error message example: "User not found or not an active member" required: - message securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: API key as Bearer token. Format "Bearer YOUR_API_KEY"