---
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. If the requested model is not available to the workspace, the agent's configured model is used instead. An unknown provider, model, or reasoning effort 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/versions/5834d690c29d/schema)