Drive multi-turn conversations with Dust agents. Create conversations, post user messages, stream agent events over SSE, attach content fragments (file/page/snippet attachments), retrieve and download conversation-scoped files, submit and delete message feedback, and resolve @mention suggestions for agent routing.
openapi: 3.0.0
info:
title: Dust Conversations API
version: 1.0.2
description: Create and drive multi-turn conversations with Dust agents — post messages, stream events, manage content fragments,
gather feedback, and resolve mentions.
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: Conversations
description: Conversations
- name: Feedbacks
description: Message feedbacks
- name: Mentions
description: Mentions
paths:
/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)
'405':
description: Method not supported
/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.
'405':
description: Method not supported. Only GET is expected.
'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.
Requires authentication and read:conversation scope.
'
tags:
- Feedbacks
parameters:
- name: wId
in: path
description: Workspace ID
required: true
schema:
type: string
- name: cId
in: path
description: Conversation ID
required: true
schema:
type: string
security:
- BearerAuth: []
responses:
'200':
description: List of feedback entries for the conversation
content:
application/json:
schema:
type: object
properties:
feedbacks:
type: array
items:
type: object
properties:
messageId:
type: string
description: ID of the message that received feedback
agentMessageId:
type: number
description: ID of the agent message
userId:
type: number
description: ID of the user who gave feedback
thumbDirection:
type: string
enum:
- up
- down
description: Direction of the thumb feedback
content:
type: string
nullable: true
description: Optional feedback content/comment
createdAt:
type: number
description: Timestamp when feedback was created
agentConfigurationId:
type: string
description: ID of the agent configuration
agentConfigurationVersion:
type: number
description: Version of the agent configuration
isConversationShared:
type: boolean
description: Whether the conversation was shared
'400':
description: Invalid request parameters
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Conversation not found
'500':
description: Internal server error
/api/v1/w/{wId}/assistant/conversations/{cId}/files/{rel}:
get:
tags:
- Conversations
summary: Download a Conversation-Scoped File by Path
description: 'Download a file from a conversation''s file system by its scoped path. The path must
be conversation-scoped, i.e. start with `conversation/` (as surfaced by agent file
system tools). The file content is streamed directly from the conversation mount.
'
parameters:
- name: wId
in: path
required: true
description: ID of the workspace
schema:
type: string
- name: cId
in: path
required: true
description: ID of the conversation
schema:
type: string
- name: rel
in: path
required: true
description: 'Conversation-scoped file path, e.g. `conversation/foo.pdf` or
`conversation/subdir/foo.pdf`. The `conversation/` prefix is required; any other
scope prefix is rejected. Path traversal segments (`..`) are rejected.
'
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.
'405':
description: Method not supported.
/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.
'405':
description: Method not supported. Only GET is expected.
'500':
description: Internal Server Error.
patch:
summary: Update Conversation Read Status
description: Mark a conversation 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:
type: object
properties:
read:
type: boolean
responses:
'200':
description: Conversation marked as read 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.
'405':
description: Method not supported. Only GET or PATCH is expected.
'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.
'405':
description: Method not supported. Only GET is expected.
'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
'405':
description: Method not allowed
'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)
'405':
description: Method not supported
/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.
Requires authentication and update:conversation scope.
'
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.
Requires authentication and update:conversation scope.
'
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
'405':
description: Method not allowed
'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.
Matches @agentName or @userName patterns against available agents and users.
'
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.
'405':
description: Method not supported. Only POST is expected.
'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.
'405':
description: Method not supported. Only GET is expected.
'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:
applic
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dust-tt/refs/heads/main/openapi/dust-conversations-api-openapi.yml