---
title: "Create a new conversation"
method: POST
path: "/api/v1/w/{wId}/assistant/conversations"
tags: ["Conversations"]
---

# Create a new conversation

`POST /api/v1/w/{wId}/assistant/conversations`

Create a new conversation in the workspace identified by {wId}.

## Path parameters

- `wId` string, required

## Request body

- object
  - `message` Message, required
    - `content` string, required — The content of the message. Should not be empty.
    - `mentions` Mention[], required — Empty array is accepted but won't trigger any agent.
      - `configurationId` string — ID of the mentioned agent configuration
    - `context` Context
      - `username` string, required — Username in the current context
      - `timezone` string, required — User's timezone
      - `fullName` string — User's full name in the current context
      - `email` string — User's email in the current context
      - `profilePictureUrl` string — URL of the user's profile picture
      - `selectedSpaceIds` string[]
      - `agenticMessageData` object
        - `type` 'run_agent' | 'agent_handover' — Type of the agentic message
        - `originMessageId` string — ID of the origin message
    - `modelSelection` ModelSelection — Optional per-message model and reasoning-effort override applied to the mentioned agent(s). When omitted, each agent runs its configured model. A provider/model pair that is not authorized for the workspace is rejected with a 400 (`model_disabled`), it does not fall back to the agent's configured model. A malformed object, or an unknown reasoning effort, also results in a 400.
      - `providerId` string, required — The model provider id (e.g. "anthropic", "openai", "google_ai_studio").
      - `modelId` string, required — The model id to run (e.g. "claude-sonnet-4-20250514").
      - `reasoningEffort` 'none' | 'light' | 'medium' | 'high' — Optional reasoning effort. Honored only if the resolved model supports it.
  - `contentFragments` ContentFragment[] — The list of content fragments to attach to this conversation (optional)
    - `title` string, required — The title of the content fragment
    - `content` string — The content of the content fragment (optional if `fileId` is set)
    - `contentType` string — The content type of the content fragment (optional if `fileId` is set)
    - `url` string — The URL of the content fragment
    - `fileId` string — The id of the previously uploaded file (optional if `content` and `contentType` are set)
    - `path` string, nullable — Path of this file inside the sandbox conversation mount.
    - `processedPath` string, nullable — Path of the plain-text sibling of this file inside the sandbox conversation mount (e.g. an audio transcript), when it has one.
    - `skipFileProcessing` boolean — Whether upload-time file processing was skipped.
    - `nodeId` string — The id of the content node (optional if `content` and `contentType` are set)
    - `nodeDataSourceViewId` string — The id of the data source view (optional if `content` and `contentType` are set)
    - `context` Context
      - `username` string, required — Username in the current context
      - `timezone` string, required — User's timezone
      - `fullName` string — User's full name in the current context
      - `email` string — User's email in the current context
      - `profilePictureUrl` string — URL of the user's profile picture
      - `selectedSpaceIds` string[]
      - `agenticMessageData` object
        - `type` 'run_agent' | 'agent_handover' — Type of the agentic message
        - `originMessageId` string — ID of the origin message
  - `title` string — The title of the conversation
  - `skipToolsValidation` boolean — Whether to skip the tools validation of the agent messages triggered by this user message (optional, defaults to false)
  - `blocking` boolean — 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.
  - `spaceId` string — The sId of the space (project) in which to create the conversation (optional). If not provided, the conversation is created outside projects

## Response `200`

Conversation created successfully.

- Conversation
  - `conversation` object
    - `id` integer
    - `created` integer
    - `sId` string — Unique string identifier for the conversation
    - `owner` Workspace
      - `id` integer
      - `sId` string — Unique string identifier for the workspace
      - `name` string — Name of the workspace
      - `role` string — User's role in the workspace
      - `segmentation` string, nullable — Segmentation information for the workspace
      - `flags` string[]
      - `ssoEnforced` boolean
      - `regionalModelsOnly` boolean, required — When true, only models whose regionalAvailability includes the workspace's region are usable.
      - `whiteListedProviders` string[]
      - `defaultEmbeddingProvider` string, nullable — Default provider for embeddings in the workspace
    - `title` string — Title of the conversation
    - `visibility` string — Visibility setting of the conversation
    - `content` array[]
      - object[]
        - `id` integer
        - `sId` string — Unique string identifier for the message
        - `type` string — Type of the message
        - `visibility` string — Visibility setting of the message
        - `version` integer
        - `created` integer
        - `user` User
          - `sId` string — Unique string identifier for the user
          - `id` integer
          - `createdAt` integer
          - `username` string — User's chosen username
          - `email` string — User's email address
          - `firstName` string — User's first name
          - `lastName` string — User's last name
          - `fullName` string — User's full name
          - `provider` string — Authentication provider used by the user
          - `image` string — URL of the user's profile image
        - `mentions` Mention[]
          - `configurationId` string — ID of the mentioned agent configuration
        - `content` string — Content of the message
        - `context` Context
          - `username` string, required — Username in the current context
          - `timezone` string, required — User's timezone
          - `fullName` string — User's full name in the current context
          - `email` string — User's email in the current context
          - `profilePictureUrl` string — URL of the user's profile picture
          - `selectedSpaceIds` string[]
          - `agenticMessageData` object
            - `type` 'run_agent' | 'agent_handover' — Type of the agentic message
            - `originMessageId` string — ID of the origin message
        - `agentMessageId` integer
        - `parentMessageId` string — ID of the parent message
        - `status` string — Status of the message
        - `actions` object[]
          - `generatedFiles` object[] — Files generated by this action. Path-backed files have `fileId: null` and can be downloaded through the conversation files endpoint using `filePath`.
            - `fileId` string, nullable — Dust file id for DB-backed files, or null for path-backed files.
            - `filePath` string — Canonical scoped path for path-backed files, as surfaced by agent file system tools.
            - `title` string
            - `contentType` string
            - `snippet` string, nullable
            - `hidden` boolean
            - `isInProjectContext` boolean
        - `chainOfThought` string, nullable — Chain of thought for the message
        - `rawContents` object[]
          - `step` integer
          - `content` string — Content for each step
        - `error` string, nullable — Error message, if any
        - `configuration` AgentConfiguration
          - `id` integer
          - `sId` string — Unique string identifier for the agent configuration
          - `version` integer
          - `versionCreatedAt` string, nullable — Timestamp of when the version was created
          - `versionAuthorId` string, nullable — ID of the user who created this version
          - `name` string — Name of the agent configuration
          - `description` string — Description of the agent configuration
          - `instructions` string, nullable — Instructions for the agent
          - `pictureUrl` string — URL of the agent's picture
          - `status` string — Current status of the agent configuration
          - `scope` string — Scope of the agent configuration
          - `userFavorite` boolean — Status of the user favorite for this configuration
          - `model` object
            - `providerId` string — ID of the model provider
            - `modelId` string — ID of the specific model
            - `temperature` number
          - `actions` unknown[]
            - unknown
          - `maxStepsPerRun` integer
          - `templateId` string, nullable — ID of the template used for this configuration

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `429` — Rate limit exceeded.
- `500` — Internal Server Error

---

[API](https://skmtc.net/dust-tt/apis/dust-api-documentation.md) · [All operations](https://skmtc.net/dust-tt/apis/dust-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dust-tt/dust-api-documentation/revisions/41617009c89a/schema)