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

# Create a message

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

## Request

- Base URL: `https://dust.tt`
- URL: `https://dust.tt/api/v1/w/{wId}/assistant/conversations/{cId}/messages`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/dust-tt/apis/dust-api-documentation/docs/api/v1/w/:wId/assistant/conversations/:cId/messages/post.ts> (a function with typed inputs; its response is checked against the schema)

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

## Path parameters

- `wId` string, required
- `cId` string, required

## Request body

- Message
  - `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[]
    - `excludedRetrievalTags` string[], nullable: Data source tags to exclude from retrieval for this run, as opaque `key:value` strings.
    - `hostSelection` string, nullable: What the user had selected in the app hosting Dust when sending the message, e.g. `Sheet1!C5:D6` in Excel. Stored with the message and shown to the agent in that message's metadata.
    - `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' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'maximal' | 'light': Optional reasoning effort. Honored only if the resolved model supports it. `light` is a deprecated alias of `low`.

## Response `200`

Message created successfully.

- Message
  - `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[]
    - `excludedRetrievalTags` string[], nullable: Data source tags to exclude from retrieval for this run, as opaque `key:value` strings.
    - `hostSelection` string, nullable: What the user had selected in the app hosting Dust when sending the message, e.g. `Sheet1!C5:D6` in Excel. Stored with the message and shown to the agent in that message's metadata.
    - `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' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'maximal' | 'light': Optional reasoning effort. Honored only if the resolved model supports it. `light` is a deprecated alias of `low`.

## Other responses

- `400`: Bad Request. Missing or invalid parameters.
- `401`: Unauthorized. Invalid or missing authentication token.
- `403`: Forbidden. Workspace or usage limits exceeded, or access denied.
- `429`: Rate limit exceeded.
- `500`: Internal Server Error.

## Changes

- **2026-10-21** `abb1c0993938`: 2 info
  - added the new optional request property `context/hostSelection`
  - added the optional property `context/hostSelection` to the response with the `200` status
- **2026-10-20** `1b8b5232a3e1`: 2 info
  - added the new optional request property `context/excludedRetrievalTags`
  - added the optional property `context/excludedRetrievalTags` to the response with the `200` status
- **2026-09-27** `acd9e7f27b34`: 4 warning, 4 info
  - added the new `low` enum value to the `modelSelection/reasoningEffort` response property for the response status `200`
  - added the new `maximal` enum value to the `modelSelection/reasoningEffort` response property for the response status `200`
  - added the new `minimal` enum value to the `modelSelection/reasoningEffort` response property for the response status `200`
  - added the new `xhigh` enum value to the `modelSelection/reasoningEffort` response property for the response status `200`
  - …4 more
- **2026-07-20** `89dbf1251af2`: 2 info
  - added the new optional request property `context/selectedSpaceIds`
  - added the optional property `context/selectedSpaceIds` to the response with the `200` status
- **2026-07-17** `9aa33b463bf9`: 2 info
  - added the new optional request property `modelSelection`
  - added the optional property `modelSelection` to the response with the `200` status

[Operation history](https://skmtc.dev/dust-tt/apis/dust-api-documentation/changes/api/v1/w/:wId/assistant/conversations/:cId/messages/post.md)

---

[API](https://skmtc.dev/dust-tt/apis/dust-api-documentation.md) - [All operations](https://skmtc.dev/dust-tt/apis/dust-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/dust-tt/apis/dust-api-documentation/revisions/abb1c0993938?raw)