Dust Agents API

openapi: 3.2.0
info:
  title: DUST API Documentation Agents API
  version: 1.0.2
  description: The OpenAPI specification for the Dust.tt API
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://dust.tt
  description: Dust.tt API (us-central1)
- url: https://eu.dust.tt
  description: Dust.tt API (europe-west1)
tags:
- name: Agents
  description: Agent configurations
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)

          - 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.

          '
        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.
      operationId: getApiV1WByWIdAssistantAgentConfigurations
      x-operation-id-source: derived
  /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.
      operationId: getApiV1WByWIdAssistantAgentConfigurationsBySIdExportYaml
      x-operation-id-source: derived
  /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.
        '403':
          description: Forbidden. Only admins can access unpublished agents.
        '404':
          description: Agent configuration not found.
        '500':
          description: Internal Server Error.
      operationId: getApiV1WByWIdAssistantAgentConfigurationsBySId
      x-operation-id-source: derived
    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
                  description: Favorites the agent for the calling user. Requires a user; rejected with 400 when authenticated with a workspace API key.
                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, or userFavorite sent with a workspace API key.
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. Only admins can update agents.
        '404':
          description: Agent configuration not found.
        '500':
          description: Internal Server Error.
      operationId: patchApiV1WByWIdAssistantAgentConfigurationsBySId
      x-operation-id-source: derived
    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.
      operationId: deleteApiV1WByWIdAssistantAgentConfigurationsBySId
      x-operation-id-source: derived
  /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.
      operationId: postApiV1WByWIdAssistantAgentConfigurationsImport
      x-operation-id-source: derived
  /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}. Returns the global agents and the published agents the caller can access whose name contains the query, case-insensitively.
      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.
      operationId: getApiV1WByWIdAssistantAgentConfigurationsSearch
      x-operation-id-source: derived
components:
  schemas:
    AgentConfiguration:
      type: object
      properties:
        id:
          type: integer
          example: 12345
        agentModelId:
          type:
          - integer
          - 'null'
          description: Stable identifier of the agent across versions; null for global agents
          example: 6789
        sId:
          type: string
          description: Unique string identifier for the agent configuration
          example: 7f3a9c2b1e
        version:
          type: integer
          example: 2
        versionCreatedAt:
          type:
          - string
          - 'null'
          description: Timestamp of when the version was created
          example: '2023-06-15T14:30:00Z'
        versionAuthorId:
          type:
          - string
          - 'null'
          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
          - 'null'
          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
          - 'null'
          description: ID of the template used for this configuration
          example: b4e2f1a9c7
        ignoreCreditSpendThresholdAlert:
          type: boolean
          description: Whether the agent keeps running past the workspace credit spend threshold alert
          example: false
        canViewContent:
          type: boolean
          description: Whether the caller can view the agent's private fields (instructions, skills, tools); they are redacted when false
          example: false
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Your DUST API key is a Bearer token.
x-provenance:
  method: harvested
  publisher: Dust
  source: https://raw.githubusercontent.com/dust-tt/dust/refs/heads/main/front-api/public/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)