COcoder
Chats

Create chat

Changed on
post/api/v2/chats

Request

  • Base URL
    / (relative, and the document was published on a file host, not at the API’s origin)
  • URL
    /api/v2/chats
  • Auth
    API key in header Coder-Session-Token

Request body

client_type'ui' | 'api'
labelsobject
mcp_server_idsstring[]
model_config_idstring uuid
organization_idstring uuid
owner_idstring uuid

OwnerID makes another user the chat owner. It defaults to the caller. The chat runs with the owner's credentials, so setting it requires site-wide authority over that user.

plan_mode'plan'
project_idstring uuid
reasoning_effortstring
system_promptstring
titlestring

Title, when set, is stored as the user title and automatic title generation does not run. It is trimmed and must then be non-empty and at most 200 Unicode code points (MaxChatTitleRunes), else the request fails with 400. When omitted, the title is derived from the first prompt and may later be replaced by a generated title.

workspace_idstring uuid

Response

Created

agent_idstring uuid
archivedboolean
build_idstring uuid
childrenCodersdkChat[] circular
client_type'ui' | 'api'
created_atstring date-time
has_unreadboolean

HasUnread is true when assistant messages exist beyond the owner's read cursor, which updates on stream connect and disconnect and via UpdateChatRequest.Read.

idstring uuid
labelsobject
last_model_config_idstring uuid
last_reasoning_effortstring
last_turn_summarystring
mcp_server_idsstring[]
organization_idstring uuid
owner_idstring uuid
owner_namestring
owner_usernamestring
parent_chat_idstring uuid
pin_orderinteger
plan_mode'plan'
project_idstring uuid
queued_for_capacityboolean

QueuedForCapacity reports that the chat is waiting for a concurrent agent slot. Single-chat reads derive it; list responses leave it false.

root_chat_idstring uuid
sharedboolean

Shared is true when this chat's root chat has explicit user or group ACL entries.

status'waiting' | 'running' | 'error' | 'requires_action' | 'interrupting' | 'paused'
summarystring

Summary is the persisted whole-chat summary, generated in the background. It is nil until the first summary has been produced.

titlestring
title_source'fallback' | 'generated' | 'user'
title_updated_atstring date-time

TitleUpdatedAt orders title changes. Title writes do not change UpdatedAt.

updated_atstring date-time
warningsstring[]
workspace_idstring uuid

Changes