{ "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": "Users", "description": "User management" }, { "name": "Agents", "description": "Agent configurations" }, { "name": "Analytics", "description": "Workspace analytics" }, { "name": "Apps", "description": "Dust apps" }, { "name": "Conversations", "description": "Conversations" }, { "name": "Datasources", "description": "Data sources" }, { "name": "DatasourceViews", "description": "Data source views" }, { "name": "Feedbacks", "description": "Message feedbacks" }, { "name": "MCP", "description": "MCP servers" }, { "name": "Mentions", "description": "Mentions" }, { "name": "Search", "description": "Search" }, { "name": "Skills", "description": "Skills" }, { "name": "Spaces", "description": "Spaces" }, { "name": "Tools", "description": "Tools" }, { "name": "Triggers", "description": "Triggers" }, { "name": "Workspace", "description": "Workspace" }, { "name": "Private Agents", "description": "Private API - Agent configurations" }, { "name": "Private Authentication", "description": "Private API - Authentication (WorkOS)" }, { "name": "Private Conversations", "description": "Private API - Conversations" }, { "name": "Private Events", "description": "Private API - SSE event streams" }, { "name": "Private Extension", "description": "Private API - Extension configuration" }, { "name": "Private Files", "description": "Private API - File uploads" }, { "name": "Private Mentions", "description": "Private API - Mention suggestions" }, { "name": "Private Messages", "description": "Private API - Messages" }, { "name": "Private Spaces", "description": "Private API - Spaces and data source views" }, { "name": "Private User", "description": "Private API - User" }, { "name": "Private Workspace", "description": "Private API - Workspace settings" } ], "paths": { "/api/v1/w/{wId}/analytics/consumption/export": { "post": { "summary": "Export consumption analytics", "description": "Export per-call consumption analytics for the workspace identified by {wId}.\nEach row represents one unit of billed credit consumption (an LLM call or a tool call).\nThe export can be filtered by various dimensions (agents, users, API keys, groups, models, tools, skills, sources, tags).\nThe export is limited to a maximum of 30 days per request and times out after 10 seconds: reduce the time range\nor apply filters to reduce the number of rows if you encounter a timeout.\nResults are streamed, if an error occurs, an error message is appended and the stream is closed.\n", "tags": [ "Analytics" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "startDate", "endDate" ], "properties": { "startDate": { "type": "string", "format": "date-time", "description": "Start of the time range (inclusive), ISO 8601 datetime", "example": "2026-01-01T00:00:00Z" }, "endDate": { "type": "string", "format": "date-time", "description": "End of the time range (exclusive), ISO 8601 datetime. Must be after startDate, at most 30 days apart.", "example": "2026-01-15T00:00:00Z" }, "format": { "type": "string", "enum": [ "csv", "ndjson" ], "description": "Output format (defaults to csv)" }, "filter": { "type": "object", "description": "Optional dimension filters. Each key maps to an array of string identifiers to include.\nEach value must be at most 256 characters. The total number of values across all dimensions must not exceed 500.\n", "properties": { "agents": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "Agent sIds to filter on" }, "users": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "User IDs to filter on" }, "api_keys": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "API key names to filter on" }, "groups": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "Group IDs to filter on" }, "models": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "Model IDs to filter on" }, "tools": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "Tool server names to filter on" }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "Skill IDs to filter on" }, "sources": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "Context origins to filter on (e.g. \"web\", \"slack\", \"api\")" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "Agent tag IDs to filter on" } } } } } } } }, "responses": { "200": { "description": "The consumption data in CSV or NDJSON format", "content": { "text/csv": { "schema": { "type": "string" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON, one row object per line" } } } }, "400": { "description": "Invalid request body (missing fields, invalid dates, range exceeds 30 days)" }, "403": { "description": "Requires an API key with admin scope" }, "500": { "description": "Internal Server Error" } } } }, "/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": [ "Analytics" ], "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, including credits.\n- \"users\": Top users by message count, including credits, last login date and membership status (active, revoked, unregistered).\n- \"skills\": Skill metadata catalog.\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, including comma-separated lists of tools (as \"server__tool\") and skills used per message, and the cost in credits of each message.\n- \"feedback\": Detailed message-level feedback (thumbs, content, conversation URL).\n", "schema": { "type": "string", "enum": [ "usage_metrics", "active_users", "source", "agents", "users", "skills", "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- all_unrestricted: Retrieves every active agent of the workspace, including unpublished agents the caller does not edit and agents requesting spaces the caller cannot access. Requires an admin key.\n", "schema": { "type": "string", "enum": [ "all", "all_unrestricted", "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." }, "403": { "description": "Forbidden. The all_unrestricted view requires a workspace admin." }, "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", "description": "Emails of the workspace members to set as editors of the agent. Omitting this field keeps the current editors; providing it replaces the whole list.", "items": { "type": "string", "format": "email" }, "example": [ "alice@example.com" ] }, "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", "description": "Replaces the full set of tools on the agent. Any tool not present in this array is removed, so send the complete desired toolset. Each entry resolves an MCP server by name (see configuration.mcp_server_name). Entries that cannot be resolved are not applied and are returned in the skippedActions field of the response rather than causing the whole request to fail.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "MCP" ] }, "configuration": { "type": "object", "properties": { "mcp_server_name": { "type": "string", "description": "Name of the MCP server to attach. Both built-in (internal) tools and remote MCP servers are supported. A remote MCP server must first be shared to a space (global or a regular space the caller can access); it is matched by its display name, which must be unambiguous within the workspace." } } } } } } } } } } }, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully updated agent configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentConfiguration": { "$ref": "#/components/schemas/AgentConfiguration" }, "skippedActions": { "type": "array", "description": "Toolset entries that could not be applied (e.g. the referenced MCP server was not found, is not shared to an accessible space, or the name was ambiguous). The request still succeeds; inspect this list to confirm every intended tool was attached.", "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 its triggers 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 parameters or the agent is already archived." }, "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", "avatar_url", "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", "description": "Emails of the workspace members to set as editors of the agent.", "items": { "type": "string", "format": "email" }, "example": [ "alice@example.com" ] }, "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. Pass the\ncanonical `filePath` surfaced in a message action's `generatedFiles` (the legacy\n`conversation/foo.pdf` form is also accepted). The file content is streamed\ndirectly 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: the canonical `filePath` returned in a message\naction's `generatedFiles`, or the legacy `conversation/foo.pdf` form. Paths\nscoped to another conversation or to a different scope are rejected. Path\ntraversal 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/{skillId}": { "delete": { "summary": "Archive a skill", "description": "Soft-archives a custom skill in the workspace.", "tags": [ "Skills" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "Unique string identifier for the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "skillId", "required": true, "description": "Unique string identifier for the custom skill", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill archived successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. The caller is not allowed to archive skills." }, "404": { "description": "Skill not found." }, "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" ] } }, { "in": "query", "name": "availability", "required": false, "description": "Filter skills by availability. Repeatable to match several values. Unpublished (editors) skills are only returned when bypassEditorVisibility is set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "editors", "workspace_users", "users_and_agents" ] } }, "style": "form", "explode": true }, { "in": "query", "name": "bypassEditorVisibility", "required": false, "description": "When true, also return unpublished (editors) skills. Requires an admin API key.", "schema": { "type": "boolean" } } ], "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." }, "editors": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Optional editor email addresses to add to imported or updated skills. Editors must be active workspace builders. Existing skills keep their current editors." }, "availability": { "type": "string", "enum": [ "editors", "workspace_users", "users_and_agents" ], "description": "Optional availability to apply to imported or updated skills. editors is unpublished, workspace_users is published, and users_and_agents is discoverable. New skills default to editors and existing skills keep their current availability when omitted." } } } } } }, "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" }, "429": { "description": "Too many pending table updates are queued for this table. Retry later." } } } }, "/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." }, "429": { "description": "Too many pending table updates are queued for this table. Retry later." }, "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": "object", "properties": { "tables": { "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": { "type": "object", "properties": { "table": { "$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" } }, { "in": "query", "name": "kinds", "required": false, "description": "Comma-separated list of space kinds to filter on, among `system`, `global`, `regular` and `project`. Defaults to `system,global,regular` — projects must be requested explicitly.", "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/{tId}": { "get": { "summary": "Get a trigger", "description": "Get one agent trigger (scheduled run or webhook) by id. Requires a workspace admin API\nkey.\n", "tags": [ "Triggers" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "path", "name": "tId", "required": true, "description": "ID of the trigger", "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "The trigger", "content": { "application/json": { "schema": { "type": "object", "properties": { "trigger": { "$ref": "#/components/schemas/Trigger" } } } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. Requires a workspace admin API key." }, "404": { "description": "Workspace or trigger not found." } } } }, "/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}/triggers": { "get": { "summary": "List triggers", "description": "List the agent triggers (scheduled runs and webhooks) configured across the workspace\nidentified by {wId}. Requires a workspace admin API key.\n", "tags": [ "Triggers" ], "parameters": [ { "in": "path", "name": "wId", "required": true, "description": "ID of the workspace", "schema": { "type": "string" } }, { "in": "query", "name": "kind", "required": false, "description": "Filter by trigger kind", "schema": { "type": "string", "enum": [ "schedule", "webhook" ] } }, { "in": "query", "name": "limit", "required": false, "description": "Maximum number of triggers to return (default 50, max 100)", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "description": "Number of triggers to skip, for pagination", "schema": { "type": "integer" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "The workspace's triggers", "content": { "application/json": { "schema": { "type": "object", "properties": { "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/Trigger" } } } } } } }, "400": { "description": "Bad Request. Invalid query parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. Requires a workspace admin API key." }, "404": { "description": "Workspace not found." } } } } }, "components": { "schemas": { "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" }, "selectedSpaceIds": { "type": "array", "items": { "type": "string" } }, "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": [] }, "skills": { "type": "array", "description": "Skills attached to the agent. Returned by the agent GET endpoints (list and single-agent) whatever the requested variant. Empty both for an agent with no skill and for an agent whose details were redacted for the caller (canRead false).", "items": { "$ref": "#/components/schemas/AgentSkill" } }, "tags": { "type": "array", "description": "Tags attached to the agent", "items": { "type": "object", "properties": { "sId": { "type": "string", "example": "3f9d1c7a5b" }, "name": { "type": "string", "example": "Support" }, "kind": { "type": "string", "enum": [ "standard", "protected" ] } } } }, "requestedSpaceIds": { "type": "array", "description": "Identifiers of the spaces the agent needs access to", "items": { "type": "string" }, "example": [ "vlt_a1b2c3d4e5" ] }, "maxStepsPerRun": { "type": "integer", "example": 10 }, "templateId": { "type": "string", "nullable": true, "description": "ID of the template used for this configuration", "example": "b4e2f1a9c7" } } }, "AgentSkill": { "type": "object", "description": "A skill attached to an agent configuration.", "properties": { "sId": { "type": "string", "description": "Unique string identifier for the skill", "example": "skill_abc123" }, "name": { "type": "string", "description": "Name of the skill", "example": "Customer Support" } } }, "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", "items": { "type": "object", "properties": { "generatedFiles": { "type": "array", "description": "Files generated by this action. Path-backed files have `fileId: null`\nand can be downloaded through the conversation files endpoint using\n`filePath`.\n", "items": { "type": "object", "properties": { "fileId": { "type": "string", "nullable": true, "description": "Dust file id for DB-backed files, or null for path-backed files." }, "filePath": { "type": "string", "description": "Canonical scoped path for path-backed files, as surfaced by agent file system tools." }, "title": { "type": "string" }, "contentType": { "type": "string" }, "snippet": { "type": "string", "nullable": true }, "hidden": { "type": "boolean" }, "isInProjectContext": { "type": "boolean" } } } } } } }, "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" }, "modelSelection": { "$ref": "#/components/schemas/ModelSelection" } } }, "ModelSelection": { "type": "object", "description": "Optional per-message model and reasoning-effort override applied to the\nmentioned agent(s). When omitted, each agent runs its configured model.\nA provider/model pair that is not authorized for the workspace is\nrejected with a 400 (`model_disabled`), it does not fall back to the\nagent's configured model. A malformed object, or an unknown reasoning\neffort, also results in a 400.\n", "required": [ "providerId", "modelId" ], "properties": { "providerId": { "type": "string", "description": "The model provider id (e.g. \"anthropic\", \"openai\", \"google_ai_studio\").", "example": "anthropic" }, "modelId": { "type": "string", "description": "The model id to run (e.g. \"claude-sonnet-4-20250514\").", "example": "claude-sonnet-4-20250514" }, "reasoningEffort": { "type": "string", "enum": [ "none", "light", "medium", "high" ], "description": "Optional reasoning effort. Honored only if the resolved model supports it.", "example": "medium" } } }, "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" }, "processedPath": { "type": "string", "nullable": true, "description": "Path of the plain-text sibling of this file inside the sandbox conversation mount (e.g. an audio transcript), when it has one.", "example": "conversation/voice.processed.txt" }, "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" }, "isRestricted": { "type": "boolean", "description": "Whether the space is restricted to specific groups" } } }, "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" }, "manuallyRequestedSpaceIds": { "type": "array", "items": { "type": "string" }, "description": "Subset of requestedSpaceIds that was selected by hand rather than derived from the skill's tools, knowledge or nested skills\n" }, "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" } } } }, "canRead": { "type": "boolean", "description": "Whether the authenticated actor can read the skill's instructions, tools and files. False when they were redacted for a workspace admin who is not a member of every space the skill requires." }, "canWrite": { "type": "boolean", "description": "Whether the authenticated actor can edit the skill" }, "isDefault": { "type": "boolean", "deprecated": true, "description": "Whether this skill is enabled by default. Deprecated, use availability instead." }, "availability": { "type": "string", "enum": [ "editors", "workspace_users", "users_and_agents" ], "description": "Who the skill is available to (users_and_agents makes it discoverable by agents)" }, "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", "required": [ "isRestrictedToSkills" ], "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" }, "isRestrictedToSkills": { "type": "boolean", "description": "Whether the MCP server view can only be used through skills", "example": false }, "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" } } } } }, "Trigger": { "type": "object", "required": [ "id", "sId", "name", "agentConfigurationId", "kind", "status", "createdAt", "executionMode", "configuration" ], "properties": { "id": { "type": "integer", "example": 12345 }, "sId": { "type": "string", "description": "Unique string identifier for the trigger", "example": "0ec9852c2f" }, "name": { "type": "string", "example": "Daily summary" }, "agentConfigurationId": { "type": "string", "description": "sId of the agent this trigger runs", "example": "8f3a1c2d9e" }, "kind": { "type": "string", "enum": [ "schedule", "webhook" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled", "disabled_by_manager", "relocating", "downgraded" ] }, "createdAt": { "type": "integer", "example": 1625097600 }, "customPrompt": { "type": "string", "nullable": true }, "naturalLanguageDescription": { "type": "string", "nullable": true }, "executionMode": { "type": "string", "enum": [ "user_pool", "workspace_pool" ] }, "configuration": { "type": "object", "description": "For `kind: schedule`, either a cron config (`cron`, `timezone`) or an interval\nconfig (`intervalDays`, `dayOfWeek`, `hour`, `minute`, `timezone`). For\n`kind: webhook`, `{ includePayload, event?, filter? }`.\n" }, "webhookSource": { "type": "object", "nullable": true, "description": "Present only for `kind: webhook` triggers", "properties": { "name": { "type": "string" }, "provider": { "type": "string", "example": "github" } } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Your DUST API key is a Bearer token." } } } }