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

# Create a conversation

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

Create a new conversation, optionally with an initial user message and content fragments.

## Path parameters

- `wId` string, required

## Request body

- object
  - `title` string, nullable
  - `visibility` 'unlisted' | 'deleted' | 'test'
  - `spaceId` string, nullable
  - `message` object
    - `content` string
    - `mentions` PrivateMention[]
      - `configurationId` string — Agent configuration sId (for agent mentions)
      - `type` 'user' — Present only for user mentions
      - `userId` string — User sId (for user mentions)
    - `context` object
      - `timezone` string
      - `profilePictureUrl` string, nullable
      - `origin` string, nullable
      - `clientSideMCPServerIds` string[]
      - `selectedMCPServerViewIds` string[]
      - `selectedSpaceIds` string[]
  - `contentFragments` object[]
  - `metadata` object, nullable
  - `selectedSpaceIds` string[]
  - `skipToolsValidation` boolean

## Response `200`

Successfully created conversation

- object
  - `conversation` PrivateFullConversation — Conversation without content, used in list responses.
    - `id` integer, required
    - `created` integer, required — Unix timestamp of creation
    - `updated` integer, required — Unix timestamp of last update
    - `unread` boolean
    - `lastReadMs` integer, nullable
    - `actionRequired` boolean — Whether the conversation requires user action
    - `hasError` boolean
    - `sId` string, required
    - `title` string, nullable
    - `spaceId` string, nullable — ID of the space the conversation belongs to (for project conversations)
    - `triggerId` string, nullable
    - `depth` integer, required — Conversation depth (for agent handover chains)
    - `metadata` object
    - `requestedSpaceIds` string[]
    - `forkingData` PrivateConversationForkingData
      - `forkedFrom` PrivateConversationForkedFrom
        - `parentConversationId` string, required
        - `parentConversationTitle` string, nullable, required
        - `sourceMessageId` string, required
        - `branchedAt` integer, required
        - `user` PrivateConversationForkUser, required
          - `sId` string
          - `id` integer
          - `createdAt` integer
          - `provider` 'auth0' | 'github' | 'google' | 'okta' | 'samlp' | 'waad', nullable
          - `username` string
          - `email` string
          - `firstName` string
          - `lastName` string, nullable
          - `fullName` string
          - `image` string, nullable
          - `lastLoginAt` integer, nullable
        - `fileCopyStatus` 'pending' | 'done', required
      - `forkedChildren` PrivateConversationForkedChild[]
        - `childConversationId` string
        - `childConversationTitle` string, nullable
        - `sourceMessageId` string
        - `branchedAt` integer
        - `user` PrivateConversationForkUser
          - `sId` string
          - `id` integer
          - `createdAt` integer
          - `provider` 'auth0' | 'github' | 'google' | 'okta' | 'samlp' | 'waad', nullable
          - `username` string
          - `email` string
          - `firstName` string
          - `lastName` string, nullable
          - `fullName` string
          - `image` string, nullable
          - `lastLoginAt` integer, nullable
    - `owner` PrivateWorkspace — Workspace as returned by the private API, includes SSO and provider settings.
      - `id` integer, required
      - `sId` string, required
      - `name` string, required
      - `role` 'admin' | 'builder' | 'user' | 'none', required
      - `segmentation` string, nullable
      - `whiteListedProviders` string[], nullable — Allowed model provider IDs
      - `defaultEmbeddingProvider` string, nullable
      - `ssoEnforced` boolean
      - `regionalModelsOnly` boolean, required — When true, only models whose regionalAvailability includes the workspace's region are usable.
      - `metadata` object, nullable
    - `visibility` 'unlisted' | 'deleted' | 'test'
    - `content` array[] — Array of message arrays (versions/retries)
      - union[]
        - union
          - PrivateUserMessage — A user message in a conversation.
            - `id` integer
            - `type` 'user_message', required
            - `sId` string, required
            - `created` integer, required
            - `visibility` 'visible' | 'deleted'
            - `version` integer, required
            - `rank` integer, required
            - `branchId` string, nullable — Legacy, always null. Branches were removed.
            - `user` object, nullable — The user who sent the message
              - …
            - `mentions` PrivateMention[]
              - …
            - `richMentions` PrivateRichMentionWithStatus[]
              - …
            - `content` string, required
            - `context` PrivateUserMessageContext — Context metadata for a user message.
              - …
            - `reactions` PrivateReaction[]
              - …
          - PrivateAgentMessage — An agent message in a conversation.
            - `id` integer
            - `agentMessageId` integer
            - `type` 'agent_message', required
            - `sId` string, required
            - `created` integer
            - `completedTs` integer, nullable
            - `visibility` 'visible' | 'deleted'
            - `version` integer, required
            - `rank` integer, required
            - `branchId` string, nullable — Legacy, always null. Branches were removed.
            - `parentMessageId` string, required
            - `parentAgentMessageId` string, nullable — If handover, the agent message that summoned this agent
            - `status` 'created' | 'succeeded' | 'failed' | 'cancelled', required
            - `content` string, nullable
            - `chainOfThought` string, nullable
            - `error` object, nullable
              - …
            - `configuration` PrivateLightAgentConfiguration — Agent configuration as returned by the private list endpoint.
              - …
            - `actions` object[] — MCP actions executed by the agent
              - …
            - `contents` object[]
              - …
            - `skipToolsValidation` boolean
            - `richMentions` PrivateRichMentionWithStatus[]
              - …
            - `completionDurationMs` integer, nullable
            - `reactions` PrivateReaction[]
              - …
            - `costCredits` integer, nullable — Cost of producing this agent message, in credits (intelligence + tool credits). Null when no billable usage is attributed to the message.
            - `subAgentCostCredits` number, nullable — Aggregated credit cost of all sub-agents (run_agent / agent_handover) spawned recursively by this message. Computed only on single-message fetches. Null otherwise.
            - `resolvedModel` object, nullable — Model triplet used to generate the message. Null when the agent ran its configured model (legacy).
              - …
            - `modelResolutionMethod` 'agent' | 'user' | 'auto', nullable — How resolvedModel was chosen - agent (configured model), user (per-message picker), or auto (routed through the auto model). Null (legacy).
          - PrivateContentFragment — A content fragment (file or content node attachment) in a conversation.
            - `type` 'content_fragment', required
            - `id` integer
            - `sId` string, required
            - `created` integer
            - `visibility` 'visible' | 'deleted'
            - `version` integer
            - `rank` integer
            - `title` string, required
            - `contentType` string, required — MIME type of the content
            - `sourceUrl` string, nullable
            - `context` object
              - …
            - `contentFragmentId` string
            - `contentFragmentVersion` 'superseded' | 'latest'
            - `contentFragmentType` 'file' | 'content_node', required — Whether this is a file upload or a content node reference
            - `expiredReason` 'data_source_deleted', nullable
            - `fileId` string, nullable — Present for file content fragments
            - `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.
            - `snippet` string, nullable
            - `textUrl` string, nullable
            - `textBytes` integer, nullable
            - `nodeId` string, nullable — Present for content node fragments
            - `nodeDataSourceViewId` string, nullable
          - PrivateCompactionMessage — A compaction message summarizing earlier conversation content.
            - `type` 'compaction_message', required
            - `id` integer
            - `compactionMessageId` integer
            - `sId` string, required
            - `created` integer, required
            - `visibility` 'visible' | 'deleted'
            - `version` integer, required
            - `rank` integer, required
            - `branchId` string, nullable — Legacy, always null. Branches were removed.
            - `sourceConversationId` string, nullable
            - `status` 'created' | 'succeeded' | 'failed', required
            - `content` string, nullable — Compacted summary. Null while status is "created".
  - `message` PrivateUserMessage — A user message in a conversation.
    - `id` integer
    - `type` 'user_message', required
    - `sId` string, required
    - `created` integer, required
    - `visibility` 'visible' | 'deleted'
    - `version` integer, required
    - `rank` integer, required
    - `branchId` string, nullable — Legacy, always null. Branches were removed.
    - `user` object, nullable — The user who sent the message
      - `sId` string
      - `username` string
      - `fullName` string
      - `image` string, nullable
    - `mentions` PrivateMention[]
      - `configurationId` string — Agent configuration sId (for agent mentions)
      - `type` 'user' — Present only for user mentions
      - `userId` string — User sId (for user mentions)
    - `richMentions` PrivateRichMentionWithStatus[]
      - `id` string, required
      - `type` 'agent' | 'user', required
      - `label` string, required
      - `pictureUrl` string, required
      - `description` string, required
      - `userFavorite` boolean
      - `dismissed` boolean, required
      - `status` 'pending_conversation_access' | 'pending_project_membership' | 'approved' | 'rejected' | 'user_restricted_by_conversation_access' | 'agent_restricted_by_space_usage', required
    - `content` string, required
    - `context` PrivateUserMessageContext — Context metadata for a user message.
      - `username` string, required
      - `fullName` string, nullable
      - `email` string, nullable
      - `profilePictureUrl` string, nullable
      - `timezone` string, required
      - `origin` 'web' | 'project_kickoff' | 'extension' | 'agent_sidekick' | 'api' | 'cli' | 'cli_programmatic' | 'email' | 'excel' | 'gsheet' | 'make' | 'n8n' | 'powerpoint' | 'raycast' | 'slack' | 'slack_workflow' | 'teams' | 'transcript' | 'triggered_programmatic' | 'triggered' | 'wakeup' | 'zapier' | 'zendesk' | 'onboarding_conversation', required
      - `selectedSpaceIds` string[]
    - `reactions` PrivateReaction[]
      - `emoji` string, required
      - `users` object[], required
        - `userId` string, nullable
        - `username` string
        - `fullName` string, nullable
  - `contentFragments` PrivateContentFragment[]
    - `type` 'content_fragment', required
    - `id` integer
    - `sId` string, required
    - `created` integer
    - `visibility` 'visible' | 'deleted'
    - `version` integer
    - `rank` integer
    - `title` string, required
    - `contentType` string, required — MIME type of the content
    - `sourceUrl` string, nullable
    - `context` object
      - `username` string, nullable
      - `fullName` string, nullable
      - `email` string, nullable
      - `profilePictureUrl` string, nullable
    - `contentFragmentId` string
    - `contentFragmentVersion` 'superseded' | 'latest'
    - `contentFragmentType` 'file' | 'content_node', required — Whether this is a file upload or a content node reference
    - `expiredReason` 'data_source_deleted', nullable
    - `fileId` string, nullable — Present for file content fragments
    - `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.
    - `snippet` string, nullable
    - `textUrl` string, nullable
    - `textBytes` integer, nullable
    - `nodeId` string, nullable — Present for content node fragments
    - `nodeDataSourceViewId` string, nullable

## Other responses

- `401` — Unauthorized

---

[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)