{ "openapi": "3.0.0", "info": { "title": "DUST API Documentation", "version": "1.0.2", "description": "The OpenAPI specification for the Dust.tt API", "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://dust.tt", "description": "Dust.tt API (us-central1)" }, { "url": "https://eu.dust.tt", "description": "Dust.tt API (europe-west1)" } ], "tags": [ { "name": "Agents", "description": "Agent configurations" }, { "name": "Apps", "description": "Dust apps" }, { "name": "Conversations", "description": "Conversations" }, { "name": "DatasourceViews", "description": "Data source views" }, { "name": "Datasources", "description": "Data sources" }, { "name": "Feedbacks", "description": "Message feedbacks" }, { "name": "MCP", "description": "MCP servers" }, { "name": "Mentions", "description": "Mentions" }, { "name": "Search", "description": "Search" }, { "name": "Tools", "description": "Tools" }, { "name": "Triggers", "description": "Triggers" }, { "name": "Skills", "description": "Skills" }, { "name": "Spaces", "description": "Spaces" }, { "name": "Workspace", "description": "Workspace" }, { "name": "Private User", "description": "Private API - User" }, { "name": "Private Authentication", "description": "Private API - Authentication (WorkOS)" }, { "name": "Private Agents", "description": "Private API - Agent configurations" }, { "name": "Private Conversations", "description": "Private API - Conversations" }, { "name": "Private Messages", "description": "Private API - Messages" }, { "name": "Private Events", "description": "Private API - SSE event streams" }, { "name": "Private Files", "description": "Private API - File uploads" }, { "name": "Private Mentions", "description": "Private API - Mention suggestions" }, { "name": "Private Spaces", "description": "Private API - Spaces and data source views" }, { "name": "Private Extension", "description": "Private API - Extension configuration" }, { "name": "Private Workspace", "description": "Private API - Workspace settings" } ], "paths": { "/api/user": { "get": { "summary": "Get current user", "description": "Returns the authenticated user with their workspaces and subscriber hash.", "tags": [ "Private User" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "The authenticated user", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/PrivateUser" } } } } } }, "404": { "description": "User not found" } } }, "patch": { "summary": "Update current user", "description": "Update the authenticated user's profile (name, job type, favorite platforms, image).", "tags": [ "Private User" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "firstName", "lastName" ], "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "jobType": { "type": "string" }, "imageUrl": { "type": "string", "nullable": true }, "favoritePlatforms": { "type": "array", "items": { "type": "string" } }, "emailProvider": { "type": "string" }, "workspaceId": { "type": "string" } } } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request body" }, "404": { "description": "User not found" } } } }, "/api/v1/w/{wId}/analytics/export": { "get": { "summary": "Export workspace analytics", "description": "Export analytics data for the workspace identified by {wId} in CSV or JSON format.", "tags": [ "Workspace" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "table", "required": true, "description": "The analytics table to export:\n- \"usage_metrics\": Messages, conversations, and active users over time.\n- \"active_users\": Daily, weekly, and monthly active user counts.\n- \"source\": Message volume by context origin (web, slack, etc.).\n- \"agents\": Top agents by message count.\n- \"users\": Top users by message count.\n- \"skill_usage\": Skill executions and unique users over time.\n- \"tool_usage\": Tool executions and unique users over time.\n- \"messages\": Detailed message-level logs.\n- \"feedback\": Detailed message-level feedback (thumbs, content, conversation URL).\n", "schema": { "type": "string", "enum": [ "usage_metrics", "active_users", "source", "agents", "users", "skill_usage", "tool_usage", "messages", "feedback" ] } }, { "in": "query", "name": "startDate", "required": true, "description": "Start date in YYYY-MM-DD format", "schema": { "type": "string", "format": "date" } }, { "in": "query", "name": "endDate", "required": true, "description": "End date in YYYY-MM-DD format", "schema": { "type": "string", "format": "date" } }, { "in": "query", "name": "timezone", "required": false, "description": "IANA timezone name (defaults to UTC)", "schema": { "type": "string" } }, { "in": "query", "name": "format", "required": false, "description": "Output format (defaults to csv)", "schema": { "type": "string", "enum": [ "csv", "json" ] } } ], "responses": { "200": { "description": "The analytics data in CSV or JSON format", "content": { "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Invalid request query parameters" }, "403": { "description": "Requires an API key with admin scope" } } } }, "/api/v1/w/{wId}/assistant/agent_configurations": { "get": { "summary": "List agents", "description": "Get the agent configurations for the workspace identified by {wId}.", "tags": [ "Agents" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "view", "required": false, "description": "The view to use when retrieving agents:\n- all: Retrieves all non-private agents (default if not authenticated)\n- list: Retrieves all active agents accessible to the user (default if authenticated)\n- published: Retrieves all agents with published scope\n- global: Retrieves all global agents\n- favorites: Retrieves all agents marked as favorites by the user (only available to authenticated users)\n", "schema": { "type": "string", "enum": [ "all", "list", "workspace", "published", "global", "favorites" ] } }, { "in": "query", "name": "withAuthors", "required": false, "description": "When set to 'true', includes recent authors information for each agent", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agent configurations for the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentConfigurations": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConfiguration" }, "description": "Array of agent configurations, optionally including lastAuthors if withAuthors=true" } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token, or attempting to access restricted views without authentication." }, "404": { "description": "Workspace not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/assistant/agent_configurations/{sId}/export/yaml": { "get": { "summary": "Export agent configuration as YAML", "description": "Download the agent configuration identified by {sId} as a YAML file.", "tags": [ "Agents" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "sId", "required": true, "description": "ID of the agent configuration", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "The agent configuration as a downloadable YAML file", "content": { "text/yaml": { "schema": { "type": "string" } } }, "headers": { "Content-Disposition": { "description": "Attachment with suggested filename", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request. Invalid or missing parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Agent configuration not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/assistant/agent_configurations/{sId}": { "get": { "summary": "Get agent configuration", "description": "Retrieve the agent configuration identified by {sId} in the workspace identified by {wId}.", "tags": [ "Agents" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "sId", "required": true, "description": "ID of the agent configuration", "schema": { "type": "string" } }, { "in": "query", "name": "variant", "required": false, "description": "Configuration variant to retrieve. 'light' returns basic config without actions, 'full' includes complete actions/tools configuration", "schema": { "type": "string", "enum": [ "light", "full" ], "default": "light" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved agent configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentConfiguration": { "$ref": "#/components/schemas/AgentConfiguration" } } } } } }, "400": { "description": "Bad Request. Invalid or missing parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Agent configuration not found." }, "500": { "description": "Internal Server Error." } } }, "patch": { "summary": "Update agent configuration", "description": "Update the agent configuration identified by {sId} in the workspace identified by {wId}.", "tags": [ "Agents" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "sId", "required": true, "description": "ID of the agent configuration", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userFavorite": { "type": "boolean" }, "agent": { "type": "object", "properties": { "handle": { "type": "string" }, "description": { "type": "string" }, "scope": { "type": "string", "enum": [ "visible", "hidden" ] }, "avatar_url": { "type": "string" }, "max_steps_per_run": { "type": "number" }, "visualization_enabled": { "type": "boolean" } } }, "instructions": { "type": "string" }, "generation_settings": { "type": "object", "properties": { "model_id": { "type": "string" }, "provider_id": { "type": "string" }, "temperature": { "type": "number" }, "reasoning_effort": { "type": "string" } } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "standard", "protected" ] } } } }, "editors": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "email": { "type": "string" }, "full_name": { "type": "string" } } } }, "skills": { "type": "array", "description": "Replaces the skills enabled on the agent configuration.", "items": { "type": "object", "required": [ "sId", "name" ], "properties": { "sId": { "type": "string" }, "name": { "type": "string" } } } }, "toolset": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "MCP" ] }, "configuration": { "type": "object" } } } } } } } } }, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully updated agent configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentConfiguration": { "$ref": "#/components/schemas/AgentConfiguration" }, "skippedActions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "reason": { "type": "string" } } } } } } } } }, "400": { "description": "Bad Request. Invalid or missing parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Agent configuration not found." }, "500": { "description": "Internal Server Error." } } }, "delete": { "summary": "Archive agent configuration", "description": "Archive the agent configuration identified by {sId} in the workspace identified by {wId}. The agent is soft-archived and triggers/editor-group memberships associated with it are disabled.", "tags": [ "Agents" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "sId", "required": true, "description": "ID of the agent configuration", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully archived agent configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Bad Request. Invalid or missing parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. The caller is not allowed to archive this agent." }, "404": { "description": "Agent configuration not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/assistant/agent_configurations/import": { "post": { "summary": "Import agent configuration", "description": "Create a new agent configuration from a JSON body matching the agent config schema.", "tags": [ "Agents" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent", "instructions", "generation_settings", "tags", "editors", "toolset" ], "properties": { "agent": { "type": "object", "required": [ "handle", "description", "scope", "max_steps_per_run", "visualization_enabled" ], "properties": { "handle": { "type": "string" }, "description": { "type": "string" }, "scope": { "type": "string", "enum": [ "visible", "hidden" ] }, "avatar_url": { "type": "string" }, "max_steps_per_run": { "type": "number" }, "visualization_enabled": { "type": "boolean" } } }, "instructions": { "type": "string" }, "generation_settings": { "type": "object", "properties": { "model_id": { "type": "string" }, "provider_id": { "type": "string" }, "temperature": { "type": "number" }, "reasoning_effort": { "type": "string" } } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "standard", "protected" ] } } } }, "editors": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "email": { "type": "string" }, "full_name": { "type": "string" } } } }, "toolset": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "MCP" ] }, "configuration": { "type": "object" } } } } } } } } }, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully created agent configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentConfiguration": { "$ref": "#/components/schemas/AgentConfiguration" }, "skippedActions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "reason": { "type": "string" } } } } } } } } }, "400": { "description": "Bad Request. Invalid request body." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/assistant/agent_configurations/search": { "get": { "summary": "Search agents by name", "description": "Search for agent configurations by name in the workspace identified by {wId}.", "tags": [ "Agents" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "q", "required": true, "description": "Search query for agent configuration names", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved agent configurations", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentConfigurations": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConfiguration" } } } } } } }, "400": { "description": "Bad Request. Invalid or missing parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Workspace not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/cancel": { "post": { "tags": [ "Conversations" ], "summary": "Cancel message generation in a conversation", "parameters": [ { "name": "wId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" }, { "name": "cId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation ID" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "messageIds" ], "properties": { "messageIds": { "type": "array", "description": "List of message IDs to cancel generation for", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Message generation successfully canceled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the cancellation was successful" } } } } } }, "400": { "description": "Invalid request (invalid query parameters or request body)" } } } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/content_fragments": { "post": { "summary": "Create a content fragment", "description": "Create a new content fragment in the workspace identified by {wId}.", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentFragment" } } } }, "responses": { "200": { "description": "Content fragment created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentFragment" } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/events": { "get": { "summary": "Get the events for a conversation", "description": "Get the events for a conversation in the workspace identified by {wId}.", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "query", "name": "lastEventId", "required": false, "description": "ID of the last event", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Events for the conversation, view the \"Events\" page from this documentation for more information." }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Conversation not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/feedbacks": { "get": { "summary": "Get feedbacks for a conversation", "description": "Retrieves all feedback entries for a specific conversation.\nRequires authentication and read:conversation scope.\n", "tags": [ "Feedbacks" ], "parameters": [ { "name": "wId", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } }, { "name": "cId", "in": "path", "description": "Conversation ID", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of feedback entries for the conversation", "content": { "application/json": { "schema": { "type": "object", "properties": { "feedbacks": { "type": "array", "items": { "type": "object", "properties": { "messageId": { "type": "string", "description": "ID of the message that received feedback" }, "agentMessageId": { "type": "number", "description": "ID of the agent message" }, "userId": { "type": "number", "description": "ID of the user who gave feedback" }, "thumbDirection": { "type": "string", "enum": [ "up", "down" ], "description": "Direction of the thumb feedback" }, "content": { "type": "string", "nullable": true, "description": "Optional feedback content/comment" }, "createdAt": { "type": "number", "description": "Timestamp when feedback was created" }, "agentConfigurationId": { "type": "string", "description": "ID of the agent configuration" }, "agentConfigurationVersion": { "type": "number", "description": "Version of the agent configuration" }, "isConversationShared": { "type": "boolean", "description": "Whether the conversation was shared" } } } } } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Conversation not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/files/{rel}": { "get": { "tags": [ "Conversations" ], "summary": "Download a conversation-scoped file by path", "description": "Download a file from a conversation's file system by its scoped path. The path must\nbe conversation-scoped, i.e. start with `conversation/` (as surfaced by agent file\nsystem tools). The file content is streamed directly from the conversation mount.\n", "parameters": [ { "name": "wId", "in": "path", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "name": "cId", "in": "path", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "name": "rel", "in": "path", "required": true, "description": "Conversation-scoped file path, e.g. `conversation/foo.pdf` or\n`conversation/subdir/foo.pdf`. The `conversation/` prefix is required; any other\nscope prefix is rejected. Path traversal segments (`..`) are rejected.\n", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "File content streamed directly.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Missing or invalid path parameters (e.g. missing or wrong scope prefix)." }, "403": { "description": "Resolved path is outside the conversation scope." }, "404": { "description": "Conversation or file not found." } } } }, "/api/v1/w/{wId}/assistant/conversations/{cId}": { "get": { "summary": "Get a conversation", "description": "Get a conversation in the workspace identified by {wId}. Supports optional pagination of message content via limit and lastValue query parameters.", "tags": [ "Conversations" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "description": "Maximum number of messages to return. When omitted, all messages are returned.", "schema": { "type": "integer" } }, { "in": "query", "name": "lastValue", "required": false, "description": "Cursor value (message rank) from a previous response to fetch the next page of messages.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conversation retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Conversation not found." }, "500": { "description": "Internal Server Error." } } }, "patch": { "summary": "Update a conversation", "description": "Update a conversation's title or mark it as read or unread in the workspace identified by {wId}.", "tags": [ "Conversations" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "read" ], "properties": { "read": { "type": "boolean" } } }, { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Conversation updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Bad Request. Invalid or missing parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Conversation not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/mentions/suggestions": { "get": { "summary": "Get mention suggestions for a conversation", "description": "Get suggestions for mentions (agents and users) based on a query string, scoped to a specific conversation.", "tags": [ "Mentions" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "query", "name": "query", "required": true, "description": "Search query string to filter suggestions", "schema": { "type": "string" } }, { "in": "query", "name": "select", "required": false, "description": "Array of mention types to include. Can be \"agents\", \"users\", or both. If not provided, defaults to agents and users.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "agents", "users" ] } } }, { "in": "query", "name": "current", "required": false, "description": "Whether to include the current user in the suggestions.", "schema": { "type": "boolean" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of mention suggestions", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/RichMention" } } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Conversation not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/messages/{mId}/answer-question": { "post": { "summary": "Answer a user question in a conversation message", "description": "Submits an answer to a question asked by an agent in a specific message", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" }, { "in": "path", "name": "cId", "required": true, "schema": { "type": "string" }, "description": "Conversation ID" }, { "in": "path", "name": "mId", "required": true, "schema": { "type": "string" }, "description": "Message ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "actionId", "answer" ], "properties": { "actionId": { "type": "string", "description": "ID of the action to answer" }, "answer": { "type": "object", "required": [ "selectedOptions" ], "properties": { "selectedOptions": { "type": "array", "items": { "type": "integer" }, "description": "Indices of selected options" }, "customResponse": { "type": "string", "description": "Optional free-text response" } } } } } } } }, "responses": { "200": { "description": "Answer submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request body or action not blocked" }, "403": { "description": "User not authorized to answer this question" }, "404": { "description": "Conversation, message, or action not found" }, "500": { "description": "Internal server error" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/messages/{mId}/edit": { "post": { "tags": [ "Conversations" ], "summary": "Edit an existing message in a conversation", "parameters": [ { "name": "wId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" }, { "name": "cId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation ID" }, { "name": "mId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Message ID to edit" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content", "mentions" ], "properties": { "content": { "type": "string", "description": "New content for the message" }, "mentions": { "type": "array", "description": "List of agent mentions in the message", "items": { "type": "object", "required": [ "configurationId" ], "properties": { "configurationId": { "type": "string", "description": "ID of the mentioned agent configuration" } } } } } } } } }, "responses": { "200": { "description": "Message successfully edited", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "description": "The edited user message" }, "agentMessages": { "type": "array", "description": "Optional array of agent messages generated in response" } } } } } }, "400": { "description": "Invalid request (message not found or not a user message)" } } } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/messages/{mId}/events": { "get": { "summary": "Get events for a message", "description": "Get events for a message in the workspace identified by {wId}.", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "path", "name": "mId", "required": true, "description": "ID of the message", "schema": { "type": "string" } }, { "in": "query", "name": "lastEventId", "description": "ID of the last event received", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "The events", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the event" }, "type": { "type": "string", "description": "Type of the event" }, "data": { "$ref": "#/components/schemas/Message" } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/messages/{mId}/feedbacks": { "post": { "summary": "Submit feedback for a specific message in a conversation", "description": "Submit user feedback (thumbs up/down) for a specific message in a conversation.\nRequires authentication and update:conversation scope.\n", "tags": [ "Feedbacks" ], "parameters": [ { "name": "wId", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } }, { "name": "cId", "in": "path", "description": "Conversation ID", "required": true, "schema": { "type": "string" } }, { "name": "mId", "in": "path", "description": "Message ID", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "thumbDirection" ], "properties": { "thumbDirection": { "type": "string", "enum": [ "up", "down" ], "description": "Direction of the thumb feedback" }, "feedbackContent": { "type": "string", "description": "Optional feedback text content" }, "isConversationShared": { "type": "boolean", "description": "Whether the conversation is shared" } } } } } }, "responses": { "200": { "description": "Feedback submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request parameters or body" }, "401": { "description": "Unauthorized" }, "404": { "description": "Conversation or message not found" } } }, "delete": { "summary": "Delete feedback for a specific message", "description": "Delete user feedback for a specific message in a conversation.\nRequires authentication and update:conversation scope.\n", "tags": [ "Feedbacks" ], "parameters": [ { "name": "wId", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } }, { "name": "cId", "in": "path", "description": "Conversation ID", "required": true, "schema": { "type": "string" } }, { "name": "mId", "in": "path", "description": "Message ID", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Feedback deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Unauthorized" }, "404": { "description": "Conversation, message or feedback not found" } } } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/messages/{mId}/validate-action": { "post": { "summary": "Validate an action in a conversation message", "description": "Approves or rejects an action taken in a specific message in a conversation", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" }, { "in": "path", "name": "cId", "required": true, "schema": { "type": "string" }, "description": "Conversation ID" }, { "in": "path", "name": "mId", "required": true, "schema": { "type": "string" }, "description": "Message ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "actionId", "approved" ], "properties": { "actionId": { "type": "string", "description": "ID of the action to validate" }, "approved": { "type": "boolean", "description": "Whether the action is approved or rejected" } } } } } }, "responses": { "200": { "description": "Action validation successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request body" }, "404": { "description": "Conversation, message, or workspace not found" }, "500": { "description": "Internal server error" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/w/{wId}/assistant/conversations/{cId}/messages": { "post": { "summary": "Create a message", "description": "Create a message in the workspace identified by {wId} in the conversation identified by {cId}.", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "responses": { "200": { "description": "Message created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. Workspace or usage limits exceeded, or access denied." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/assistant/conversations": { "post": { "summary": "Create a new conversation", "description": "Create a new conversation in the workspace identified by {wId}.", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "$ref": "#/components/schemas/Message" }, "contentFragments": { "type": "array", "items": { "$ref": "#/components/schemas/ContentFragment" }, "description": "The list of content fragments to attach to this conversation (optional)" }, "title": { "type": "string", "description": "The title of the conversation", "example": "My conversation" }, "skipToolsValidation": { "type": "boolean", "description": "Whether to skip the tools validation of the agent messages triggered by this user message (optional, defaults to false)", "example": false }, "blocking": { "type": "boolean", "description": "Whether to wait for the agent to generate the initial message. If true the query will wait for the agent's answer. If false (default), the API will return a conversation ID directly and you will need to use streaming events to get the messages.", "example": true }, "spaceId": { "type": "string", "description": "The sId of the space (project) in which to create the conversation (optional). If not provided, the conversation is created outside projects", "example": "space_abc123" } } } } } }, "responses": { "200": { "description": "Conversation created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/w/{wId}/assistant/mentions/parse": { "post": { "summary": "Parse mentions in markdown text", "description": "Parses pasted text containing @ mentions and converts them to the proper mention format.\nMatches @agentName or @userName patterns against available agents and users.\n", "tags": [ "Mentions" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "markdown" ], "properties": { "markdown": { "type": "string", "description": "Markdown text containing @ mentions to parse", "example": "Hello @JohnDoe, can you help with @MyAgent?" } } } } } }, "responses": { "200": { "description": "Parsed markdown with mentions converted to proper format", "content": { "application/json": { "schema": { "type": "object", "properties": { "markdown": { "type": "string", "description": "Processed markdown text with mentions converted to serialized format" } } } } } }, "400": { "description": "Bad Request. Missing or invalid request body." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/assistant/mentions/suggestions": { "get": { "summary": "Get mention suggestions", "description": "Get suggestions for mentions (agents and users) based on a query string.", "tags": [ "Mentions" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "query", "required": true, "description": "Search query string to filter suggestions", "schema": { "type": "string" } }, { "in": "query", "name": "select", "required": false, "description": "Array of mention types to include. Can be \"agents\", \"users\", or both. If not provided, defaults to agents and users.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "agents", "users" ] } } }, { "in": "query", "name": "current", "required": false, "description": "Whether to include the current user in the suggestions.", "schema": { "type": "boolean" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of mention suggestions", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/RichMention" } } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/files": { "post": { "tags": [ "Conversations" ], "summary": "Create a file upload URL", "parameters": [ { "name": "wId", "in": "path", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contentType", "fileName", "fileSize", "useCase", "useCaseMetadata" ], "properties": { "contentType": { "type": "string", "description": "MIME type of the file" }, "fileName": { "type": "string", "description": "Name of the file" }, "fileSize": { "type": "integer", "description": "Size of the file in bytes" }, "useCase": { "type": "string", "description": "Intended use case for the file, use \"conversation\"" }, "useCaseMetadata": { "type": "string", "description": "(optional) Metadata for the use case, for conversation useCase should be dictionary with conversationId stringified" } } } } } }, "responses": { "200": { "description": "File upload URL created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "properties": { "sId": { "type": "string", "description": "Unique string identifier for the file" }, "uploadUrl": { "type": "string", "description": "Upload URL for the file" } } } } } } } }, "400": { "description": "Invalid request or unsupported file type" }, "401": { "description": "Unauthorized" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/w/{wId}/mcp/deregister": { "post": { "summary": "Deregister a client-side MCP server", "description": "[Documentation](https://docs.dust.tt/docs/client-side-mcp-server)\nRemove a previously registered client-side MCP server registration.\n", "tags": [ "MCP" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "serverId" ], "properties": { "serverId": { "type": "string", "description": "The ID of the registered MCP server" } } } } } }, "responses": { "200": { "description": "Server deregistered successfully" }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. User does not have access to the workspace." } } } }, "/api/v1/w/{wId}/mcp/heartbeat": { "post": { "summary": "Update heartbeat for a client-side MCP server", "description": "[Documentation](https://docs.dust.tt/docs/client-side-mcp-server)\nUpdate the heartbeat for a previously registered client-side MCP server.\nThis extends the TTL for the server registration.\n", "tags": [ "MCP" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "serverId" ], "properties": { "serverId": { "type": "string", "description": "The ID of the registered MCP server" } } } } } }, "responses": { "200": { "description": "Heartbeat updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. User does not have access to the workspace." }, "404": { "description": "Not Found. MCP server not registered or expired." } } } }, "/api/v1/w/{wId}/mcp/register": { "post": { "summary": "Register a client-side MCP server", "description": "[Documentation](https://docs.dust.tt/docs/client-side-mcp-server)\nRegister a client-side MCP server to Dust.\nThe registration is scoped to the current user and workspace.\nA serverId identifier is generated and returned in the response.\n", "tags": [ "MCP" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "serverName" ], "properties": { "serverName": { "type": "string", "description": "Name of the MCP server" } } } } } }, "responses": { "200": { "description": "Server registered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "serverId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. User does not have access to the workspace." } } } }, "/api/v1/w/{wId}/mcp/requests": { "get": { "summary": "Stream MCP tool requests for a workspace", "description": "[Documentation](https://docs.dust.tt/docs/client-side-mcp-server)\nServer-Sent Events (SSE) endpoint that streams MCP tool requests for a workspace.\nThis endpoint is used by client-side MCP servers to listen for tool requests in real-time.\nThe connection will remain open and events will be sent as new tool requests are made.\n", "tags": [ "MCP" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "serverId", "required": true, "description": "ID of the MCP server to filter events for", "schema": { "type": "string" } }, { "in": "query", "name": "lastEventId", "required": false, "description": "ID of the last event to filter events for", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection established successfully. Events will be streamed in Server-Sent Events format.\nEach event will contain a tool request that needs to be processed by the MCP server.\n", "content": { "text/event-stream": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of the event (e.g. \"tool_request\")" }, "data": { "type": "object", "description": "The tool request data" } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. You don't have access to this workspace or MCP server." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/mcp/results": { "post": { "summary": "Submit MCP tool execution results", "description": "[Documentation](https://docs.dust.tt/docs/client-side-mcp-server)\nEndpoint for client-side MCP servers to submit the results of tool executions.\nThis endpoint accepts the output from tools that were executed locally.\n", "tags": [ "MCP" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "serverId" ], "properties": { "result": { "type": "object", "description": "The result data from the tool execution" }, "serverId": { "type": "string", "description": "ID of the MCP server submitting the results" } } } } } }, "responses": { "200": { "description": "Tool execution results successfully submitted" }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. You don't have access to this workspace or MCP server." }, "404": { "description": "Conversation or message not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/search": { "get": { "summary": "Search for nodes in the workspace (streaming)", "description": "Search for nodes in the workspace with SSE streaming", "tags": [ "Search" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "query", "required": true, "description": "The search query (minimum 3 characters)", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "description": "Number of results per page (1-100, default 25)", "schema": { "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "description": "Cursor for pagination", "schema": { "type": "string" } }, { "in": "query", "name": "viewType", "required": false, "description": "Type of view to filter results", "schema": { "type": "string", "enum": [ "all", "document", "table" ] } }, { "in": "query", "name": "spaceIds", "required": false, "description": "Comma-separated list of space IDs to search in", "schema": { "type": "string" } }, { "in": "query", "name": "includeDataSources", "required": false, "description": "Whether to include data sources", "schema": { "type": "boolean" } }, { "in": "query", "name": "searchSourceUrls", "required": false, "description": "Whether to search source URLs", "schema": { "type": "boolean" } }, { "in": "query", "name": "includeTools", "required": false, "description": "Whether to include tool results", "schema": { "type": "boolean" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Search results streamed successfully", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Search for nodes in the workspace", "description": "Search for nodes in the workspace", "tags": [ "Search" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "The search query" }, "includeDataSources": { "type": "boolean", "description": "List of data source IDs to include in search" }, "viewType": { "type": "string", "description": "Type of view to filter results" }, "spaceIds": { "type": "array", "description": "List of space IDs to search in", "items": { "type": "string" } }, "nodeIds": { "type": "array", "description": "List of specific node IDs to search", "items": { "type": "string" } }, "searchSourceUrls": { "type": "boolean", "description": "Whether to search source URLs" } } } } } }, "responses": { "200": { "description": "Search results retrieved successfully" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Space not found" } } } }, "/api/v1/w/{wId}/search/tools/upload": { "post": { "summary": "Upload a tool file", "description": "Download and upload a file from a tool (MCP server) to Dust", "tags": [ "Search" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "serverViewId", "externalId" ], "properties": { "serverViewId": { "type": "string", "description": "The MCP server view ID" }, "externalId": { "type": "string", "description": "The external ID of the file in the tool" }, "conversationId": { "type": "string", "description": "Optional conversation ID for context" }, "serverName": { "type": "string", "description": "Optional name of the MCP server (e.g., \"Notion\", \"GitHub\")" }, "serverIcon": { "type": "string", "description": "Optional icon identifier for the MCP server" } } } } } }, "responses": { "200": { "description": "File uploaded successfully" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/api/v1/w/{wId}/skills": { "get": { "summary": "List skills", "description": "Retrieves the custom skills in the workspace. Active skills are returned by default.", "tags": [ "Skills" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "status", "required": false, "description": "Filter skills by status. Defaults to active.", "schema": { "type": "string", "enum": [ "active", "archived", "suggested" ] } } ], "responses": { "200": { "description": "Skills available in the workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Workspace not found." } } }, "post": { "summary": "Import skills from uploaded files", "description": "Imports skills from uploaded files or ZIP archives into the workspace.", "tags": [ "Skills" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Skill files or ZIP archives to import." }, "names": { "type": "array", "items": { "type": "string" }, "description": "Optional skill names to import from the uploaded files." }, "onConflict": { "type": "string", "enum": [ "error", "skip", "override" ], "description": "Conflict handling strategy. Defaults to error." } } } } } }, "responses": { "200": { "description": "Skills import result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } }, "updated": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "400": { "description": "Bad Request. Missing or invalid uploaded files." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Workspace not found." } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/apps/{aId}/runs/{runId}": { "get": { "summary": "Get an app run", "description": "Retrieve a run for an app in the space identified by {spaceId}.", "tags": [ "Apps" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "aId", "required": true, "description": "ID of the app", "schema": { "type": "string" } }, { "in": "path", "name": "runId", "required": true, "description": "ID of the run", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The run", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/Run" } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/apps/{aId}/runs": { "post": { "summary": "Create an app run", "description": "Create and execute a run for an app in the space specified by {spaceId}.", "tags": [ "Apps" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "aId", "required": true, "description": "Unique identifier of the app", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "specification_hash", "config", "inputs" ], "properties": { "specification_hash": { "type": "string", "description": "Hash of the app specification. Ensures API compatibility across app iterations." }, "config": { "type": "object", "description": "Configuration for the app run", "properties": { "model": { "type": "object", "description": "Model configuration", "properties": { "provider_id": { "type": "string", "description": "ID of the model provider" }, "model_id": { "type": "string", "description": "ID of the model" }, "use_cache": { "type": "boolean", "description": "Whether to use caching" }, "use_stream": { "type": "boolean", "description": "Whether to use streaming" } } } } }, "inputs": { "type": "array", "description": "Array of input objects for the app", "items": { "type": "object", "additionalProperties": true } }, "stream": { "type": "boolean", "description": "If true, the response will be streamed" }, "blocking": { "type": "boolean", "description": "If true, the request will block until the run is complete" }, "block_filter": { "type": "array", "items": { "type": "string" }, "description": "Array of block names to filter the response" } } } } } }, "responses": { "200": { "description": "App run created and executed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/Run" } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Workspace or app not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/apps": { "get": { "summary": "List apps", "description": "Get all apps in the space identified by {spaceId}.", "tags": [ "Apps" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Apps of the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the app" }, "sId": { "type": "string", "description": "Unique string identifier for the app" }, "name": { "type": "string", "description": "Name of the app" }, "description": { "type": "string", "description": "Description of the app" }, "savedSpecification": { "type": "string", "description": "Saved specification of the app" }, "savedConfig": { "type": "string", "description": "Saved configuration of the app" }, "savedRun": { "type": "string", "description": "Saved run identifier of the app" }, "dustAPIProjectId": { "type": "string", "description": "ID of the associated Dust API project" } } } } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Workspace not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_source_views/{dsvId}": { "get": { "tags": [ "DatasourceViews" ], "security": [ { "BearerAuth": [] } ], "summary": "Get a data source view", "parameters": [ { "name": "wId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "spaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dsvId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasourceView" } } } }, "404": { "description": "Data source view not found" } } }, "patch": { "tags": [ "DatasourceViews" ], "security": [ { "BearerAuth": [] } ], "summary": "Update a data source view", "parameters": [ { "name": "wId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "spaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dsvId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "type": "object", "properties": { "parentsIn": { "type": "array", "items": { "type": "string" } } }, "required": [ "parentsIn" ] }, { "type": "object", "properties": { "parentsToAdd": { "type": "array", "items": { "type": "string" } }, "parentsToRemove": { "type": "array", "items": { "type": "string" } } } } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasourceView" } } } }, "400": { "description": "Invalid request body" }, "403": { "description": "Unauthorized - Only admins or builders can administrate spaces" }, "404": { "description": "Data source view not found" }, "500": { "description": "Internal server error - The data source view cannot be updated" } } }, "delete": { "tags": [ "DatasourceViews" ], "security": [ { "BearerAuth": [] } ], "summary": "Delete a data source view", "parameters": [ { "name": "wId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "spaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dsvId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Data source view successfully deleted" }, "401": { "description": "Unauthorized - The data source view is in use and cannot be deleted" }, "403": { "description": "Forbidden - Only admins or builders can delete data source views" }, "404": { "description": "Data source view not found" } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_source_views/{dsvId}/search": { "get": { "summary": "Search the data source view", "description": "Search the data source view identified by {dsvId} in the workspace identified by {wId}.", "tags": [ "DatasourceViews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsvId", "required": true, "description": "ID of the data source view", "schema": { "type": "string" } }, { "in": "query", "name": "query", "required": true, "description": "The search query", "schema": { "type": "string" } }, { "in": "query", "name": "top_k", "required": true, "description": "The number of results to return", "schema": { "type": "number" } }, { "in": "query", "name": "full_text", "required": true, "description": "Whether to return the full document content", "schema": { "type": "boolean" } }, { "in": "query", "name": "target_document_tokens", "required": false, "description": "The number of tokens in the target document", "schema": { "type": "number" } }, { "in": "query", "name": "timestamp_gt", "required": false, "description": "The timestamp to filter by", "schema": { "type": "number" } }, { "in": "query", "name": "timestamp_lt", "required": false, "description": "The timestamp to filter by", "schema": { "type": "number" } }, { "in": "query", "name": "tags_in", "required": false, "description": "The tags to filter by", "schema": { "type": "string" } }, { "in": "query", "name": "tags_not", "required": false, "description": "The tags to filter by", "schema": { "type": "string" } }, { "in": "query", "name": "parents_in", "required": false, "description": "The parents to filter by", "schema": { "type": "string" } }, { "in": "query", "name": "parents_not", "required": false, "description": "The parents to filter by", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the document" }, "title": { "type": "string", "description": "Title of the document" }, "content": { "type": "string", "description": "Content of the document" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags of the document" }, "parents": { "type": "array", "items": { "type": "string" }, "description": "Parents of the document" }, "timestamp": { "type": "number", "description": "Timestamp of the document" }, "data": { "type": "object", "description": "Data of the document" }, "score": { "type": "number", "description": "Score of the document" } } } } } } } } }, "400": { "description": "Invalid request error" } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_source_views": { "get": { "summary": "List Data Source Views", "description": "Retrieves a list of data source views for the specified space", "tags": [ "DatasourceViews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of data source views in the space", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataSourceViews": { "type": "array", "items": { "$ref": "#/components/schemas/DatasourceView" } } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Workspace not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/check_upsert_queue": { "get": { "summary": "Check the upsert queue status for a data source", "description": "Returns the number of running document upsert workflows for this data source. This endpoint is only accessible with system API keys (e.g., from connectors).", "tags": [ "Datasources" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Status of the upsert queue", "content": { "application/json": { "schema": { "type": "object", "properties": { "running_count": { "type": "number", "description": "Number of currently running upsert workflows" } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. Only system keys can access this endpoint." }, "404": { "description": "Data source not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/documents/{documentId}": { "get": { "summary": "Retrieve a document from a data source", "description": "Retrieve a document from a data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "path", "name": "documentId", "required": true, "description": "ID of the document", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "The document", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Data source or document not found." }, "500": { "description": "Internal Server Error." } } }, "post": { "summary": "Upsert a document in a data source", "description": "Upsert a document in a data source in the workspace identified by {wId}.", "tags": [ "Datasources" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "path", "name": "documentId", "required": true, "description": "ID of the document", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the document to upsert." }, "mime_type": { "type": "string", "description": "The MIME type of the document to upsert." }, "text": { "type": "string", "description": "The text content of the document to upsert." }, "section": { "$ref": "#/components/schemas/Section" }, "source_url": { "type": "string", "description": "The source URL for the document to upsert." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags to associate with the document." }, "timestamp": { "type": "number", "description": "Unix timestamp (in milliseconds) for the document (e.g. 1736365559000)." }, "light_document_output": { "type": "boolean", "description": "If true, a lightweight version of the document will be returned in the response (excluding the text, chunks and vectors). Defaults to false." }, "async": { "type": "boolean", "description": "If true, the upsert operation will be performed asynchronously." }, "upsert_context": { "type": "object", "description": "Additional context for the upsert operation." } } } } } }, "responses": { "200": { "description": "The document", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "data_source": { "$ref": "#/components/schemas/Datasource" } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. The data source is managed." }, "404": { "description": "Data source or document not found." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Internal Server Error." } } }, "delete": { "summary": "Delete a document from a data source", "description": "Delete a document from a data source in the workspace identified by {wId}.", "tags": [ "Datasources" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "path", "name": "documentId", "required": true, "description": "ID of the document", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "The document", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "properties": { "document_id": { "type": "string" } } } } } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. The data source is managed." }, "404": { "description": "Data source or document not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/documents/{documentId}/parents": { "post": { "summary": "Update the parents of a document", "description": "Update the parents of a document in the data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "path", "name": "documentId", "required": true, "description": "ID of the document", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_id": { "type": "string", "description": "Direct parent ID of the document" }, "parents": { "type": "array", "items": { "type": "string" }, "description": "Document and ancestor ids, with the following convention: parents[0] === documentId, parents[1] === parentId, and then ancestors ids in order" } } } } } }, "responses": { "200": { "description": "The parents were updated" }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Data source or workspace not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/documents": { "get": { "summary": "Get documents", "description": "Get documents in the data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "query", "name": "document_ids", "description": "The IDs of the documents to fetch (optional)", "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "limit", "description": "Limit the number of documents returned", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "description": "Offset the returned documents", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "total": { "type": "integer" } } } } } }, "404": { "description": "The data source was not found" } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/search": { "get": { "summary": "Search the data source", "description": "Search the data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "query", "name": "query", "required": true, "description": "The search query", "schema": { "type": "string" } }, { "in": "query", "name": "top_k", "required": true, "description": "The number of results to return", "schema": { "type": "number" } }, { "in": "query", "name": "full_text", "required": true, "description": "Whether to return the full document content", "schema": { "type": "boolean" } }, { "in": "query", "name": "target_document_tokens", "required": false, "description": "The number of tokens in the target document", "schema": { "type": "number" } }, { "in": "query", "name": "timestamp_gt", "required": false, "description": "The timestamp to filter by", "schema": { "type": "number" } }, { "in": "query", "name": "timestamp_lt", "required": false, "description": "The timestamp to filter by", "schema": { "type": "number" } }, { "in": "query", "name": "tags_in", "required": false, "description": "The tags to filter by", "schema": { "type": "string" } }, { "in": "query", "name": "tags_not", "required": false, "description": "The tags to filter by", "schema": { "type": "string" } }, { "in": "query", "name": "parents_in", "required": false, "description": "The parents to filter by", "schema": { "type": "string" } }, { "in": "query", "name": "parents_not", "required": false, "description": "The parents to filter by", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the document" }, "title": { "type": "string", "description": "Title of the document" }, "content": { "type": "string", "description": "Content of the document" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags of the document" }, "parents": { "type": "array", "items": { "type": "string" }, "description": "Parents of the document" }, "timestamp": { "type": "number", "description": "Timestamp of the document" }, "data": { "type": "object", "description": "Data of the document" }, "score": { "type": "number", "description": "Score of the document" } } } } } } } } }, "400": { "description": "Invalid request error" } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/tables/{tId}": { "get": { "summary": "Get a table", "description": "Get a table in the data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "path", "name": "tId", "required": true, "description": "ID of the table", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The table", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Table" } } } }, "404": { "description": "The table was not found" } } }, "delete": { "summary": "Delete a table", "description": "Delete a table in the data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "path", "name": "tId", "required": true, "description": "ID of the table", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The table was deleted" }, "404": { "description": "The table was not found" } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/tables/{tId}/rows/{rId}": { "get": { "summary": "Get a row", "description": "Get a row in the table identified by {tId} in the data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "path", "name": "tId", "required": true, "description": "ID of the table", "schema": { "type": "string" } }, { "in": "path", "name": "rId", "required": true, "description": "ID of the row", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The row", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Datasource" } } } }, "404": { "description": "The row was not found" } } }, "delete": { "summary": "Delete a row", "description": "Delete a row in the table identified by {tId} in the data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "path", "name": "tId", "required": true, "description": "ID of the table", "schema": { "type": "string" } }, { "in": "path", "name": "rId", "required": true, "description": "ID of the row", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The row was deleted" }, "404": { "description": "The row was not found" } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/tables/{tId}/rows": { "get": { "summary": "List rows", "description": "List rows in the table identified by {tId} in the data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "path", "name": "tId", "required": true, "description": "ID of the table", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "description": "Limit the number of rows returned", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "description": "Offset the returned rows", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The rows", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Datasource" } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Table, data source or workspace not found." }, "500": { "description": "Internal Server Error." } } }, "post": { "summary": "Upsert rows", "description": "Upsert rows in the table identified by {tId} in the data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } }, { "in": "path", "name": "tId", "required": true, "description": "ID of the table", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "row_id": { "type": "string", "description": "Unique identifier for the row" }, "value": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "datetime" ] }, "epoch": { "type": "number" } } } ] } } } } }, "truncate": { "type": "boolean", "description": "Whether to truncate existing rows" } } } } } }, "responses": { "200": { "description": "The table", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Datasource" } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Data source or workspace not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_sources/{dsId}/tables": { "get": { "summary": "Get tables", "description": "Get tables in the data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The tables", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Table" } } } } }, "400": { "description": "Invalid request" } } }, "post": { "summary": "Upsert a table", "description": "Upsert a table in the data source identified by {dsId} in the workspace identified by {wId}.", "tags": [ "Datasources" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsId", "required": true, "description": "ID of the data source", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the table" }, "title": { "type": "string", "description": "Title of the table" }, "table_id": { "type": "string", "description": "Unique identifier for the table" }, "description": { "type": "string", "description": "Description of the table" }, "timestamp": { "type": "number", "description": "Unix timestamp (in milliseconds) for the table (e.g. 1736365559000)." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags associated with the table" }, "mime_type": { "type": "string", "description": "Reserved for internal use, should not be set. Mime type of the table" } } } } } }, "responses": { "200": { "description": "The table", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Table" } } } }, "400": { "description": "Invalid request" } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/data_sources": { "get": { "summary": "Get data sources", "description": "Get data sources in the workspace identified by {wId}.", "tags": [ "Datasources" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "The data sources", "content": { "application/json": { "schema": { "type": "object", "properties": { "data_sources": { "type": "array", "items": { "$ref": "#/components/schemas/Datasource" } } } } } } }, "404": { "description": "The workspace was not found" } } } }, "/api/v1/w/{wId}/spaces/{spaceId}/mcp_server_views": { "get": { "summary": "List available MCP server views.", "description": "Retrieves a list of enabled MCP server views (aka tools) for a specific space of the authenticated workspace.", "tags": [ "Tools" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } } ], "responses": { "200": { "description": "MCP server views of the space", "content": { "application/json": { "schema": { "type": "object", "properties": { "spaces": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerView" } } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Workspace not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/spaces": { "get": { "summary": "List available spaces.", "description": "Retrieves a list of accessible spaces for the authenticated workspace.", "tags": [ "Spaces" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Spaces of the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "spaces": { "type": "array", "items": { "$ref": "#/components/schemas/Space" } } } } } } }, "400": { "description": "Bad Request. Missing or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "404": { "description": "Workspace not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/w/{wId}/triggers/hooks/{webhookSourceId}": { "post": { "summary": "Receive external webhook to trigger flows", "description": "Skeleton endpoint that verifies workspace and webhook source and logs receipt.", "tags": [ "Triggers" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Workspace ID", "schema": { "type": "string" } }, { "in": "path", "name": "webhookSourceId", "required": true, "description": "Webhook source ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Webhook received" }, "400": { "description": "Invalid request" }, "404": { "description": "Workspace or webhook source not found" } } } }, "/api/v1/w/{wId}/workspace-usage": { "get": { "summary": "Get workspace usage data", "deprecated": true, "description": "Deprecated: this endpoint will be removed after 2026-07-01.\nUse GET /api/v1/w/{wId}/analytics/export instead.\n\nGet usage data for the workspace identified by {wId} in CSV or JSON format.\n", "tags": [ "Workspace" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "start", "required": true, "description": "The start date in YYYY-MM or YYYY-MM-DD format", "schema": { "type": "string" } }, { "in": "query", "name": "end", "required": false, "description": "The end date in YYYY-MM or YYYY-MM-DD format (required when mode is 'range')", "schema": { "type": "string" } }, { "in": "query", "name": "mode", "required": true, "description": "The mode of date range selection", "schema": { "type": "string", "enum": [ "month", "range" ] } }, { "in": "query", "name": "format", "required": false, "description": "The output format of the data (defaults to 'csv')", "schema": { "type": "string", "enum": [ "csv", "json" ] } }, { "in": "query", "name": "table", "required": true, "description": "The name of the usage table to retrieve:\n- \"users\": The list of users categorized by their activity level.\n- \"assistant_messages\": The list of messages sent by users including the mentioned agents.\n- \"builders\": The list of builders categorized by their activity level.\n- \"assistants\": The list of workspace agents and their corresponding usage.\n- \"feedback\": The list of feedback given by users on the agent messages.\n- \"all\": A concatenation of all the above tables.\n", "schema": { "type": "string", "enum": [ "users", "assistant_messages", "builders", "assistants", "feedback", "all" ] } }, { "in": "query", "name": "includeInactive", "required": false, "description": "Include users and assistants with zero messages in the export (defaults to false)", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The usage data in CSV or JSON format, or a ZIP of multiple CSVs if table is equal to \"all\"", "content": { "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object" } }, "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request query" }, "403": { "description": "The workspace does not have access to the usage data API" }, "404": { "description": "The workspace was not found" } } } }, "/api/w/{wId}/assistant/agent_configurations": { "get": { "summary": "List agent configurations", "description": "Returns all agent configurations in the workspace.", "tags": [ "Private Agents" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "view", "required": false, "description": "Filter agents by view", "schema": { "type": "string", "enum": [ "all", "list", "favorites", "published", "admin_internal", "global", "workspace" ] } }, { "in": "query", "name": "limit", "required": false, "description": "Maximum number of results to return", "schema": { "type": "integer" } }, { "in": "query", "name": "withUsage", "required": false, "description": "Include usage statistics", "schema": { "type": "string", "enum": [ "true" ] } }, { "in": "query", "name": "withAuthors", "required": false, "description": "Include recent authors", "schema": { "type": "string", "enum": [ "true" ] } }, { "in": "query", "name": "withFeedbacks", "required": false, "description": "Include feedback counts", "schema": { "type": "string", "enum": [ "true" ] } }, { "in": "query", "name": "withEditors", "required": false, "description": "Include editors list", "schema": { "type": "string", "enum": [ "true" ] } }, { "in": "query", "name": "sort", "required": false, "description": "Sort order", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentConfigurations": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateLightAgentConfiguration" } } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Create an agent configuration", "description": "Creates a new agent configuration in the workspace.", "tags": [ "Private Agents" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assistant" ], "properties": { "assistant": { "type": "object", "description": "Agent configuration to create" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentConfiguration": { "$ref": "#/components/schemas/PrivateLightAgentConfiguration" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/cancel": { "post": { "summary": "Cancel message generation", "description": "Cancels the generation of messages in a conversation.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "messageIds" ], "properties": { "action": { "type": "string", "enum": [ "cancel", "gracefully_stop", "interrupt" ] }, "messageIds": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/compactions": { "post": { "summary": "Compact a conversation", "description": "Trigger compaction of a conversation, summarizing older messages into a compaction message. Requires a model to use for summary generation.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "object", "required": [ "providerId", "modelId" ], "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Compaction started", "content": { "application/json": { "schema": { "type": "object", "properties": { "compactionMessage": { "$ref": "#/components/schemas/PrivateCompactionMessage" } } } } } }, "400": { "description": "Invalid request body" }, "404": { "description": "Conversation not found" }, "409": { "description": "Conflict — compaction or agent message is already running" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/content_fragment": { "post": { "summary": "Create a content fragment", "description": "Post a new content fragment to an existing conversation.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "content", "contentType", "context" ], "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "contentType": { "type": "string", "description": "MIME type of the content" }, "url": { "type": "string", "nullable": true }, "context": { "type": "object", "properties": { "profilePictureUrl": { "type": "string", "nullable": true } } }, "fileId": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Successfully created content fragment", "content": { "application/json": { "schema": { "type": "object", "properties": { "contentFragment": { "$ref": "#/components/schemas/PrivateContentFragment" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/events": { "get": { "summary": "Stream conversation events", "description": "Stream real-time conversation events using Server-Sent Events (SSE). This endpoint is redirected to /api/sse/ for SSE traffic routing.", "tags": [ "Private Events" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "SSE event stream. Each event is sent as `data: {json}\\n\\n`.\nEvents are discriminated by the `type` field.\n", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/PrivateConversationEvent" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/feedbacks": { "get": { "summary": "Get conversation feedbacks", "description": "Retrieve all feedbacks for a conversation submitted by the authenticated user.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved feedbacks", "content": { "application/json": { "schema": { "type": "object", "properties": { "feedbacks": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateFeedback" } } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}": { "get": { "summary": "Get a conversation", "description": "Retrieve a specific conversation by its ID.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved conversation", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/PrivateConversation" } } } } } }, "401": { "description": "Unauthorized" } } }, "delete": { "summary": "Delete or leave a conversation", "description": "Delete a conversation or leave it if it is shared.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully deleted or left conversation" }, "401": { "description": "Unauthorized" } } }, "patch": { "summary": "Update a conversation", "description": "Update a conversation's title, mark it as read, move it to a different space, or control URL access mode.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" } } }, { "type": "object", "required": [ "read" ], "properties": { "read": { "type": "boolean" } } }, { "type": "object", "required": [ "spaceId" ], "properties": { "spaceId": { "type": "string" } } }, { "type": "object", "required": [ "accessMode" ], "properties": { "accessMode": { "type": "string", "enum": [ "participants_only", "workspace_members" ] } } } ] } } } }, "responses": { "200": { "description": "Successfully updated conversation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/messages/{mId}/actions/{aId}": { "get": { "summary": "Get a single action", "description": "Retrieve a single action by its ID within an agent message, along with the message status.", "tags": [ "Private Messages" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "path", "name": "mId", "required": true, "description": "ID of the message", "schema": { "type": "string" } }, { "in": "path", "name": "aId", "required": true, "description": "ID of the action", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved the action", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/PrivateAgentMCPAction" }, "messageStatus": { "type": "string", "enum": [ "created", "succeeded", "failed", "cancelled", "gracefully_stopped" ] } } } } } }, "400": { "description": "Invalid request (missing parameters or message is not an agent message)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Conversation, message, or action not found" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/messages/{mId}/edit": { "post": { "summary": "Edit a message", "description": "Edit the content and mentions of an existing user message in a conversation.", "tags": [ "Private Messages" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "path", "name": "mId", "required": true, "description": "ID of the message", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content", "mentions" ], "properties": { "content": { "type": "string" }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateMention" } } } } } } }, "responses": { "200": { "description": "Successfully edited message", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/PrivateUserMessage" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/messages/{mId}/events": { "get": { "summary": "Stream message events", "description": "Stream real-time events for a specific agent message using Server-Sent Events (SSE). Only available for agent messages. This endpoint is redirected to /api/sse/ for SSE traffic routing.", "tags": [ "Private Events" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "path", "name": "mId", "required": true, "description": "ID of the message", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "SSE event stream. Each event is sent as `data: {json}\\n\\n`.\nEvents are discriminated by the `type` field. Each event payload also includes a `step` integer.\n", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/PrivateAgentMessageEvent" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/messages/{mId}/feedbacks": { "post": { "summary": "Submit message feedback", "description": "Create or update feedback (thumbs up/down) for a specific agent message.", "tags": [ "Private Messages" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "path", "name": "mId", "required": true, "description": "ID of the message", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "thumbDirection" ], "properties": { "thumbDirection": { "type": "string", "enum": [ "up", "down" ] }, "feedbackContent": { "type": "string", "nullable": true }, "isConversationShared": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Successfully submitted feedback", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized" } } }, "delete": { "summary": "Delete message feedback", "description": "Remove the authenticated user's feedback for a specific agent message.", "tags": [ "Private Messages" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "path", "name": "mId", "required": true, "description": "ID of the message", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully deleted feedback", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/messages/{mId}": { "get": { "summary": "Get a message", "description": "Retrieve a specific message by its ID within a conversation.", "tags": [ "Private Messages" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "path", "name": "mId", "required": true, "description": "ID of the message", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved message", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "oneOf": [ { "$ref": "#/components/schemas/PrivateUserMessage" }, { "$ref": "#/components/schemas/PrivateAgentMessage" }, { "$ref": "#/components/schemas/PrivateContentFragment" } ] } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Message or conversation not found" } } }, "delete": { "summary": "Delete a message", "description": "Soft-delete a user or agent message from a conversation.", "tags": [ "Private Messages" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "path", "name": "mId", "required": true, "description": "ID of the message", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully deleted message", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Message or conversation not found" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/messages/{mId}/retry": { "post": { "summary": "Retry an agent message", "description": "Retry generating an agent message response, optionally retrying only blocked actions.", "tags": [ "Private Messages" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "path", "name": "mId", "required": true, "description": "ID of the message", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully retried message", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/PrivateAgentMessage" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/messages": { "get": { "summary": "List messages in a conversation", "description": "Retrieve a paginated list of messages for a specific conversation.", "tags": [ "Private Messages" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/PrivateUserMessage" }, { "$ref": "#/components/schemas/PrivateLightAgentMessage" }, { "$ref": "#/components/schemas/PrivateContentFragment" } ] } }, "hasMore": { "type": "boolean" }, "lastValue": { "type": "integer", "nullable": true } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Post a message to a conversation", "description": "Post a new user message to an existing conversation, triggering agent responses.", "tags": [ "Private Messages" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content", "context", "mentions" ], "properties": { "content": { "type": "string" }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateMention" } }, "context": { "type": "object", "properties": { "timezone": { "type": "string" }, "profilePictureUrl": { "type": "string", "nullable": true }, "origin": { "type": "string", "nullable": true }, "clientSideMCPServerIds": { "type": "array", "items": { "type": "string" } }, "selectedMCPServerViewIds": { "type": "array", "items": { "type": "string" } } } }, "skipToolsValidation": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Successfully posted message", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/PrivateUserMessage" }, "contentFragments": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateContentFragment" } }, "agentMessages": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateAgentMessage" } } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/participants": { "get": { "summary": "Get conversation participants", "description": "Returns the participants of a specific conversation.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "participants": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "configurationId": { "type": "string" }, "configurationName": { "type": "string" } } } }, "users": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "fullName": { "type": "string", "nullable": true }, "pictureUrl": { "type": "string", "nullable": true } } } } } } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Add a participant to a conversation", "description": "Adds the authenticated user as a participant to a specific conversation.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Successfully added participant" }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/wakeups/{wuId}": { "delete": { "summary": "Cancel a wake-up", "description": "Cancel a scheduled wake-up. Only the wake-up owner or a workspace admin can cancel.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } }, { "in": "path", "name": "wuId", "required": true, "description": "sId of the wake-up to cancel", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully cancelled (or already terminal)", "content": { "application/json": { "schema": { "type": "object", "properties": { "wakeUp": { "$ref": "#/components/schemas/PrivateWakeUp" } } } } } }, "403": { "description": "Caller is not the wake-up owner or a workspace admin" }, "404": { "description": "Wake-up not found in this conversation" } } } }, "/api/w/{wId}/assistant/conversations/{cId}/wakeups": { "get": { "summary": "List wake-ups for a conversation", "description": "Retrieve all wake-ups scheduled in a conversation (any status).", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "cId", "required": true, "description": "ID of the conversation", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved wake-ups", "content": { "application/json": { "schema": { "type": "object", "properties": { "wakeUps": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateWakeUp" } } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/conversations": { "get": { "summary": "List conversations", "description": "Retrieve a paginated list of conversations for the authenticated user in the workspace.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved conversations", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateConversation" } }, "hasMore": { "type": "boolean" }, "lastValue": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Create a conversation", "description": "Create a new conversation, optionally with an initial user message and content fragments.", "tags": [ "Private Conversations" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "unlisted", "deleted", "test" ] }, "spaceId": { "type": "string", "nullable": true }, "message": { "type": "object", "properties": { "content": { "type": "string" }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateMention" } }, "context": { "type": "object", "properties": { "timezone": { "type": "string" }, "profilePictureUrl": { "type": "string", "nullable": true }, "origin": { "type": "string", "nullable": true }, "clientSideMCPServerIds": { "type": "array", "items": { "type": "string" } }, "selectedMCPServerViewIds": { "type": "array", "items": { "type": "string" } } } } } }, "contentFragments": { "type": "array", "items": { "type": "object" } }, "metadata": { "type": "object", "nullable": true }, "skipToolsValidation": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Successfully created conversation", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/PrivateFullConversation" }, "message": { "$ref": "#/components/schemas/PrivateUserMessage" }, "contentFragments": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateContentFragment" } } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/assistant/mentions/suggestions": { "get": { "summary": "Get mention suggestions", "description": "Returns mention suggestions for the workspace.", "tags": [ "Private Mentions" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "query", "required": false, "description": "Search query to filter suggestions", "schema": { "type": "string" } }, { "in": "query", "name": "select", "required": false, "description": "Filter by type (agents, users, or both)", "schema": { "type": "string", "enum": [ "agents", "users" ] } }, { "in": "query", "name": "current", "required": false, "description": "Whether to include only current mentions", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "in": "query", "name": "spaceId", "required": false, "description": "Filter suggestions by space", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateMentionSuggestion" } } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/extension/config": { "get": { "summary": "Get extension configuration", "description": "Returns the extension configuration for the workspace, including blacklisted domains.", "tags": [ "Private Extension" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Extension configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateExtensionConfig" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/feature-flags": { "get": { "summary": "Get workspace feature flags", "description": "Returns the list of enabled feature flags for the workspace.", "tags": [ "Private Workspace" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of feature flags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateFeatureFlags" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/files/{fileId}": { "get": { "summary": "Get or download a file", "description": "View or download a file. Use query parameters `version` (original, processed, public) and `action` (view, download).", "tags": [ "Private Files" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "fileId", "required": true, "description": "ID of the file", "schema": { "type": "string" } }, { "in": "query", "name": "version", "required": false, "description": "File version to retrieve", "schema": { "type": "string", "enum": [ "original", "processed", "public" ] } }, { "in": "query", "name": "action", "required": false, "description": "Action to perform", "schema": { "type": "string", "enum": [ "view", "download" ] } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "File content or redirect to download URL", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "Redirect to signed download URL" }, "404": { "description": "File not found" } } }, "post": { "summary": "Upload file content", "description": "Process and store the uploaded file content.", "tags": [ "Private Files" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "fileId", "required": true, "description": "ID of the file", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "File processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "$ref": "#/components/schemas/PrivateFileWithUploadUrl" } } } } } }, "400": { "description": "Invalid file content (e.g. a CSV with an unsupported encoding)" }, "403": { "description": "Permission denied" }, "404": { "description": "File not found" } } }, "delete": { "summary": "Delete a file", "description": "Delete a file from the workspace.", "tags": [ "Private Files" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "fileId", "required": true, "description": "ID of the file", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "File deleted" }, "403": { "description": "Permission denied" }, "404": { "description": "File not found" } } } }, "/api/w/{wId}/files": { "post": { "summary": "Create a file upload", "description": "Creates a file record and returns a pre-signed upload URL. The file content should then be uploaded to the returned URL.", "tags": [ "Private Files" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contentType", "fileName", "fileSize", "useCase" ], "properties": { "contentType": { "type": "string" }, "fileName": { "type": "string" }, "fileSize": { "type": "number" }, "useCase": { "type": "string", "enum": [ "conversation", "folders_document", "avatar", "upsert_document", "upsert_table", "project_context", "skill_attachment", "workspace_branding" ] }, "useCaseMetadata": { "type": "object" } } } } } }, "responses": { "200": { "description": "File record created with upload URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "$ref": "#/components/schemas/PrivateFileWithUploadUrl" } } } } } }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/w/{wId}/spaces/{spaceId}/data_source_views/{dsvId}": { "get": { "summary": "Get a data source view", "description": "Returns the details of a specific data source view.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsvId", "required": true, "description": "ID of the data source view", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataSourceView": { "$ref": "#/components/schemas/PrivateDataSourceView" }, "connector": { "type": "object", "nullable": true, "description": "Connector details if the data source is managed" } } } } } }, "401": { "description": "Unauthorized" } } }, "patch": { "summary": "Update a data source view", "description": "Updates a specific data source view.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsvId", "required": true, "description": "ID of the data source view", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parentsIn": { "type": "array", "nullable": true, "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataSourceView": { "$ref": "#/components/schemas/PrivateDataSourceView" }, "connector": { "type": "object", "nullable": true } } } } } }, "401": { "description": "Unauthorized" } } }, "delete": { "summary": "Delete a data source view", "description": "Deletes a specific data source view.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "path", "name": "dsvId", "required": true, "description": "ID of the data source view", "schema": { "type": "string" } }, { "in": "query", "name": "force", "required": false, "description": "Force deletion even if the view is in use", "schema": { "type": "string", "enum": [ "true" ] } } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "Successfully deleted data source view" }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/spaces/{spaceId}/data_source_views": { "get": { "summary": "List data source views", "description": "Returns all data source views in a specific space.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "query", "name": "category", "required": false, "description": "Filter by data source view category", "schema": { "type": "string", "enum": [ "managed", "folder", "website", "apps" ] } }, { "in": "query", "name": "withDetails", "required": false, "description": "Include usage and connector details (requires category)", "schema": { "type": "string", "enum": [ "true" ] } }, { "in": "query", "name": "includeEditedBy", "required": false, "description": "Include editedByUser information", "schema": { "type": "string", "enum": [ "true" ] } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataSourceViews": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateDataSourceView" } } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Create a data source view", "description": "Creates a new data source view in a specific space.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dataSourceId" ], "properties": { "dataSourceId": { "type": "string" }, "parentsIn": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Successfully created data source view", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataSourceView": { "$ref": "#/components/schemas/PrivateDataSourceView" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/spaces/{spaceId}": { "get": { "summary": "Get a space", "description": "Returns the details of a specific space including categories, members, and permissions.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "query", "name": "includeAllMembers", "required": false, "description": "Include all members (including inactive)", "schema": { "type": "string", "enum": [ "true" ] } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "space": { "allOf": [ { "$ref": "#/components/schemas/PrivateSpace" }, { "type": "object", "properties": { "categories": { "type": "object", "additionalProperties": { "type": "object", "properties": { "count": { "type": "integer" }, "usage": { "type": "object", "properties": { "count": { "type": "integer" }, "agents": { "type": "array", "items": { "type": "object" } } } } } } }, "canWrite": { "type": "boolean" }, "canRead": { "type": "boolean" }, "isMember": { "type": "boolean" }, "isEditor": { "type": "boolean" }, "members": { "type": "array", "items": { "type": "object" } }, "description": { "type": "string", "nullable": true }, "archivedAt": { "type": "integer", "nullable": true }, "todoGenerationEnabled": { "type": "boolean", "description": "Whether automatic todo suggestions from project activity are enabled." }, "lastTodoAnalysisAt": { "type": "integer", "nullable": true, "description": "Unix timestamp (ms) of the last automatic todo suggestion scan, if any." }, "pinnedFramePath": { "type": "string", "nullable": true, "description": "Scoped path to the frame file pinned as the Pod banner." } } } ] } } } } } }, "401": { "description": "Unauthorized" } } }, "patch": { "summary": "Update a space", "description": "Updates the properties of a specific space.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "content": { "type": "array", "items": { "type": "object", "properties": { "dataSourceId": { "type": "string" }, "parentsIn": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "space": { "$ref": "#/components/schemas/PrivateSpace" } } } } } }, "401": { "description": "Unauthorized" } } }, "delete": { "summary": "Delete a space", "description": "Deletes a specific space from the workspace.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the space", "schema": { "type": "string" } }, { "in": "query", "name": "force", "required": false, "description": "Force deletion even if space is in use", "schema": { "type": "string", "enum": [ "true" ] } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "space": { "$ref": "#/components/schemas/PrivateSpace" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/spaces/{spaceId}/project_notification_preferences": { "get": { "summary": "Get project notification preference", "description": "Returns the current user's notification preference for a project space.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the project space", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "userProjectNotificationPreference": { "type": "object", "nullable": true, "properties": { "sId": { "type": "string" }, "spaceId": { "type": "string" }, "userId": { "type": "string" }, "preference": { "type": "string", "enum": [ "all_messages", "only_mentions", "never" ] } } } } } } } }, "400": { "description": "Bad request (space is not a project)" }, "401": { "description": "Unauthorized" } } }, "patch": { "summary": "Set project notification preference", "description": "Sets the current user's notification preference for a project space.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "spaceId", "required": true, "description": "ID of the project space", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "preference" ], "properties": { "preference": { "type": "string", "enum": [ "all_messages", "only_mentions", "never" ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "userProjectNotificationPreference": { "type": "object", "nullable": true, "properties": { "sId": { "type": "string" }, "spaceId": { "type": "string" }, "userId": { "type": "string" }, "preference": { "type": "string", "enum": [ "all_messages", "only_mentions", "never" ] } } } } } } } }, "400": { "description": "Bad request (space is not a project or invalid body)" }, "401": { "description": "Unauthorized" } } } }, "/api/w/{wId}/spaces": { "get": { "summary": "List spaces", "description": "Returns all spaces in the workspace.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "role", "required": false, "description": "Filter by role (e.g. admin to list all workspace spaces)", "schema": { "type": "string" } }, { "in": "query", "name": "kind", "required": false, "description": "Filter by space kind (e.g. system)", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "spaces": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/PrivateSpace" }, { "$ref": "#/components/schemas/PrivateProject" } ] } } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Create a space", "description": "Creates a new space in the workspace.", "tags": [ "Private Spaces" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "isRestricted", "name", "spaceKind", "managementMode" ], "properties": { "isRestricted": { "type": "boolean" }, "name": { "type": "string" }, "spaceKind": { "type": "string", "enum": [ "regular", "project" ] }, "managementMode": { "type": "string", "enum": [ "manual", "group" ] }, "memberIds": { "type": "array", "items": { "type": "string" }, "description": "Required when managementMode is manual" }, "groupIds": { "type": "array", "items": { "type": "string" }, "description": "Required when managementMode is group" } } } } } }, "responses": { "201": { "description": "Successfully created space", "content": { "application/json": { "schema": { "type": "object", "properties": { "space": { "$ref": "#/components/schemas/PrivateSpace" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/workos/login": { "get": { "summary": "Initiate WorkOS login", "description": "Redirects to WorkOS AuthKit for authentication. Supports PKCE flow for extensions.", "tags": [ "Private Authentication" ], "security": [], "parameters": [ { "in": "query", "name": "redirect_uri", "required": false, "description": "Custom redirect URI (used by extensions for PKCE flow)", "schema": { "type": "string" } }, { "in": "query", "name": "code_challenge", "required": false, "description": "PKCE code challenge", "schema": { "type": "string" } }, { "in": "query", "name": "code_challenge_method", "required": false, "description": "PKCE code challenge method (S256)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Login page HTML" }, "302": { "description": "Redirect to WorkOS authorization URL" }, "400": { "description": "Bad request" } } } }, "/api/workos/authenticate": { "post": { "summary": "Exchange code or refresh token", "description": "Exchanges an authorization code or refresh token for access tokens via WorkOS.", "tags": [ "Private Authentication" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "grant_type": { "type": "string", "enum": [ "refresh_token" ] }, "refresh_token": { "type": "string" }, "code_verifier": { "type": "string" } } } } } }, "responses": { "200": { "description": "Authentication result with tokens", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "user": { "type": "object" }, "expiresIn": { "type": "integer", "description": "Token expiry in seconds" }, "expirationDate": { "type": "integer", "description": "Token expiry date in milliseconds" } } } } } }, "400": { "description": "Invalid request" } } } }, "/api/workos/revoke-session": { "post": { "summary": "Revoke a session", "description": "Revokes a WorkOS session by session ID. Used by the Chrome extension for logout.", "tags": [ "Private Authentication" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Session revoked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid session_id" } } } } }, "components": { "schemas": { "PrivateUser": { "type": "object", "description": "Authenticated user with their workspaces and subscriber hash.", "required": [ "sId", "id", "createdAt", "username", "email", "firstName", "fullName", "workspaces" ], "properties": { "sId": { "type": "string", "description": "Unique string identifier for the user" }, "id": { "type": "integer", "description": "Numeric model identifier" }, "createdAt": { "type": "integer", "description": "Unix timestamp of user creation" }, "provider": { "type": "string", "nullable": true, "enum": [ "auth0", "github", "google", "okta", "samlp", "waad" ], "description": "Authentication provider" }, "username": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string", "nullable": true }, "fullName": { "type": "string" }, "image": { "type": "string", "nullable": true, "description": "URL of the user's profile image" }, "lastLoginAt": { "type": "integer", "nullable": true }, "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateWorkspace" } }, "selectedWorkspace": { "type": "string", "description": "sId of the currently selected workspace" }, "origin": { "type": "string", "description": "How the user joined (e.g. invitation, provisioned)" }, "subscriberHash": { "type": "string", "nullable": true, "description": "Hash used for Intercom identity verification" } } }, "PrivateWorkspace": { "type": "object", "description": "Workspace as returned by the private API, includes SSO and provider settings.", "required": [ "id", "sId", "name", "role", "regionalModelsOnly" ], "properties": { "id": { "type": "integer" }, "sId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "builder", "user", "none" ] }, "segmentation": { "type": "string", "nullable": true }, "whiteListedProviders": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Allowed model provider IDs" }, "defaultEmbeddingProvider": { "type": "string", "nullable": true }, "ssoEnforced": { "type": "boolean" }, "regionalModelsOnly": { "type": "boolean", "description": "When true, only models whose regionalAvailability includes the workspace's region are usable." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true } } }, "PrivateConversation": { "type": "object", "description": "Conversation without content, used in list responses.", "required": [ "id", "created", "updated", "sId", "depth" ], "properties": { "id": { "type": "integer" }, "created": { "type": "integer", "description": "Unix timestamp of creation" }, "updated": { "type": "integer", "description": "Unix timestamp of last update" }, "unread": { "type": "boolean" }, "lastReadMs": { "type": "integer", "nullable": true }, "actionRequired": { "type": "boolean", "description": "Whether the conversation requires user action" }, "hasError": { "type": "boolean" }, "sId": { "type": "string" }, "title": { "type": "string", "nullable": true }, "spaceId": { "type": "string", "nullable": true, "description": "ID of the space the conversation belongs to (for project conversations)" }, "triggerId": { "type": "string", "nullable": true }, "depth": { "type": "integer", "description": "Conversation depth (for agent handover chains)" }, "metadata": { "type": "object", "additionalProperties": true }, "requestedSpaceIds": { "type": "array", "items": { "type": "string" } }, "forkingData": { "$ref": "#/components/schemas/PrivateConversationForkingData" } } }, "PrivateConversationForkUser": { "type": "object", "properties": { "sId": { "type": "string" }, "id": { "type": "integer" }, "createdAt": { "type": "integer" }, "provider": { "type": "string", "nullable": true, "enum": [ "auth0", "github", "google", "okta", "samlp", "waad" ] }, "username": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string", "nullable": true }, "fullName": { "type": "string" }, "image": { "type": "string", "nullable": true }, "lastLoginAt": { "type": "integer", "nullable": true } } }, "PrivateConversationForkedFrom": { "type": "object", "required": [ "parentConversationId", "parentConversationTitle", "sourceMessageId", "branchedAt", "user", "fileCopyStatus" ], "properties": { "parentConversationId": { "type": "string" }, "parentConversationTitle": { "type": "string", "nullable": true }, "sourceMessageId": { "type": "string" }, "branchedAt": { "type": "integer" }, "user": { "$ref": "#/components/schemas/PrivateConversationForkUser" }, "fileCopyStatus": { "type": "string", "enum": [ "pending", "done" ] } } }, "PrivateConversationForkedChild": { "type": "object", "properties": { "childConversationId": { "type": "string" }, "childConversationTitle": { "type": "string", "nullable": true }, "sourceMessageId": { "type": "string" }, "branchedAt": { "type": "integer" }, "user": { "$ref": "#/components/schemas/PrivateConversationForkUser" } } }, "PrivateConversationForkingData": { "type": "object", "properties": { "forkedFrom": { "$ref": "#/components/schemas/PrivateConversationForkedFrom" }, "forkedChildren": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateConversationForkedChild" } } } }, "PrivateFullConversation": { "type": "object", "description": "Full conversation including content, owner, and visibility.", "allOf": [ { "$ref": "#/components/schemas/PrivateConversation" }, { "type": "object", "properties": { "owner": { "$ref": "#/components/schemas/PrivateWorkspace" }, "visibility": { "type": "string", "enum": [ "unlisted", "deleted", "test" ] }, "branchId": { "type": "string", "nullable": true }, "content": { "type": "array", "description": "Array of message arrays (versions/retries)", "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/PrivateUserMessage" }, { "$ref": "#/components/schemas/PrivateAgentMessage" }, { "$ref": "#/components/schemas/PrivateContentFragment" }, { "$ref": "#/components/schemas/PrivateCompactionMessage" } ] } } } } } ] }, "PrivateUserMessage": { "type": "object", "description": "A user message in a conversation.", "required": [ "type", "sId", "content", "version", "rank", "created" ], "properties": { "id": { "type": "integer" }, "type": { "type": "string", "enum": [ "user_message" ] }, "sId": { "type": "string" }, "created": { "type": "integer" }, "visibility": { "type": "string", "enum": [ "visible", "deleted" ] }, "version": { "type": "integer" }, "rank": { "type": "integer" }, "user": { "type": "object", "nullable": true, "description": "The user who sent the message", "properties": { "sId": { "type": "string" }, "username": { "type": "string" }, "fullName": { "type": "string" }, "image": { "type": "string", "nullable": true } } }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateMention" } }, "richMentions": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateRichMentionWithStatus" } }, "content": { "type": "string" }, "context": { "$ref": "#/components/schemas/PrivateUserMessageContext" }, "reactions": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateReaction" } } } }, "PrivateAgentMessage": { "type": "object", "description": "An agent message in a conversation.", "required": [ "type", "sId", "version", "rank", "status", "parentMessageId" ], "properties": { "id": { "type": "integer" }, "agentMessageId": { "type": "integer" }, "type": { "type": "string", "enum": [ "agent_message" ] }, "sId": { "type": "string" }, "created": { "type": "integer" }, "completedTs": { "type": "integer", "nullable": true }, "visibility": { "type": "string", "enum": [ "visible", "deleted" ] }, "version": { "type": "integer" }, "rank": { "type": "integer" }, "parentMessageId": { "type": "string" }, "parentAgentMessageId": { "type": "string", "nullable": true, "description": "If handover, the agent message that summoned this agent" }, "status": { "type": "string", "enum": [ "created", "succeeded", "failed", "cancelled" ] }, "content": { "type": "string", "nullable": true }, "chainOfThought": { "type": "string", "nullable": true }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "metadata": { "type": "object", "nullable": true } } }, "configuration": { "$ref": "#/components/schemas/PrivateLightAgentConfiguration" }, "actions": { "type": "array", "items": { "type": "object" }, "description": "MCP actions executed by the agent" }, "contents": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "integer" }, "content": { "type": "object" } } } }, "skipToolsValidation": { "type": "boolean" }, "richMentions": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateRichMentionWithStatus" } }, "completionDurationMs": { "type": "integer", "nullable": true }, "reactions": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateReaction" } }, "costCredits": { "type": "integer", "nullable": true, "description": "Cost of producing this agent message, in AWU credits (intelligence + tool credits). Null when no billable usage is attributed to the message." }, "subAgentCostCredits": { "type": "number", "nullable": true, "description": "Aggregated AWU credit cost of all sub-agents (run_agent / agent_handover) spawned recursively by this message. Computed only on single-message fetches; null otherwise." } } }, "PrivateLightAgentMessage": { "type": "object", "description": "A lighter agent message used in paginated message list responses.", "required": [ "type", "sId", "version", "rank", "status", "parentMessageId", "configuration" ], "properties": { "type": { "type": "string", "enum": [ "agent_message" ] }, "sId": { "type": "string" }, "created": { "type": "integer" }, "completedTs": { "type": "integer", "nullable": true }, "visibility": { "type": "string", "enum": [ "visible", "deleted" ] }, "version": { "type": "integer" }, "rank": { "type": "integer" }, "parentMessageId": { "type": "string" }, "parentAgentMessageId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "created", "succeeded", "failed", "cancelled" ] }, "content": { "type": "string", "nullable": true }, "chainOfThought": { "type": "string", "nullable": true }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "metadata": { "type": "object", "nullable": true } } }, "configuration": { "type": "object", "description": "Minimal agent configuration info", "properties": { "sId": { "type": "string" }, "name": { "type": "string" }, "pictureUrl": { "type": "string" }, "status": { "type": "string" }, "canRead": { "type": "boolean" } } }, "citations": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PrivateCitation" } }, "generatedFiles": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "title": { "type": "string" }, "contentType": { "type": "string" }, "publicUrl": { "type": "string" } } } }, "richMentions": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateRichMentionWithStatus" } }, "completionDurationMs": { "type": "integer", "nullable": true }, "costCredits": { "type": "integer", "nullable": true, "description": "Cost of producing this agent message, in AWU credits (intelligence + tool credits). Null when no billable usage is attributed to the message." }, "subAgentCostCredits": { "type": "number", "nullable": true, "description": "Aggregated AWU credit cost of all sub-agents (run_agent / agent_handover) spawned recursively by this message. Computed only on single-message fetches; null otherwise." }, "activitySteps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking", "action" ] }, "content": { "type": "string", "description": "Chain of thought text (thinking steps only)" }, "label": { "type": "string", "description": "Action display label (action steps only)" }, "id": { "type": "string" }, "actionId": { "type": "string", "description": "Action string identifier (action steps only)" } } } }, "reactions": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateReaction" } } } }, "PrivateCitation": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "href": { "type": "string" }, "provider": { "type": "string" }, "contentType": { "type": "string" } } }, "PrivateContentFragment": { "type": "object", "description": "A content fragment (file or content node attachment) in a conversation.", "required": [ "type", "sId", "title", "contentType", "contentFragmentType" ], "properties": { "type": { "type": "string", "enum": [ "content_fragment" ] }, "id": { "type": "integer" }, "sId": { "type": "string" }, "created": { "type": "integer" }, "visibility": { "type": "string", "enum": [ "visible", "deleted" ] }, "version": { "type": "integer" }, "rank": { "type": "integer" }, "title": { "type": "string" }, "contentType": { "type": "string", "description": "MIME type of the content" }, "sourceUrl": { "type": "string", "nullable": true }, "context": { "type": "object", "properties": { "username": { "type": "string", "nullable": true }, "fullName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "profilePictureUrl": { "type": "string", "nullable": true } } }, "contentFragmentId": { "type": "string" }, "contentFragmentVersion": { "type": "string", "enum": [ "superseded", "latest" ] }, "contentFragmentType": { "type": "string", "enum": [ "file", "content_node" ], "description": "Whether this is a file upload or a content node reference" }, "expiredReason": { "type": "string", "nullable": true, "enum": [ "data_source_deleted" ] }, "fileId": { "type": "string", "nullable": true, "description": "Present for file content fragments" }, "path": { "type": "string", "nullable": true, "description": "Path of this file inside the sandbox conversation mount." }, "skipDataSourceIndexing": { "type": "boolean", "description": "Whether data source indexing was skipped for this file." }, "skipFileProcessing": { "type": "boolean", "description": "Whether upload-time file processing was skipped." }, "snippet": { "type": "string", "nullable": true }, "textUrl": { "type": "string", "nullable": true }, "textBytes": { "type": "integer", "nullable": true }, "nodeId": { "type": "string", "nullable": true, "description": "Present for content node fragments" }, "nodeDataSourceViewId": { "type": "string", "nullable": true } } }, "PrivateCompactionMessage": { "type": "object", "description": "A compaction message summarizing earlier conversation content.", "required": [ "type", "sId", "status", "version", "rank", "created" ], "properties": { "type": { "type": "string", "enum": [ "compaction_message" ] }, "id": { "type": "integer" }, "compactionMessageId": { "type": "integer" }, "sId": { "type": "string" }, "created": { "type": "integer" }, "visibility": { "type": "string", "enum": [ "visible", "deleted" ] }, "version": { "type": "integer" }, "rank": { "type": "integer" }, "branchId": { "type": "string", "nullable": true }, "sourceConversationId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "created", "succeeded", "failed" ] }, "content": { "type": "string", "nullable": true, "description": "Compacted summary. Null while status is \"created\"." } } }, "PrivateLightAgentConfiguration": { "type": "object", "description": "Agent configuration as returned by the private list endpoint.", "required": [ "id", "sId", "version", "name", "description", "pictureUrl", "status", "scope", "model", "maxStepsPerRun", "tags" ], "properties": { "id": { "type": "integer" }, "sId": { "type": "string" }, "version": { "type": "integer" }, "versionCreatedAt": { "type": "string", "nullable": true }, "versionAuthorId": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "instructions": { "type": "string", "nullable": true }, "pictureUrl": { "type": "string" }, "status": { "type": "string", "description": "Agent status", "enum": [ "active", "archived", "draft", "pending", "disabled_by_admin", "disabled_missing_datasource", "disabled_free_workspace" ] }, "scope": { "type": "string", "enum": [ "global", "visible", "hidden" ] }, "userFavorite": { "type": "boolean" }, "model": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "temperature": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "none", "light", "medium", "high" ] } } }, "maxStepsPerRun": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "sId": { "type": "string" }, "name": { "type": "string" } } } }, "templateId": { "type": "string", "nullable": true }, "requestedGroupIds": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "requestedSpaceIds": { "type": "array", "items": { "type": "string" } }, "canRead": { "type": "boolean" }, "canEdit": { "type": "boolean" }, "lastAuthors": { "type": "array", "description": "Optional, returned when withAuthors query param is set", "items": { "type": "string" } }, "editors": { "type": "array", "description": "Optional, returned when withEditors query param is set", "items": { "type": "object", "properties": { "sId": { "type": "string" }, "fullName": { "type": "string" }, "image": { "type": "string", "nullable": true } } } }, "usage": { "type": "object", "description": "Optional, returned when withUsage query param is set", "properties": { "messageCount": { "type": "integer" }, "conversationCount": { "type": "integer" }, "userCount": { "type": "integer" }, "timePeriodSec": { "type": "integer" } } }, "feedbacks": { "type": "object", "description": "Optional, returned when withFeedbacks query param is set", "properties": { "up": { "type": "integer" }, "down": { "type": "integer" } } } } }, "PrivateFileWithUploadUrl": { "type": "object", "description": "File record with a pre-signed upload URL.", "required": [ "sId", "id", "fileName", "fileSize", "contentType", "status", "useCase", "uploadUrl" ], "properties": { "sId": { "type": "string" }, "id": { "type": "string" }, "contentType": { "type": "string" }, "fileName": { "type": "string" }, "fileSize": { "type": "integer" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "failed", "ready" ] }, "useCase": { "type": "string", "enum": [ "conversation", "avatar", "tool_output", "upsert_document", "folders_document", "upsert_table", "project_context", "skill_attachment" ] }, "uploadUrl": { "type": "string", "description": "Pre-signed URL for uploading the file content" }, "downloadUrl": { "type": "string" }, "publicUrl": { "type": "string" }, "path": { "type": "string", "nullable": true, "description": "path when the file is ready on a mount (e.g. `project/report.pdf` or `conversation/chart.png`). Same shape as mount file listing entries." } } }, "PrivateSpace": { "type": "object", "description": "A space in the workspace.", "required": [ "sId", "name", "kind", "groupIds", "isRestricted", "managementMode" ], "properties": { "sId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "global", "system", "conversations", "regular", "project" ] }, "groupIds": { "type": "array", "items": { "type": "string" } }, "isRestricted": { "type": "boolean" }, "managementMode": { "type": "string", "enum": [ "manual", "group" ] }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } } }, "PrivateProject": { "type": "object", "description": "A project space with additional metadata.", "allOf": [ { "$ref": "#/components/schemas/PrivateSpace" }, { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "isMember": { "type": "boolean" }, "archivedAt": { "type": "integer", "nullable": true }, "todoGenerationEnabled": { "type": "boolean", "description": "Whether automatic todo suggestions from project activity are enabled." }, "lastTodoAnalysisAt": { "type": "integer", "nullable": true, "description": "Unix timestamp (ms) of the last automatic todo suggestion scan, if any." }, "pinnedFramePath": { "type": "string", "nullable": true, "description": "Scoped path to the frame file pinned as the Pod banner (e.g. project/banner.html)." } } } ] }, "PrivateDataSourceView": { "type": "object", "description": "A view on a data source within a space.", "required": [ "sId", "id", "category", "kind", "spaceId", "dataSource" ], "properties": { "sId": { "type": "string" }, "id": { "type": "integer" }, "category": { "type": "string", "enum": [ "managed", "folder", "website", "apps" ] }, "kind": { "type": "string", "enum": [ "default", "custom" ] }, "spaceId": { "type": "string" }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" }, "parentsIn": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "List of parent IDs included in this view, null if the full data source is used" }, "dataSource": { "$ref": "#/components/schemas/PrivateDataSource" }, "editedByUser": { "type": "object", "nullable": true, "properties": { "editedAt": { "type": "integer", "nullable": true }, "fullName": { "type": "string", "nullable": true }, "imageUrl": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "userId": { "type": "string", "nullable": true } } } } }, "PrivateDataSource": { "type": "object", "description": "A data source in the workspace.", "required": [ "sId", "id", "name" ], "properties": { "sId": { "type": "string" }, "id": { "type": "integer" }, "createdAt": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "assistantDefaultSelected": { "type": "boolean" }, "dustAPIProjectId": { "type": "string" }, "dustAPIDataSourceId": { "type": "string" }, "connectorId": { "type": "string", "nullable": true }, "connectorProvider": { "type": "string", "nullable": true } } }, "PrivateMentionSuggestion": { "type": "object", "description": "A rich mention suggestion for agents or users.", "required": [ "id", "type", "label", "pictureUrl", "description" ], "properties": { "id": { "type": "string", "description": "Agent sId or user sId" }, "type": { "type": "string", "enum": [ "agent", "user" ] }, "label": { "type": "string", "description": "Display name" }, "pictureUrl": { "type": "string" }, "description": { "type": "string", "description": "Agent description or user email" }, "userFavorite": { "type": "boolean", "description": "Whether the agent is a user favorite (agent mentions only)" } } }, "PrivateFeatureFlags": { "type": "object", "description": "Workspace feature flags response.", "required": [ "feature_flags" ], "properties": { "feature_flags": { "type": "array", "items": { "type": "string" }, "description": "List of enabled feature flag names for the workspace" } } }, "PrivateExtensionConfig": { "type": "object", "description": "Extension configuration for the workspace.", "required": [ "blacklistedDomains" ], "properties": { "blacklistedDomains": { "type": "array", "items": { "type": "string" }, "description": "Domains where the extension should not activate" } } }, "PrivateFeedback": { "type": "object", "description": "User feedback on an agent message.", "required": [ "id", "sId", "messageId", "agentMessageId", "userId", "thumbDirection", "agentConfigurationId", "agentConfigurationVersion", "isConversationShared", "dismissed", "createdAt" ], "properties": { "id": { "type": "integer" }, "sId": { "type": "string" }, "messageId": { "type": "string" }, "agentMessageId": { "type": "integer" }, "userId": { "type": "integer" }, "thumbDirection": { "type": "string", "enum": [ "up", "down" ] }, "content": { "type": "string", "nullable": true, "description": "Optional text feedback from the user" }, "createdAt": { "type": "string", "format": "date-time" }, "agentConfigurationId": { "type": "string" }, "agentConfigurationVersion": { "type": "integer" }, "isConversationShared": { "type": "boolean" }, "dismissed": { "type": "boolean" } } }, "PrivateWakeUp": { "type": "object", "description": "A wake-up scheduled in a conversation to re-invoke the agent at a later time.", "required": [ "id", "sId", "createdAt", "agentConfigurationId", "scheduleConfig", "reason", "status", "fireCount", "maxFires" ], "properties": { "id": { "type": "integer" }, "sId": { "type": "string" }, "createdAt": { "type": "integer", "description": "Unix timestamp (milliseconds)." }, "agentConfigurationId": { "type": "string" }, "scheduleConfig": { "oneOf": [ { "type": "object", "required": [ "type", "fireAt" ], "properties": { "type": { "type": "string", "enum": [ "one_shot" ] }, "fireAt": { "type": "integer", "description": "Unix timestamp (milliseconds) when the wake-up should fire." } } }, { "type": "object", "required": [ "type", "cron", "timezone" ], "properties": { "type": { "type": "string", "enum": [ "cron" ] }, "cron": { "type": "string", "description": "5-field cron expression." }, "timezone": { "type": "string", "description": "IANA timezone name." } } } ] }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "scheduled", "fired", "cancelled", "expired" ] }, "fireCount": { "type": "integer" }, "maxFires": { "type": "integer" } } }, "PrivateMention": { "type": "object", "description": "A mention in a message (agent or user).", "properties": { "configurationId": { "type": "string", "description": "Agent configuration sId (for agent mentions)" }, "type": { "type": "string", "enum": [ "user" ], "description": "Present only for user mentions" }, "userId": { "type": "string", "description": "User sId (for user mentions)" } } }, "PrivateRichMentionWithStatus": { "type": "object", "description": "A rich mention with approval status, used in message responses.", "required": [ "id", "type", "label", "pictureUrl", "description", "dismissed", "status" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "agent", "user" ] }, "label": { "type": "string" }, "pictureUrl": { "type": "string" }, "description": { "type": "string" }, "userFavorite": { "type": "boolean" }, "dismissed": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending_conversation_access", "pending_project_membership", "approved", "rejected", "user_restricted_by_conversation_access", "agent_restricted_by_space_usage" ] } } }, "PrivateUserMessageContext": { "type": "object", "description": "Context metadata for a user message.", "required": [ "username", "timezone", "origin" ], "properties": { "username": { "type": "string" }, "fullName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "profilePictureUrl": { "type": "string", "nullable": true }, "timezone": { "type": "string" }, "origin": { "type": "string", "enum": [ "web", "project_kickoff", "extension", "agent_sidekick", "api", "cli", "cli_programmatic", "email", "excel", "gsheet", "make", "n8n", "powerpoint", "raycast", "slack", "slack_workflow", "teams", "transcript", "triggered_programmatic", "triggered", "wakeup", "zapier", "zendesk", "onboarding_conversation" ] } } }, "PrivateReaction": { "type": "object", "description": "A reaction on a message.", "required": [ "emoji", "users" ], "properties": { "emoji": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "nullable": true }, "username": { "type": "string" }, "fullName": { "type": "string", "nullable": true } } } } } }, "PrivateConversationEvent": { "type": "object", "description": "Server-Sent Event for conversation-level streaming. Discriminated on the `type` field.", "discriminator": { "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/PrivateUserMessageNewEvent" }, { "$ref": "#/components/schemas/PrivateAgentMessageNewEvent" }, { "$ref": "#/components/schemas/PrivateAgentMessageDoneEvent" }, { "$ref": "#/components/schemas/PrivateCompactionMessageNewEvent" }, { "$ref": "#/components/schemas/PrivateCompactionMessageDoneEvent" }, { "$ref": "#/components/schemas/PrivateConversationTitleEvent" } ] }, "PrivateUserMessageNewEvent": { "type": "object", "required": [ "type", "created", "messageId", "message" ], "properties": { "type": { "type": "string", "enum": [ "user_message_new" ] }, "created": { "type": "integer" }, "messageId": { "type": "string" }, "message": { "$ref": "#/components/schemas/PrivateUserMessage" } } }, "PrivateAgentMessageNewEvent": { "type": "object", "required": [ "type", "created", "configurationId", "messageId", "message" ], "properties": { "type": { "type": "string", "enum": [ "agent_message_new" ] }, "created": { "type": "integer" }, "configurationId": { "type": "string" }, "messageId": { "type": "string" }, "message": { "$ref": "#/components/schemas/PrivateAgentMessage" } } }, "PrivateAgentMessageDoneEvent": { "type": "object", "required": [ "type", "created", "conversationId", "configurationId", "messageId", "status" ], "properties": { "type": { "type": "string", "enum": [ "agent_message_done" ] }, "created": { "type": "integer" }, "conversationId": { "type": "string" }, "configurationId": { "type": "string" }, "messageId": { "type": "string" }, "status": { "type": "string", "enum": [ "success", "error" ] } } }, "PrivateCompactionMessageNewEvent": { "type": "object", "required": [ "type", "created", "messageId", "message" ], "properties": { "type": { "type": "string", "enum": [ "compaction_message_new" ] }, "created": { "type": "integer" }, "messageId": { "type": "string" }, "message": { "$ref": "#/components/schemas/PrivateCompactionMessage" } } }, "PrivateCompactionMessageDoneEvent": { "type": "object", "required": [ "type", "created", "messageId", "message" ], "properties": { "type": { "type": "string", "enum": [ "compaction_message_done" ] }, "created": { "type": "integer" }, "messageId": { "type": "string" }, "message": { "$ref": "#/components/schemas/PrivateCompactionMessage" } } }, "PrivateConversationTitleEvent": { "type": "object", "required": [ "type", "created", "title" ], "properties": { "type": { "type": "string", "enum": [ "conversation_title" ] }, "created": { "type": "integer" }, "title": { "type": "string" } } }, "PrivateAgentMessageEvent": { "type": "object", "description": "Server-Sent Event for agent message streaming. Discriminated on the `type` field. Each event also includes a `step` integer.", "discriminator": { "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/PrivateGenerationTokensEvent" }, { "$ref": "#/components/schemas/PrivateToolCallStartedEvent" }, { "$ref": "#/components/schemas/PrivateAgentActionSuccessEvent" }, { "$ref": "#/components/schemas/PrivateAgentMessageSuccessEvent" }, { "$ref": "#/components/schemas/PrivateAgentErrorEvent" }, { "$ref": "#/components/schemas/PrivateAgentGenerationCancelledEvent" }, { "$ref": "#/components/schemas/PrivateToolErrorEvent" }, { "$ref": "#/components/schemas/PrivateToolParamsEvent" }, { "$ref": "#/components/schemas/PrivateToolApproveExecutionEvent" }, { "$ref": "#/components/schemas/PrivateToolNotificationEvent" }, { "$ref": "#/components/schemas/PrivateToolPersonalAuthRequiredEvent" }, { "$ref": "#/components/schemas/PrivateToolFileAuthRequiredEvent" }, { "$ref": "#/components/schemas/PrivateAgentContextPrunedEvent" } ] }, "PrivateGenerationTokensEvent": { "type": "object", "required": [ "type", "created", "configurationId", "messageId", "text", "classification" ], "properties": { "type": { "type": "string", "enum": [ "generation_tokens" ] }, "created": { "type": "integer" }, "configurationId": { "type": "string" }, "messageId": { "type": "string" }, "text": { "type": "string", "description": "The token(s) generated in this chunk" }, "classification": { "type": "string", "enum": [ "tokens", "chain_of_thought", "opening_delimiter", "closing_delimiter" ] }, "delimiterClassification": { "type": "string", "description": "Present when classification is opening_delimiter or closing_delimiter" }, "step": { "type": "integer" } } }, "PrivateToolCallStartedEvent": { "type": "object", "required": [ "type", "created", "configurationId", "messageId", "toolName" ], "properties": { "type": { "type": "string", "enum": [ "tool_call_started" ] }, "created": { "type": "integer" }, "configurationId": { "type": "string" }, "messageId": { "type": "string" }, "toolCallId": { "type": "string" }, "toolCallIndex": { "type": "integer" }, "toolName": { "type": "string" }, "step": { "type": "integer" } } }, "PrivateAgentActionSuccessEvent": { "type": "object", "required": [ "type", "created", "configurationId", "messageId", "action" ], "properties": { "type": { "type": "string", "enum": [ "agent_action_success" ] }, "created": { "type": "integer" }, "configurationId": { "type": "string" }, "messageId": { "type": "string" }, "action": { "$ref": "#/components/schemas/PrivateAgentMCPAction" }, "step": { "type": "integer" } } }, "PrivateAgentMCPAction": { "type": "object", "description": "An MCP action with its output.", "required": [ "id", "sId", "createdAt", "updatedAt", "agentMessageId", "toolName", "functionCallName", "functionCallId", "params", "citationsAllocated", "status", "step", "generatedFiles", "output" ], "properties": { "id": { "type": "integer", "description": "Numeric model identifier" }, "sId": { "type": "string", "description": "Unique string identifier" }, "createdAt": { "type": "integer", "description": "Unix timestamp of creation" }, "updatedAt": { "type": "integer", "description": "Unix timestamp of last update" }, "agentMessageId": { "type": "integer", "description": "ID of the parent agent message" }, "internalMCPServerName": { "type": "string", "nullable": true, "description": "Name of the internal MCP server, if any" }, "toolName": { "type": "string", "description": "Name of the tool" }, "mcpServerId": { "type": "string", "nullable": true, "description": "ID of the MCP server, if external" }, "functionCallName": { "type": "string", "description": "Name of the function call" }, "functionCallId": { "type": "string", "description": "ID of the function call" }, "params": { "type": "object", "description": "Parameters passed to the tool" }, "citationsAllocated": { "type": "integer", "description": "Number of citations allocated" }, "status": { "type": "string", "enum": [ "succeeded", "errored", "denied", "blocked_authentication_required", "blocked_file_authorization_required", "blocked_validation_required", "blocked_child_action_input_required", "blocked_user_answer_required", "ready_allowed_explicitly", "ready_allowed_implicitly", "running" ], "description": "Execution status of the tool" }, "step": { "type": "integer", "description": "Step number in the agent execution" }, "executionDurationMs": { "type": "integer", "nullable": true, "description": "Duration of execution in milliseconds" }, "displayLabels": { "type": "object", "nullable": true, "properties": { "running": { "type": "string" }, "done": { "type": "string" } } }, "generatedFiles": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "title": { "type": "string" }, "contentType": { "type": "string" }, "snippet": { "type": "string", "nullable": true }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" }, "isInProjectContext": { "type": "boolean" }, "hidden": { "type": "boolean" } } } }, "output": { "type": "array", "nullable": true, "description": "Tool call result content", "items": { "type": "object" } }, "citations": { "type": "object", "nullable": true, "description": "Map of citation key to citation object" } } }, "PrivateAgentMessageSuccessEvent": { "type": "object", "required": [ "type", "created", "configurationId", "messageId", "message", "runIds" ], "properties": { "type": { "type": "string", "enum": [ "agent_message_success" ] }, "created": { "type": "integer" }, "configurationId": { "type": "string" }, "messageId": { "type": "string" }, "message": { "$ref": "#/components/schemas/PrivateAgentMessage" }, "runIds": { "type": "array", "items": { "type": "string" } }, "step": { "type": "integer" } } }, "PrivateAgentErrorEvent": { "type": "object", "required": [ "type", "created", "configurationId", "messageId", "error" ], "properties": { "type": { "type": "string", "enum": [ "agent_error" ] }, "created": { "type": "integer" }, "configurationId": { "type": "string" }, "messageId": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "runIds": { "type": "array", "items": { "type": "string" } }, "step": { "type": "integer" } } }, "PrivateAgentGenerationCancelledEvent": { "type": "object", "required": [ "type", "created", "configurationId", "messageId" ], "properties": { "type": { "type": "string", "enum": [ "agent_generation_cancelled" ] }, "created": { "type": "integer" }, "configurationId": { "type": "string" }, "messageId": { "type": "string" }, "step": { "type": "integer" } } }, "PrivateToolErrorEvent": { "type": "object", "required": [ "type", "created", "configurationId", "messageId", "conversationId", "error", "isLastBlockingEventForStep" ], "properties": { "type": { "type": "string", "enum": [ "tool_error" ] }, "created": { "type": "integer" }, "configurationId": { "type": "string" }, "messageId": { "type": "string" }, "conversationId": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "isLastBlockingEventForStep": { "type": "boolean" }, "step": { "type": "integer" } } }, "PrivateToolParamsEvent": { "type": "object", "required": [ "type", "created", "configurationId", "messageId", "action" ], "properties": { "type": { "type": "string", "enum": [ "tool_params" ] }, "created": { "type": "integer" }, "configurationId": { "type": "string" }, "messageId": { "type": "string" }, "action": { "type": "object", "description": "The MCP action with its parameters" }, "runIds": { "type": "array", "items": { "type": "string" } }, "step": { "type": "integer" } } }, "PrivateToolApproveExecutionEvent": { "type": "object", "description": "Sent when a tool requires user approval before execution.", "required": [ "type", "created", "conversationId", "messageId", "actionId", "configurationId", "inputs" ], "properties": { "type": { "type": "string", "enum": [ "tool_approve_execution" ] }, "created": { "type": "integer" }, "conversationId": { "type": "string" }, "messageId": { "type": "string" }, "actionId": { "type": "string" }, "configurationId": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": true }, "stake": { "type": "string", "description": "Risk level of the tool execution" }, "isLastBlockingEventForStep": { "type": "boolean" }, "metadata": { "type": "object" }, "step": { "type": "integer" } } }, "PrivateToolNotificationEvent": { "type": "object", "description": "Progress notification from a running tool.", "required": [ "type", "created", "configurationId", "conversationId", "messageId", "action", "notification" ], "properties": { "type": { "type": "string", "enum": [ "tool_notification" ] }, "created": { "type": "integer" }, "configurationId": { "type": "string" }, "conversationId": { "type": "string" }, "messageId": { "type": "string" }, "action": { "type": "object", "description": "The MCP action producing the notification" }, "notification": { "type": "object", "description": "Progress notification content" }, "step": { "type": "integer" } } }, "PrivateToolPersonalAuthRequiredEvent": { "type": "object", "description": "Sent when a tool requires personal OAuth authentication.", "required": [ "type", "created", "conversationId", "messageId", "actionId", "configurationId", "authError" ], "properties": { "type": { "type": "string", "enum": [ "tool_personal_auth_required" ] }, "created": { "type": "integer" }, "conversationId": { "type": "string" }, "messageId": { "type": "string" }, "actionId": { "type": "string" }, "configurationId": { "type": "string" }, "authError": { "type": "object", "properties": { "mcpServerId": { "type": "string" }, "provider": { "type": "string" }, "scope": { "type": "string" }, "toolName": { "type": "string" }, "message": { "type": "string" } } }, "step": { "type": "integer" } } }, "PrivateToolFileAuthRequiredEvent": { "type": "object", "description": "Sent when a tool requires file access authorization (e.g., Google Drive).", "required": [ "type", "created", "conversationId", "messageId", "actionId", "configurationId", "fileAuthError" ], "properties": { "type": { "type": "string", "enum": [ "tool_file_auth_required" ] }, "created": { "type": "integer" }, "conversationId": { "type": "string" }, "messageId": { "type": "string" }, "actionId": { "type": "string" }, "configurationId": { "type": "string" }, "fileAuthError": { "type": "object", "properties": { "fileId": { "type": "string" }, "fileName": { "type": "string" }, "connectionId": { "type": "string" }, "mimeType": { "type": "string" }, "toolName": { "type": "string" }, "message": { "type": "string" } } }, "step": { "type": "integer" } } }, "PrivateAgentContextPrunedEvent": { "type": "object", "required": [ "type", "created", "configurationId", "messageId" ], "properties": { "type": { "type": "string", "enum": [ "agent_context_pruned" ] }, "created": { "type": "integer" }, "configurationId": { "type": "string" }, "messageId": { "type": "string" }, "step": { "type": "integer" } } }, "Section": { "type": "object", "description": "A section of a document that can contain nested sections", "properties": { "prefix": { "type": "string", "nullable": true, "description": "Optional prefix text for the section" }, "content": { "type": "string", "nullable": true, "description": "Optional content text for the section" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/Section" }, "description": "Array of nested sections" } } }, "User": { "type": "object", "properties": { "sId": { "type": "string", "description": "Unique string identifier for the user", "example": "0ec9852c2f" }, "id": { "type": "integer", "example": 12345 }, "createdAt": { "type": "integer", "example": 1625097600 }, "username": { "type": "string", "description": "User's chosen username", "example": "johndoe" }, "email": { "type": "string", "description": "User's email address", "example": "john.doe@example.com" }, "firstName": { "type": "string", "description": "User's first name", "example": "John" }, "lastName": { "type": "string", "description": "User's last name", "example": "Doe" }, "fullName": { "type": "string", "description": "User's full name", "example": "John Doe" }, "provider": { "type": "string", "description": "Authentication provider used by the user", "example": "google" }, "image": { "type": "string", "description": "URL of the user's profile image", "example": "https://example.com/profile/johndoe.jpg" } } }, "Workspace": { "type": "object", "required": [ "regionalModelsOnly" ], "properties": { "id": { "type": "integer", "example": 67890 }, "sId": { "type": "string", "description": "Unique string identifier for the workspace", "example": "dQFf9l5FQY" }, "name": { "type": "string", "description": "Name of the workspace", "example": "My Awesome Workspace" }, "role": { "type": "string", "description": "User's role in the workspace", "example": "admin" }, "segmentation": { "type": "string", "nullable": true, "description": "Segmentation information for the workspace", "example": "enterprise" }, "flags": { "type": "array", "items": { "type": "string", "description": "Feature flags enabled for the workspace" }, "example": [ "advanced_analytics", "beta_features" ] }, "ssoEnforced": { "type": "boolean", "example": true }, "regionalModelsOnly": { "type": "boolean", "description": "When true, only models whose regionalAvailability includes the workspace's region are usable.", "example": false }, "whiteListedProviders": { "type": "array", "items": { "type": "string", "description": "List of allowed authentication providers" }, "example": [ "google", "github" ] }, "defaultEmbeddingProvider": { "type": "string", "nullable": true, "description": "Default provider for embeddings in the workspace", "example": "openai" } } }, "Context": { "type": "object", "required": [ "username", "timezone" ], "properties": { "username": { "type": "string", "description": "Username in the current context", "example": "johndoe123" }, "timezone": { "type": "string", "description": "User's timezone", "example": "America/New_York" }, "fullName": { "type": "string", "description": "User's full name in the current context", "example": "John Doe" }, "email": { "type": "string", "description": "User's email in the current context", "example": "john.doe@example.com" }, "profilePictureUrl": { "type": "string", "description": "URL of the user's profile picture", "example": "https://example.com/profiles/johndoe123.jpg" }, "agenticMessageData": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "run_agent", "agent_handover" ], "description": "Type of the agentic message" }, "originMessageId": { "type": "string", "description": "ID of the origin message", "example": "2b8e4f6a0c" } } } } }, "AgentConfiguration": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345 }, "sId": { "type": "string", "description": "Unique string identifier for the agent configuration", "example": "7f3a9c2b1e" }, "version": { "type": "integer", "example": 2 }, "versionCreatedAt": { "type": "string", "nullable": true, "description": "Timestamp of when the version was created", "example": "2023-06-15T14:30:00Z" }, "versionAuthorId": { "type": "string", "nullable": true, "description": "ID of the user who created this version", "example": "0ec9852c2f" }, "name": { "type": "string", "description": "Name of the agent configuration", "example": "Customer Support Agent" }, "description": { "type": "string", "description": "Description of the agent configuration", "example": "An AI agent designed to handle customer support inquiries" }, "instructions": { "type": "string", "nullable": true, "description": "Instructions for the agent", "example": "Always greet the customer politely and try to resolve their issue efficiently." }, "pictureUrl": { "type": "string", "description": "URL of the agent's picture", "example": "https://example.com/agent-images/support-agent.png" }, "status": { "type": "string", "description": "Current status of the agent configuration", "example": "active" }, "scope": { "type": "string", "description": "Scope of the agent configuration", "example": "workspace" }, "userFavorite": { "type": "boolean", "description": "Status of the user favorite for this configuration", "example": true }, "model": { "type": "object", "properties": { "providerId": { "type": "string", "description": "ID of the model provider", "example": "openai" }, "modelId": { "type": "string", "description": "ID of the specific model", "example": "gpt-4" }, "temperature": { "type": "number", "example": 0.7 } } }, "actions": { "type": "array", "example": [] }, "maxStepsPerRun": { "type": "integer", "example": 10 }, "templateId": { "type": "string", "nullable": true, "description": "ID of the template used for this configuration", "example": "b4e2f1a9c7" } } }, "Conversation": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "integer", "example": 67890 }, "created": { "type": "integer", "example": 1625097600 }, "sId": { "type": "string", "description": "Unique string identifier for the conversation", "example": "3d8f6a2c1b" }, "owner": { "$ref": "#/components/schemas/Workspace" }, "title": { "type": "string", "description": "Title of the conversation", "example": "Customer Inquiry #1234" }, "visibility": { "type": "string", "description": "Visibility setting of the conversation", "example": "private" }, "content": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "sId": { "type": "string", "description": "Unique string identifier for the message", "example": "9e7d5c3a1f" }, "type": { "type": "string", "description": "Type of the message", "example": "human" }, "visibility": { "type": "string", "description": "Visibility setting of the message", "example": "visible" }, "version": { "type": "integer", "example": 1 }, "created": { "type": "integer", "example": 1625097700 }, "user": { "$ref": "#/components/schemas/User" }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" } }, "content": { "type": "string", "description": "Content of the message", "example": "Hello, I need help with my order." }, "context": { "$ref": "#/components/schemas/Context" }, "agentMessageId": { "type": "integer", "example": 1 }, "parentMessageId": { "type": "string", "description": "ID of the parent message", "example": "2b8e4f6a0c" }, "status": { "type": "string", "description": "Status of the message", "example": "completed" }, "actions": { "type": "array", "example": [] }, "chainOfThought": { "type": "string", "nullable": true, "description": "Chain of thought for the message", "example": "The user is asking about their order. I should first greet them and then ask for their order number." }, "rawContents": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "integer", "example": 1 }, "content": { "type": "string", "description": "Content for each step", "example": "Hello! I'd be happy to help you with your order. Could you please provide your order number?" } } } }, "error": { "type": "string", "nullable": true, "description": "Error message, if any", "example": null }, "configuration": { "$ref": "#/components/schemas/AgentConfiguration" } } } } } } } } }, "Mention": { "type": "object", "properties": { "configurationId": { "type": "string", "description": "ID of the mentioned agent configuration", "example": "7f3a9c2b1e" } } }, "RichMention": { "type": "object", "description": "A rich mention suggestion containing detailed information about an agent or user", "required": [ "id", "type", "label", "pictureUrl", "description" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the mention (agent sId or user sId)", "example": "7f3a9c2b1e" }, "type": { "type": "string", "enum": [ "agent", "user" ], "description": "Type of the mention", "example": "agent" }, "label": { "type": "string", "description": "Display label for the mention", "example": "My Assistant" }, "pictureUrl": { "type": "string", "description": "URL of the profile picture", "example": "https://example.com/avatar.png" }, "description": { "type": "string", "description": "Description of the mention (agent description or user email)", "example": "A helpful AI assistant" }, "userFavorite": { "type": "boolean", "nullable": true, "description": "Whether the agent is marked as a favorite by the user (only for agent mentions)", "example": true } } }, "Message": { "type": "object", "required": [ "content", "mentions" ], "properties": { "content": { "type": "string", "description": "The content of the message. Should not be empty.", "example": "This is my message" }, "mentions": { "type": "array", "description": "Empty array is accepted but won't trigger any agent.", "items": { "$ref": "#/components/schemas/Mention" } }, "context": { "$ref": "#/components/schemas/Context" } } }, "ContentFragment": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "The title of the content fragment", "example": "My content fragment" }, "content": { "type": "string", "description": "The content of the content fragment (optional if `fileId` is set)", "example": "This is my content fragment extracted text" }, "contentType": { "type": "string", "description": "The content type of the content fragment (optional if `fileId` is set)", "example": "text/plain" }, "url": { "type": "string", "description": "The URL of the content fragment", "example": "https://example.com/content" }, "fileId": { "type": "string", "description": "The id of the previously uploaded file (optional if `content` and `contentType` are set)", "example": "fil_123456" }, "path": { "type": "string", "nullable": true, "description": "Path of this file inside the sandbox conversation mount.", "example": "conversation/report.csv" }, "skipDataSourceIndexing": { "type": "boolean", "description": "Whether data source indexing was skipped for this file." }, "skipFileProcessing": { "type": "boolean", "description": "Whether upload-time file processing was skipped." }, "nodeId": { "type": "string", "description": "The id of the content node (optional if `content` and `contentType` are set)", "example": "node_123456" }, "nodeDataSourceViewId": { "type": "string", "description": "The id of the data source view (optional if `content` and `contentType` are set)", "example": "dsv_123456" }, "context": { "$ref": "#/components/schemas/Context" } } }, "Space": { "type": "object", "properties": { "sId": { "type": "string", "description": "Unique string identifier for the space" }, "name": { "type": "string", "description": "Name of the space" }, "kind": { "type": "string", "enum": [ "regular", "global", "system", "public" ], "description": "The kind of the space" }, "groupIds": { "type": "array", "items": { "type": "string" }, "description": "List of group IDs that have access to the space" } } }, "Datasource": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the datasource", "example": 12345 }, "createdAt": { "type": "integer", "description": "Timestamp of when the datasource was created", "example": 1625097600 }, "name": { "type": "string", "description": "Name of the datasource", "example": "Customer Knowledge Base" }, "description": { "type": "string", "description": "Description of the datasource", "example": "Contains all customer-related information and FAQs" }, "dustAPIProjectId": { "type": "string", "description": "ID of the associated Dust API project", "example": "5e9d8c7b6a" }, "connectorId": { "type": "string", "description": "ID of the connector used for this datasource", "example": "1f3e5d7c9b" }, "connectorProvider": { "type": "string", "description": "Provider of the connector (e.g., 'webcrawler')", "example": "webcrawler" }, "assistantDefaultSelected": { "type": "boolean", "description": "Whether this datasource is selected by default for agents", "example": true } } }, "Table": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the table", "example": "Roi data", "deprecated": true }, "title": { "type": "string", "description": "Title of the table", "example": "ROI Data" }, "table_id": { "type": "string", "description": "Unique identifier for the table", "example": "1234f4567c" }, "description": { "type": "string", "description": "Description of the table", "example": "roi data for Q1" }, "mime_type": { "type": "string", "description": "MIME type of the table", "example": "text/csv" }, "schema": { "type": "array", "description": "Array of column definitions", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the column", "example": "roi" }, "value_type": { "type": "string", "description": "Data type of the column", "enum": [ "text", "int", "float", "bool", "date" ], "example": "int" }, "possible_values": { "type": "array", "description": "Array of possible values for the column (null if unrestricted)", "items": { "type": "string" }, "nullable": true, "example": [ "1", "2", "3" ] } } } }, "timestamp": { "type": "number", "description": "Unix timestamp of table creation/modification", "example": 1732810375150 }, "tags": { "type": "array", "description": "Array of tags associated with the table", "items": { "type": "string" } }, "parent_id": { "type": "string", "description": "ID of the table parent", "items": { "type": "string" }, "example": "1234f4567c" }, "parents": { "type": "array", "description": "Array of parent table IDs", "items": { "type": "string" }, "example": [ "1234f4567c" ] } } }, "DatasourceView": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "managed", "folder", "website", "apps" ], "description": "The category of the data source view" }, "createdAt": { "type": "number", "description": "Timestamp of when the data source view was created" }, "dataSource": { "$ref": "#/components/schemas/Datasource" }, "editedByUser": { "type": "object", "description": "The user who last edited the data source view", "properties": { "fullName": { "type": "string", "description": "Full name of the user" }, "editedAt": { "type": "number", "description": "Timestamp of when the data source view was last edited by the user" } } }, "id": { "type": "number", "description": "Unique identifier for the data source view" }, "kind": { "type": "string", "enum": [ "default", "custom" ], "description": "The kind of the data source view" }, "parentsIn": { "type": "array", "items": { "type": "string" }, "description": "List of IDs included in this view, null if complete data source is taken", "nullable": true }, "sId": { "type": "string", "description": "Unique string identifier for the data source view" }, "updatedAt": { "type": "number", "description": "Timestamp of when the data source view was last updated" }, "spaceId": { "type": "string", "description": "ID of the space containing the data source view" } } }, "SkillSourceMetadata": { "type": "object", "properties": { "repoUrl": { "type": "string", "description": "URL of the source repository, when applicable", "example": "https://github.com/dust-tt/skills" }, "filePath": { "type": "string", "description": "Path to the source skill file", "example": "support/SKILL.md" } } }, "Skill": { "type": "object", "properties": { "sId": { "type": "string", "description": "Unique string identifier for the skill", "example": "skill_abc123" }, "createdAt": { "type": "number", "nullable": true, "description": "Timestamp of when the skill was created" }, "updatedAt": { "type": "number", "nullable": true, "description": "Timestamp of when the skill was last updated" }, "editedBy": { "type": "integer", "nullable": true, "description": "Numeric identifier of the last editor" }, "status": { "type": "string", "enum": [ "active", "archived", "suggested" ], "description": "Current status of the skill", "example": "active" }, "name": { "type": "string", "description": "Name of the skill", "example": "Customer Support" }, "agentFacingDescription": { "type": "string", "description": "Description shown to agents when selecting or using the skill", "example": "Use this skill to answer customer support questions." }, "userFacingDescription": { "type": "string", "description": "Description shown to workspace users", "example": "Answers support questions with the right workspace context." }, "icon": { "type": "string", "nullable": true, "description": "Icon identifier for the skill", "example": "ActionRobotIcon" }, "source": { "type": "string", "nullable": true, "enum": [ "web_app", "github", "api", "local_file" ], "description": "Source used to create or import the skill" }, "sourceMetadata": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SkillSourceMetadata" } ] }, "reinforcement": { "type": "string", "enum": [ "auto", "on", "off" ], "description": "Reinforcement setting for the skill" }, "lastReinforcementAnalysisAt": { "type": "string", "nullable": true, "description": "Timestamp of the last reinforcement analysis, when available" }, "requestedSpaceIds": { "type": "array", "items": { "type": "string" }, "description": "Space identifiers the skill needs access to" }, "fileAttachments": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "description": "Unique string identifier for the attached file" }, "fileName": { "type": "string", "description": "Name of the attached file" } } } }, "canWrite": { "type": "boolean", "description": "Whether the authenticated actor can edit the skill" }, "isExtendable": { "type": "boolean", "description": "Whether this skill can be extended by another skill" }, "isDefault": { "type": "boolean", "description": "Whether this skill is enabled by default" }, "extendedSkillId": { "type": "string", "nullable": true, "description": "Identifier of the extended skill, when applicable" }, "instructions": { "type": "string", "nullable": true, "description": "Instructions used by the agent when running the skill" }, "instructionsHtml": { "type": "string", "nullable": true, "description": "HTML representation of the skill instructions" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerView" } } } }, "Run": { "type": "object", "properties": { "run_id": { "type": "string", "description": "The ID of the run", "example": "4a2c6e8b0d" }, "app_id": { "type": "string", "description": "The ID of the app", "example": "9f1d3b5a7c" }, "status": { "type": "object", "properties": { "run": { "type": "string", "description": "The status of the run", "example": "succeeded" }, "build": { "type": "string", "description": "The status of the build", "example": "succeeded" } } }, "results": { "type": "object", "description": "The results of the run", "example": {} }, "specification_hash": { "type": "string", "description": "The hash of the app specification", "example": "8c0a4e6d2f" }, "traces": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "number", "description": "The timestamp of the trace", "example": 1234567890 }, "trace": { "type": "object", "description": "The trace", "example": {} } } } } } } }, "Document": { "type": "object", "properties": { "data_source_id": { "type": "string", "example": "3b7d9f1e5a" }, "created": { "type": "number", "example": 1625097600 }, "document_id": { "type": "string", "example": "2c4a6e8d0f" }, "title": { "type": "string", "description": "Title of the document", "example": "Customer Support FAQ" }, "mime_type": { "type": "string", "description": "MIME type of the table", "example": "text/md" }, "timestamp": { "type": "number", "example": 1625097600 }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "customer_support", "faq" ] }, "parent_id": { "type": "string", "description": "ID of the document parent", "items": { "type": "string" }, "example": "1234f4567c" }, "parents": { "type": "array", "items": { "type": "string" }, "example": [ "7b9d1f3e5a", "2c4a6e8d0f" ] }, "source_url": { "type": "string", "nullable": true, "example": "https://example.com/support/article1" }, "hash": { "type": "string", "example": "a1b2c3d4e5" }, "text_size": { "type": "number", "example": 1024 }, "chunk_count": { "type": "number", "example": 5 }, "chunks": { "type": "array", "items": { "type": "object" }, "example": [ { "chunk_id": "9f1d3b5a7c", "text": "This is the first chunk of the document.", "embedding": [ 0.1, 0.2, 0.3, 0.4 ] }, { "chunk_id": "4a2c6e8b0d", "text": "This is the second chunk of the document.", "embedding": [ 0.5, 0.6, 0.7, 0.8 ] } ] }, "text": { "type": "string", "example": "This is the full text content of the document. It contains multiple paragraphs and covers various topics related to customer support." }, "token_count": { "type": "number", "nullable": true, "example": 150 } } }, "MCPServerView": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the MCP server view", "example": 123 }, "sId": { "type": "string", "description": "Unique string identifier for the MCP server view", "example": "mcp_sv_abc123" }, "name": { "type": "string", "nullable": true, "description": "Custom name for the MCP server view (null if not set)", "example": "My Custom MCP Server" }, "description": { "type": "string", "nullable": true, "description": "Custom description for the MCP server view (null if not set)", "example": "This MCP server handles customer data operations" }, "createdAt": { "type": "number", "description": "Unix timestamp of when the MCP server view was created", "example": 1625097600 }, "updatedAt": { "type": "number", "description": "Unix timestamp of when the MCP server view was last updated", "example": 1625184000 }, "spaceId": { "type": "string", "description": "ID of the space containing the MCP server view", "example": "spc_xyz789" }, "serverType": { "type": "string", "enum": [ "remote", "internal" ], "description": "Type of the MCP server", "example": "remote" }, "server": { "type": "object", "properties": { "sId": { "type": "string", "description": "Unique string identifier for the MCP server", "example": "mcp_srv_def456" }, "name": { "type": "string", "description": "Name of the MCP server", "example": "Customer Data Server" }, "version": { "type": "string", "description": "Version of the MCP server", "example": "1.0.0" }, "description": { "type": "string", "description": "Description of the MCP server", "example": "Handles customer data operations and queries" }, "icon": { "type": "string", "description": "Icon identifier for the MCP server", "example": "database" }, "authorization": { "type": "object", "nullable": true, "properties": { "provider": { "type": "string", "description": "OAuth provider for authorization", "example": "github" }, "supported_use_cases": { "type": "array", "items": { "type": "string", "enum": [ "platform_actions", "personal_actions" ] }, "description": "Supported use cases for the authorization", "example": [ "platform_actions" ] }, "scope": { "type": "string", "description": "OAuth scope required", "example": "repo:read" } } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the tool", "example": "query_customers" }, "description": { "type": "string", "description": "Description of what the tool does", "example": "Query customer database for information" }, "inputSchema": { "type": "object", "description": "JSON Schema for the tool's input parameters", "example": { "type": "object", "properties": { "customerId": { "type": "string" } } } } } } }, "availability": { "type": "string", "description": "Availability status of the MCP server", "example": "production" }, "allowMultipleInstances": { "type": "boolean", "description": "Whether multiple instances of this server can be created", "example": false }, "documentationUrl": { "type": "string", "nullable": true, "description": "URL to the server's documentation", "example": "https://docs.example.com/mcp-server" } } }, "oAuthUseCase": { "type": "string", "nullable": true, "enum": [ "platform_actions", "personal_actions" ], "description": "OAuth use case for the MCP server view", "example": "platform_actions" }, "editedByUser": { "type": "object", "nullable": true, "description": "Information about the user who last edited the MCP server view", "properties": { "editedAt": { "type": "number", "nullable": true, "description": "Unix timestamp of when the edit occurred", "example": 1625184000 }, "fullName": { "type": "string", "nullable": true, "description": "Full name of the editor", "example": "John Doe" }, "imageUrl": { "type": "string", "nullable": true, "description": "Profile image URL of the editor", "example": "https://example.com/profile/johndoe.jpg" } } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Your DUST API key is a Bearer token." } } } }