openapi: 3.0.0 info: title: Dust Agents API version: 1.0.2 description: Manage Dust agent configurations — list, retrieve, update, archive, search, and export agents as YAML. contact: name: Dust Support url: https://docs.dust.tt license: name: MIT url: https://github.com/dust-tt/dust/blob/main/LICENSE servers: - url: https://dust.tt description: Dust.tt API (us-central1) - url: https://eu.dust.tt description: Dust.tt API (europe-west1) tags: - name: Agents description: Agent configurations paths: /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: - all: Retrieves all non-private agents (default if not authenticated) - list: Retrieves all active agents accessible to the user (default if authenticated) - published: Retrieves all agents with published scope - global: Retrieves all global agents - favorites: Retrieves all agents marked as favorites by the user (only available to authenticated users) ' schema: type: string enum: - all - list - workspace - published - global - favorites - in: query name: withAuthors required: false description: When set to 'true', includes recent authors information for each agent schema: type: string enum: - 'true' - 'false' security: - BearerAuth: [] responses: '200': description: Agent configurations for the workspace content: application/json: schema: type: object properties: agentConfigurations: type: array items: $ref: '#/components/schemas/AgentConfiguration' description: Array of agent configurations, optionally including lastAuthors if withAuthors=true '400': description: Bad Request. Missing or invalid parameters. '401': description: Unauthorized. Invalid or missing authentication token, or attempting to access restricted views without authentication. '404': description: Workspace not found. '405': description: Method not supported. Only GET is expected. '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. '405': description: Method not supported. Only GET is expected. '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. '405': description: Method not supported. Only GET or PATCH is expected. '500': description: Internal Server Error. patch: summary: Update Agent Configuration description: Update the agent configuration identified by {sId} in the workspace identified by {wId}. tags: - Agents parameters: - in: path name: wId required: true description: ID of the workspace schema: type: string - in: path name: sId required: true description: ID of the agent configuration schema: type: string requestBody: required: true content: application/json: schema: type: object properties: userFavorite: type: boolean agent: type: object properties: handle: type: string description: type: string scope: type: string enum: - visible - hidden avatar_url: type: string max_steps_per_run: type: number visualization_enabled: type: boolean instructions: type: string generation_settings: type: object properties: model_id: type: string provider_id: type: string temperature: type: number reasoning_effort: type: string tags: type: array items: type: object properties: name: type: string kind: type: string enum: - standard - protected editors: type: array items: type: object properties: user_id: type: string email: type: string full_name: type: string skills: type: array description: Replaces the skills enabled on the agent configuration. items: type: object required: - sId - name properties: sId: type: string name: type: string toolset: type: array items: type: object properties: name: type: string description: type: string type: type: string enum: - MCP configuration: type: object security: - BearerAuth: [] responses: '200': description: Successfully updated agent configuration content: application/json: schema: type: object properties: agentConfiguration: $ref: '#/components/schemas/AgentConfiguration' skippedActions: type: array items: type: object properties: name: type: string reason: type: string '400': description: Bad Request. Invalid or missing parameters. '401': description: Unauthorized. Invalid or missing authentication token. '404': description: Agent configuration not found. '405': description: Method not supported. Only GET or PATCH is expected. '500': description: Internal Server Error. delete: summary: Archive Agent Configuration description: Archive the agent configuration identified by {sId} in the workspace identified by {wId}. The agent is soft-archived and triggers/editor-group memberships associated with it are disabled. tags: - Agents parameters: - in: path name: wId required: true description: ID of the workspace schema: type: string - in: path name: sId required: true description: ID of the agent configuration schema: type: string security: - BearerAuth: [] responses: '200': description: Successfully archived agent configuration content: application/json: schema: type: object properties: success: type: boolean '400': description: Bad Request. Invalid or missing parameters. '401': description: Unauthorized. Invalid or missing authentication token. '403': description: Forbidden. The caller is not allowed to archive this agent. '404': description: Agent configuration not found. '405': description: Method not supported. Only GET, PATCH or DELETE is expected. '500': description: Internal Server Error. /api/v1/w/{wId}/assistant/agent_configurations/import: post: summary: Import Agent Configuration description: Create a new agent configuration from a JSON body matching the agent config schema. tags: - Agents parameters: - in: path name: wId required: true description: ID of the workspace schema: type: string requestBody: required: true content: application/json: schema: type: object required: - agent - instructions - generation_settings - tags - editors - toolset properties: agent: type: object required: - handle - description - scope - max_steps_per_run - visualization_enabled properties: handle: type: string description: type: string scope: type: string enum: - visible - hidden avatar_url: type: string max_steps_per_run: type: number visualization_enabled: type: boolean instructions: type: string generation_settings: type: object properties: model_id: type: string provider_id: type: string temperature: type: number reasoning_effort: type: string tags: type: array items: type: object properties: name: type: string kind: type: string enum: - standard - protected editors: type: array items: type: object properties: user_id: type: string email: type: string full_name: type: string toolset: type: array items: type: object properties: name: type: string description: type: string type: type: string enum: - MCP configuration: type: object security: - BearerAuth: [] responses: '200': description: Successfully created agent configuration content: application/json: schema: type: object properties: agentConfiguration: $ref: '#/components/schemas/AgentConfiguration' skippedActions: type: array items: type: object properties: name: type: string reason: type: string '400': description: Bad Request. Invalid request body. '401': description: Unauthorized. Invalid or missing authentication token. '405': description: Method not supported. Only POST is expected. '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. '405': description: Method not supported. Only GET is expected. '500': description: Internal Server Error. components: schemas: AgentConfiguration: type: object properties: id: type: integer example: 12345 sId: type: string description: Unique string identifier for the agent configuration example: 7f3a9c2b1e version: type: integer example: 2 versionCreatedAt: type: string nullable: true description: Timestamp of when the version was created example: '2023-06-15T14:30:00Z' versionAuthorId: type: string nullable: true description: ID of the user who created this version example: 0ec9852c2f name: type: string description: Name of the agent configuration example: Customer Support Agent description: type: string description: Description of the agent configuration example: An AI agent designed to handle customer support inquiries instructions: type: string nullable: true description: Instructions for the agent example: Always greet the customer politely and try to resolve their issue efficiently. pictureUrl: type: string description: URL of the agent's picture example: https://example.com/agent-images/support-agent.png status: type: string description: Current status of the agent configuration example: active scope: type: string description: Scope of the agent configuration example: workspace userFavorite: type: boolean description: Status of the user favorite for this configuration example: true model: type: object properties: providerId: type: string description: ID of the model provider example: openai modelId: type: string description: ID of the specific model example: gpt-4 temperature: type: number example: 0.7 actions: type: array example: [] maxStepsPerRun: type: integer example: 10 templateId: type: string nullable: true description: ID of the template used for this configuration example: b4e2f1a9c7 securitySchemes: BearerAuth: type: http scheme: bearer description: Your DUST API key is a Bearer token.