Skip to main content
127.8K
HomeReferenceREST APIChats

Chats

On this page

Programmatic API for Coder Agents (the user-facing "Coder Agents" / "Chats" product). Use these endpoints to create, list, and manage AI coding agent sessions.

Connect to chat workspace desktop via WebSockets

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/experimental/chats/{chat}/stream/desktop \ -H 'Coder-Session-Token: API_KEY'

GET /api/experimental/chats/{chat}/stream/desktop

Raw binary WebSocket stream of the chat workspace desktop. Experimental: this endpoint is subject to change.

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID

Responses

StatusMeaningDescriptionSchema
101Switching ProtocolsSwitching Protocols

To perform this operation, you must be authenticated. Learn more.

List chats

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats

Parameters

NameInTypeRequiredDescription
qquerystringfalseSearch query. Supports title:<substring> (case-insensitive, quote multi-word values), archived:bool, has_unread:bool, pr_status:<draft|open|merged|closed> as repeated or comma-separated values, source:<created_by_me|shared_with_me>, diff_url:<url> (quote values containing colons), pr:<number> (exact PR number match), repo:<owner/repo> (case-insensitive substring match against git remote origin or URL), pr_title:<text> (case-insensitive PR title substring), search:<text> (full-text search across chat titles, PR titles, PR numbers, and message bodies; message bodies match English word stems, e.g. refactor matches refactoring, and ignore English stopwords; titles and PR titles match whole words case-insensitively without stemming; quote multi-word values; cannot be combined with title, pr_title, or pr; a value that tokenizes to no searchable words, e.g. punctuation only, returns an empty list). Bare terms are not supported; use title:<value> or search:<value>.
labelqueryarray[string]falseFilter by label as key:value. Repeat for multiple (AND logic).
after_idquerystring(uuid)falseAfter ID
limitqueryintegerfalsePage limit
offsetqueryintegerfalsePage offset

Example responses

200 Response

[ { "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [ {} ], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" } ]

Responses

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.Chat

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» agent_idstring(uuid)false
» archivedbooleanfalse
» build_idstring(uuid)false
» childrencodersdk.ChatfalseChildren holds child (subagent) chats nested under this root chat. Always initialized to an empty slice so the JSON field is present as []. Child chats cannot create their own subagents, so nesting depth is capped at 1 and this slice is always empty for child chats.
» client_typecodersdk.ChatClientTypefalse
» contextcodersdk.ChatContextfalseContext reports the chat's pinned workspace-context state and whether it has drifted from the agent's latest pushed snapshot. Nil when the chat has no pinned context yet.
»» dirtybooleanfalseDirty is true when the agent's latest snapshot hash differs from the chat's pinned hash.
»» dirty_sincestring(date-time)falseDirty since is when drift was first detected; nil when not dirty.
»» errorstringfalseError is the snapshot-level error copied from the pinned snapshot (empty when healthy).
»» resourcesarrayfalseResources is the chat's pinned context (instruction files and skills) the prompt is built from, metadata only (no bodies). It is populated only on the single-chat GET response; list and watch payloads leave it nil to stay lightweight.
»»» errorstringfalseError explains a non-ok Status; empty when healthy. May also carry a non-fatal warning when Status is ok.
»»» kindcodersdk.ChatContextResourceKindfalse
»»» size_bytesintegerfalseSize bytes is the original payload size in bytes.
»»» skill_descriptionstringfalse
»»» skill_namestringfalseSkill name and SkillDescription are populated only for skill kinds.
»»» sourcestringfalseSource is the resource locator: the canonical file path for an instruction file, the skill directory for a skill, the file path for an MCP config, or the server name for an MCP server.
»»» statuscodersdk.ChatContextResourceStatusfalseStatus is the resource's health. Non-ok resources (invalid, unreadable, oversize, excluded) are still reported so the UI can surface why a resource was dropped from the prompt instead of silently omitting it; their body-specific fields (skill name, tools) are empty.
»»» toolsarrayfalseTools lists the tools exposed by an MCP server. Populated only for the mcp_server kind; nil otherwise.
»»»» descriptionstringfalseDescription is the tool's human-readable summary; may be empty.
»»»» namestringfalseName is the tool name with the <server>__ prefix the agent adds stripped, so it reads as the server exposes it.
» created_atstring(date-time)false
» diff_statuscodersdk.ChatDiffStatusfalse
»» additionsintegerfalse
»» approvedbooleanfalse
»» author_avatar_urlstringfalse
»» author_loginstringfalse
»» base_branchstringfalse
»» changed_filesintegerfalse
»» changes_requestedbooleanfalse
»» chat_idstring(uuid)false
»» commitsintegerfalse
»» deletionsintegerfalse
»» head_branchstringfalse
»» pr_numberintegerfalse
»» pull_request_draftbooleanfalse
»» pull_request_statestringfalse
»» pull_request_titlestringfalse
»» refreshed_atstring(date-time)false
»» reviewer_countintegerfalse
»» stale_atstring(date-time)false
»» urlstringfalse
» filesarrayfalse
»» created_atstring(date-time)false
»» idstring(uuid)false
»» mime_typestringfalse
»» namestringfalse
»» organization_idstring(uuid)false
»» owner_idstring(uuid)false
»» size_bytesintegerfalse
» has_unreadbooleanfalseHas unread is true when assistant messages exist beyond the owner's read cursor, which updates on stream connect and disconnect.
» idstring(uuid)false
» labelsobjectfalse
»» [any property]stringfalse
» last_errorcodersdk.ChatErrorfalse
»» detailstringfalseDetail is optional provider-specific context shown alongside the normalized error message when available.
»» kindcodersdk.ChatErrorKindfalseKind classifies the error for consistent client rendering.
»» messagestringfalseMessage is the normalized, user-facing error message.
»» providerstringfalseProvider identifies the upstream model provider when known.
»» retryablebooleanfalseRetryable reports whether the underlying error is transient.
»» status_codeintegerfalseStatus code is the best-effort upstream HTTP status code.
» last_model_config_idstring(uuid)false
» last_reasoning_effortstringfalse
» last_turn_summarystringfalse
» mcp_server_idsarrayfalse
» organization_idstring(uuid)false
» owner_idstring(uuid)false
» owner_namestringfalse
» owner_usernamestringfalse
» parent_chat_idstring(uuid)false
» pin_orderintegerfalse
» plan_modecodersdk.ChatPlanModefalse
» queued_for_capacitybooleanfalseQueued for capacity 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)false
» sharedbooleanfalseShared is true when this chat's root chat has explicit user or group ACL entries.
» statuscodersdk.ChatStatusfalse
» summarystringfalseSummary is the persisted whole-chat summary, generated in the background. It is nil until the first summary has been produced.
» titlestringfalse
» updated_atstring(date-time)false
» warningsarrayfalse
» workspace_idstring(uuid)false

Enumerated Values

PropertyValue(s)
client_typeapi, ui
kindauth, config, content_filter, generic, hook_denied, hook_dispatch_failed, instruction_file, mcp_config, mcp_server, missing_key, overloaded, provider_disabled, rate_limit, skill, stream_silence_timeout, timeout, usage_limit
statuserror, excluded, interrupting, invalid, ok, oversize, requires_action, running, unreadable, waiting
plan_modeplan

To perform this operation, you must be authenticated. Learn more.

Create chat

Code samples

# Example request using curl curl -X POST http://coder-server:8080/api/v2/chats \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

POST /api/v2/chats

Body parameter

{ "client_type": "ui", "content": [ { "content": "string", "end_line": 0, "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767", "file_name": "string", "start_line": 0, "text": "string", "type": "text" } ], "labels": { "property1": "string", "property2": "string" }, "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "plan_mode": "plan", "reasoning_effort": "string", "system_prompt": "string", "unsafe_dynamic_tools": [ { "description": "string", "input_schema": [ 0 ], "name": "string" } ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" }

Parameters

NameInTypeRequiredDescription
bodybodycodersdk.CreateChatRequesttrueCreate chat request

Example responses

201 Response

{ "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [ { "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" } ], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" }

Responses

StatusMeaningDescriptionSchema
201CreatedCreatedcodersdk.Chat
413Payload Too LargeRequest body exceeds 256 KiBcodersdk.Response

To perform this operation, you must be authenticated. Learn more.

List chats by workspace

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/by-workspace \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/by-workspace

Parameters

NameInTypeRequiredDescription
workspace_idsquerystringfalseComma-separated workspace IDs

Example responses

200 Response

{ "property1": "string", "property2": "string" }

Responses

StatusMeaningDescriptionSchema
200OKOKcoderd.chatsByWorkspaceResponse

To perform this operation, you must be authenticated. Learn more.

Get chat auto archive days

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/config/auto-archive-days \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/config/auto-archive-days

Example responses

200 Response

{ "auto_archive_days": 0 }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatAutoArchiveDaysResponse

To perform this operation, you must be authenticated. Learn more.

Update chat auto archive days

Code samples

# Example request using curl curl -X PUT http://coder-server:8080/api/v2/chats/config/auto-archive-days \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/chats/config/auto-archive-days

Body parameter

{ "auto_archive_days": 0 }

Parameters

NameInTypeRequiredDescription
bodybodycodersdk.UpdateChatAutoArchiveDaysRequesttrueRequest body

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.

Get chat debug logging setting

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/config/debug-logging \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/config/debug-logging

Example responses

200 Response

{ "allow_users": true, "forced_by_deployment": true }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatDebugLoggingAdminSettings

To perform this operation, you must be authenticated. Learn more.

Update chat debug logging setting

Code samples

# Example request using curl curl -X PUT http://coder-server:8080/api/v2/chats/config/debug-logging \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/chats/config/debug-logging

Body parameter

{ "allow_users": true }

Parameters

NameInTypeRequiredDescription
bodybodycodersdk.UpdateChatDebugLoggingAllowUsersRequesttrueRequest body

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.

Get chat debug retention days

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/config/debug-retention-days \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/config/debug-retention-days

Example responses

200 Response

{ "debug_retention_days": 0 }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatDebugRetentionDaysResponse

To perform this operation, you must be authenticated. Learn more.

Update chat debug retention days

Code samples

# Example request using curl curl -X PUT http://coder-server:8080/api/v2/chats/config/debug-retention-days \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/chats/config/debug-retention-days

Body parameter

{ "debug_retention_days": 0 }

Parameters

NameInTypeRequiredDescription
bodybodycodersdk.UpdateChatDebugRetentionDaysRequesttrueRequest body

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.

Get chat personal model override settings

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/config/personal-model-overrides \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/config/personal-model-overrides

Example responses

200 Response

{ "allow_users": true }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatPersonalModelOverridesAdminSettings

To perform this operation, you must be authenticated. Learn more.

Update chat personal model override settings

Code samples

# Example request using curl curl -X PUT http://coder-server:8080/api/v2/chats/config/personal-model-overrides \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/chats/config/personal-model-overrides

Body parameter

{ "allow_users": true }

Parameters

NameInTypeRequiredDescription
bodybodycodersdk.UpdateChatPersonalModelOverridesAdminSettingsRequesttrueRequest body

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.

Get chat plan mode instructions

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/config/plan-mode-instructions \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/config/plan-mode-instructions

Example responses

200 Response

{ "plan_mode_instructions": "string" }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatPlanModeInstructionsResponse

To perform this operation, you must be authenticated. Learn more.

Update chat plan mode instructions

Code samples

# Example request using curl curl -X PUT http://coder-server:8080/api/v2/chats/config/plan-mode-instructions \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/chats/config/plan-mode-instructions

Body parameter

{ "plan_mode_instructions": "string" }

Parameters

NameInTypeRequiredDescription
bodybodycodersdk.UpdateChatPlanModeInstructionsRequesttrueRequest body

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.

Get chat system prompt

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/config/system-prompt \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/config/system-prompt

Example responses

200 Response

{ "default_system_prompt": "string", "include_default_system_prompt": true, "system_prompt": "string" }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatSystemPromptResponse

To perform this operation, you must be authenticated. Learn more.

Update chat system prompt

Code samples

# Example request using curl curl -X PUT http://coder-server:8080/api/v2/chats/config/system-prompt \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/chats/config/system-prompt

Body parameter

{ "include_default_system_prompt": true, "system_prompt": "string" }

Parameters

NameInTypeRequiredDescription
bodybodycodersdk.UpdateChatSystemPromptRequesttrueRequest body

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.

Get user chat debug logging setting

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/config/user-debug-logging \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/config/user-debug-logging

Example responses

200 Response

{ "debug_logging_enabled": true, "forced_by_deployment": true, "user_toggle_allowed": true }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.UserChatDebugLoggingSettings

To perform this operation, you must be authenticated. Learn more.

Update user chat debug logging setting

Code samples

# Example request using curl curl -X PUT http://coder-server:8080/api/v2/chats/config/user-debug-logging \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/chats/config/user-debug-logging

Body parameter

{ "debug_logging_enabled": true }

Parameters

NameInTypeRequiredDescription
bodybodycodersdk.UpdateUserChatDebugLoggingRequesttrueRequest body

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.

Get user chat custom prompt

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/config/user-prompt \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/config/user-prompt

Example responses

200 Response

{ "custom_prompt": "string" }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.UserChatCustomPrompt

To perform this operation, you must be authenticated. Learn more.

Update user chat custom prompt

Code samples

# Example request using curl curl -X PUT http://coder-server:8080/api/v2/chats/config/user-prompt \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/chats/config/user-prompt

Body parameter

{ "custom_prompt": "string" }

Parameters

NameInTypeRequiredDescription
bodybodycodersdk.UserChatCustomPrompttrueRequest body

Example responses

200 Response

{ "custom_prompt": "string" }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.UserChatCustomPrompt

To perform this operation, you must be authenticated. Learn more.

Get chat workspace time to live

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/config/workspace-ttl \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/config/workspace-ttl

Example responses

200 Response

{ "workspace_ttl_ms": 0 }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatWorkspaceTTLResponse

To perform this operation, you must be authenticated. Learn more.

Update chat workspace time to live

Code samples

# Example request using curl curl -X PUT http://coder-server:8080/api/v2/chats/config/workspace-ttl \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/chats/config/workspace-ttl

Body parameter

{ "workspace_ttl_ms": 0 }

Parameters

NameInTypeRequiredDescription
bodybodycodersdk.UpdateChatWorkspaceTTLRequesttrueRequest body

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.

Upload chat file

Code samples

# Example request using curl curl -X POST http://coder-server:8080/api/v2/chats/files?organization=497f6eca-6276-4993-bfeb-53cbbbba6f08 \ -H 'Content-Type: image/png' \ -H 'Accept: application/json' \ -H 'Content-Disposition: attachment; filename="image.png"' \ -H 'Coder-Session-Token: API_KEY' \ --data-binary '@image.png'

POST /api/v2/chats/files

Parameters

NameInTypeRequiredDescription
organizationquerystring(uuid)trueOrganization ID
Content-DispositionheaderstringtrueAttachment disposition carrying the file name
bodybodystringtrueRaw file binary data

Example responses

201 Response

{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }

Responses

StatusMeaningDescriptionSchema
201CreatedCreatedcodersdk.UploadChatFileResponse
413Payload Too LargeRequest body exceeds 10 MiBcodersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get chat file

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/files/{file} \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/files/{file}

Parameters

NameInTypeRequiredDescription
filepathstring(uuid)trueFile ID

Responses

StatusMeaningDescriptionSchema
200OKOK

To perform this operation, you must be authenticated. Learn more.

Watch chat events for a user via WebSockets

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/watch \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/watch

Example responses

200 Response

{ "chat": { "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [ {} ], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" }, "kind": "status_change", "tool_calls": [ { "args": "string", "tool_call_id": "string", "tool_name": "string" } ] }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatWatchEvent

To perform this operation, you must be authenticated. Learn more.

Get chat by ID

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/{chat} \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/{chat}

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID

Example responses

200 Response

{ "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [ { "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" } ], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.Chat

To perform this operation, you must be authenticated. Learn more.

Update chat

Code samples

# Example request using curl curl -X PATCH http://coder-server:8080/api/v2/chats/{chat} \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/chats/{chat}

Body parameter

{ "archived": true, "labels": { "property1": "string", "property2": "string" }, "pin_order": 0, "plan_mode": "plan", "title": "string", "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" }

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID
bodybodycodersdk.UpdateChatRequesttrueUpdate chat request

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.

Refresh chat context

Code samples

# Example request using curl curl -X PUT http://coder-server:8080/api/v2/chats/{chat}/context \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/chats/{chat}/context

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID

Example responses

200 Response

{ "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [ { "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" } ], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.Chat

To perform this operation, you must be authenticated. Learn more.

Get chat cost

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/{chat}/cost \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/{chat}/cost

Cost covers the whole chat tree: the root chat plus every subagent chat beneath it. Requesting cost for a subagent chat returns that same total.

Cost is derived from AI Gateway data, which is subject to its own retention period, 60 days by default, configured independently of chat retention. Spend for requests older than that period is no longer reported, so a chat whose requests have all been purged reports zero cost.

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID

Example responses

200 Response

{ "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "request_count": 0, "total_cost_micros": 0, "unpriced_request_count": 0 }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatCost

To perform this operation, you must be authenticated. Learn more.

Get chat diff contents

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/{chat}/diff \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/{chat}/diff

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID

Example responses

200 Response

{ "branch": "string", "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "diff": "string", "provider": "string", "pull_request_url": "string", "remote_origin": "string" }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatDiffContents

To perform this operation, you must be authenticated. Learn more.

Interrupt chat

Code samples

# Example request using curl curl -X POST http://coder-server:8080/api/v2/chats/{chat}/interrupt \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

POST /api/v2/chats/{chat}/interrupt

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID

Example responses

200 Response

{ "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [ { "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" } ], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.Chat

To perform this operation, you must be authenticated. Learn more.

List chat messages

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/{chat}/messages \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/{chat}/messages

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID
before_idqueryintegerfalseReturn messages with id < before_id
after_idqueryintegerfalseReturn messages with id > after_id
limitqueryintegerfalsePage size, 1 to 200. Defaults to 50.

Example responses

200 Response

{ "has_more": true, "messages": [ { "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "content": [ { "args": [ 0 ], "args_delta": "string", "completed_at": "2019-08-24T14:15:22Z", "content": "string", "context_file_agent_id": { "uuid": "string", "valid": true }, "context_file_content": "string", "context_file_directory": "string", "context_file_os": "string", "context_file_path": "string", "context_file_skill_meta_file": "string", "context_file_truncated": true, "created_at": "2019-08-24T14:15:22Z", "data": [ 0 ], "end_line": 0, "file_id": { "uuid": "string", "valid": true }, "file_name": "string", "hook_rewritten": true, "is_error": true, "is_media": true, "mcp_server_config_id": { "uuid": "string", "valid": true }, "media_type": "string", "name": "string", "parsed_commands": [ [ "string" ] ], "provider_executed": true, "provider_metadata": [ 0 ], "result": [ 0 ], "result_delta": "string", "result_reset": true, "skill_description": "string", "skill_dir": "string", "skill_name": "string", "source_id": "string", "start_line": 0, "text": "string", "title": "string", "tool_call_id": "string", "tool_name": "string", "type": "text", "url": "string" } ], "created_at": "2019-08-24T14:15:22Z", "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "id": 0, "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", "role": "system", "usage": { "cache_creation_tokens": 0, "cache_read_tokens": 0, "context_limit": 0, "input_tokens": 0, "output_tokens": 0, "reasoning_tokens": 0, "total_tokens": 0 } } ], "queued_messages": [ { "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "content": [ { "args": [ 0 ], "args_delta": "string", "completed_at": "2019-08-24T14:15:22Z", "content": "string", "context_file_agent_id": { "uuid": "string", "valid": true }, "context_file_content": "string", "context_file_directory": "string", "context_file_os": "string", "context_file_path": "string", "context_file_skill_meta_file": "string", "context_file_truncated": true, "created_at": "2019-08-24T14:15:22Z", "data": [ 0 ], "end_line": 0, "file_id": { "uuid": "string", "valid": true }, "file_name": "string", "hook_rewritten": true, "is_error": true, "is_media": true, "mcp_server_config_id": { "uuid": "string", "valid": true }, "media_type": "string", "name": "string", "parsed_commands": [ [ "string" ] ], "provider_executed": true, "provider_metadata": [ 0 ], "result": [ 0 ], "result_delta": "string", "result_reset": true, "skill_description": "string", "skill_dir": "string", "skill_name": "string", "source_id": "string", "start_line": 0, "text": "string", "title": "string", "tool_call_id": "string", "tool_name": "string", "type": "text", "url": "string" } ], "created_at": "2019-08-24T14:15:22Z", "id": 0, "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205" } ] }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatMessagesResponse

To perform this operation, you must be authenticated. Learn more.

Send chat message

Code samples

# Example request using curl curl -X POST http://coder-server:8080/api/v2/chats/{chat}/messages \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

POST /api/v2/chats/{chat}/messages

Body parameter

{ "busy_behavior": "queue", "content": [ { "content": "string", "end_line": 0, "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767", "file_name": "string", "start_line": 0, "text": "string", "type": "text" } ], "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", "plan_mode": "plan", "reasoning_effort": "string" }

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID
bodybodycodersdk.CreateChatMessageRequesttrueCreate chat message request

Example responses

200 Response

{ "message": { "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "content": [ { "args": [ 0 ], "args_delta": "string", "completed_at": "2019-08-24T14:15:22Z", "content": "string", "context_file_agent_id": { "uuid": "string", "valid": true }, "context_file_content": "string", "context_file_directory": "string", "context_file_os": "string", "context_file_path": "string", "context_file_skill_meta_file": "string", "context_file_truncated": true, "created_at": "2019-08-24T14:15:22Z", "data": [ 0 ], "end_line": 0, "file_id": { "uuid": "string", "valid": true }, "file_name": "string", "hook_rewritten": true, "is_error": true, "is_media": true, "mcp_server_config_id": { "uuid": "string", "valid": true }, "media_type": "string", "name": "string", "parsed_commands": [ [ "string" ] ], "provider_executed": true, "provider_metadata": [ 0 ], "result": [ 0 ], "result_delta": "string", "result_reset": true, "skill_description": "string", "skill_dir": "string", "skill_name": "string", "source_id": "string", "start_line": 0, "text": "string", "title": "string", "tool_call_id": "string", "tool_name": "string", "type": "text", "url": "string" } ], "created_at": "2019-08-24T14:15:22Z", "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "id": 0, "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", "role": "system", "usage": { "cache_creation_tokens": 0, "cache_read_tokens": 0, "context_limit": 0, "input_tokens": 0, "output_tokens": 0, "reasoning_tokens": 0, "total_tokens": 0 } }, "messages": [ { "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "content": [ { "args": [ 0 ], "args_delta": "string", "completed_at": "2019-08-24T14:15:22Z", "content": "string", "context_file_agent_id": { "uuid": "string", "valid": true }, "context_file_content": "string", "context_file_directory": "string", "context_file_os": "string", "context_file_path": "string", "context_file_skill_meta_file": "string", "context_file_truncated": true, "created_at": "2019-08-24T14:15:22Z", "data": [ 0 ], "end_line": 0, "file_id": { "uuid": "string", "valid": true }, "file_name": "string", "hook_rewritten": true, "is_error": true, "is_media": true, "mcp_server_config_id": { "uuid": "string", "valid": true }, "media_type": "string", "name": "string", "parsed_commands": [ [ "string" ] ], "provider_executed": true, "provider_metadata": [ 0 ], "result": [ 0 ], "result_delta": "string", "result_reset": true, "skill_description": "string", "skill_dir": "string", "skill_name": "string", "source_id": "string", "start_line": 0, "text": "string", "title": "string", "tool_call_id": "string", "tool_name": "string", "type": "text", "url": "string" } ], "created_at": "2019-08-24T14:15:22Z", "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "id": 0, "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", "role": "system", "usage": { "cache_creation_tokens": 0, "cache_read_tokens": 0, "context_limit": 0, "input_tokens": 0, "output_tokens": 0, "reasoning_tokens": 0, "total_tokens": 0 } } ], "queued": true, "queued_message": { "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "content": [ { "args": [ 0 ], "args_delta": "string", "completed_at": "2019-08-24T14:15:22Z", "content": "string", "context_file_agent_id": { "uuid": "string", "valid": true }, "context_file_content": "string", "context_file_directory": "string", "context_file_os": "string", "context_file_path": "string", "context_file_skill_meta_file": "string", "context_file_truncated": true, "created_at": "2019-08-24T14:15:22Z", "data": [ 0 ], "end_line": 0, "file_id": { "uuid": "string", "valid": true }, "file_name": "string", "hook_rewritten": true, "is_error": true, "is_media": true, "mcp_server_config_id": { "uuid": "string", "valid": true }, "media_type": "string", "name": "string", "parsed_commands": [ [ "string" ] ], "provider_executed": true, "provider_metadata": [ 0 ], "result": [ 0 ], "result_delta": "string", "result_reset": true, "skill_description": "string", "skill_dir": "string", "skill_name": "string", "source_id": "string", "start_line": 0, "text": "string", "title": "string", "tool_call_id": "string", "tool_name": "string", "type": "text", "url": "string" } ], "created_at": "2019-08-24T14:15:22Z", "id": 0, "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205" }, "warnings": [ "string" ] }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.CreateChatMessageResponse

To perform this operation, you must be authenticated. Learn more.

Edit chat message

Code samples

# Example request using curl curl -X PATCH http://coder-server:8080/api/v2/chats/{chat}/messages/{message} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/chats/{chat}/messages/{message}

Body parameter

{ "content": [ { "content": "string", "end_line": 0, "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767", "file_name": "string", "start_line": 0, "text": "string", "type": "text" } ], "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", "reasoning_effort": "string" }

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID
messagepathintegertrueMessage ID
bodybodycodersdk.EditChatMessageRequesttrueEdit chat message request

Example responses

200 Response

{ "deleted_message_ids": [ 0 ], "message": { "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "content": [ { "args": [ 0 ], "args_delta": "string", "completed_at": "2019-08-24T14:15:22Z", "content": "string", "context_file_agent_id": { "uuid": "string", "valid": true }, "context_file_content": "string", "context_file_directory": "string", "context_file_os": "string", "context_file_path": "string", "context_file_skill_meta_file": "string", "context_file_truncated": true, "created_at": "2019-08-24T14:15:22Z", "data": [ 0 ], "end_line": 0, "file_id": { "uuid": "string", "valid": true }, "file_name": "string", "hook_rewritten": true, "is_error": true, "is_media": true, "mcp_server_config_id": { "uuid": "string", "valid": true }, "media_type": "string", "name": "string", "parsed_commands": [ [ "string" ] ], "provider_executed": true, "provider_metadata": [ 0 ], "result": [ 0 ], "result_delta": "string", "result_reset": true, "skill_description": "string", "skill_dir": "string", "skill_name": "string", "source_id": "string", "start_line": 0, "text": "string", "title": "string", "tool_call_id": "string", "tool_name": "string", "type": "text", "url": "string" } ], "created_at": "2019-08-24T14:15:22Z", "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "id": 0, "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", "role": "system", "usage": { "cache_creation_tokens": 0, "cache_read_tokens": 0, "context_limit": 0, "input_tokens": 0, "output_tokens": 0, "reasoning_tokens": 0, "total_tokens": 0 } }, "messages": [ { "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "content": [ { "args": [ 0 ], "args_delta": "string", "completed_at": "2019-08-24T14:15:22Z", "content": "string", "context_file_agent_id": { "uuid": "string", "valid": true }, "context_file_content": "string", "context_file_directory": "string", "context_file_os": "string", "context_file_path": "string", "context_file_skill_meta_file": "string", "context_file_truncated": true, "created_at": "2019-08-24T14:15:22Z", "data": [ 0 ], "end_line": 0, "file_id": { "uuid": "string", "valid": true }, "file_name": "string", "hook_rewritten": true, "is_error": true, "is_media": true, "mcp_server_config_id": { "uuid": "string", "valid": true }, "media_type": "string", "name": "string", "parsed_commands": [ [ "string" ] ], "provider_executed": true, "provider_metadata": [ 0 ], "result": [ 0 ], "result_delta": "string", "result_reset": true, "skill_description": "string", "skill_dir": "string", "skill_name": "string", "source_id": "string", "start_line": 0, "text": "string", "title": "string", "tool_call_id": "string", "tool_name": "string", "type": "text", "url": "string" } ], "created_at": "2019-08-24T14:15:22Z", "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "id": 0, "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", "role": "system", "usage": { "cache_creation_tokens": 0, "cache_read_tokens": 0, "context_limit": 0, "input_tokens": 0, "output_tokens": 0, "reasoning_tokens": 0, "total_tokens": 0 } } ], "warnings": [ "string" ] }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.EditChatMessageResponse

To perform this operation, you must be authenticated. Learn more.

List chat user prompts

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/{chat}/prompts \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/{chat}/prompts

Returns the user-authored prompts in a chat, newest first, with each prompt's text parts concatenated in the order they were authored. Used by the composer to power the up/down arrow prompt-history cycle without paging through every message in the chat.

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID
limitqueryintegerfalsePage size, 0 to 2000. 0 (the default) means the server-side default of 500.

Example responses

200 Response

{ "prompts": [ { "id": 0, "text": "string" } ] }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ChatPromptsResponse

To perform this operation, you must be authenticated. Learn more.

Delete chat queued message

Code samples

# Example request using curl curl -X DELETE http://coder-server:8080/api/v2/chats/{chat}/queue/{queuedMessage} \ -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/chats/{chat}/queue/{queuedMessage}

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID
queuedMessagepathintegertrueQueued message ID

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.

Promote chat queued message

Code samples

# Example request using curl curl -X POST http://coder-server:8080/api/v2/chats/{chat}/queue/{queuedMessage}/promote \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

POST /api/v2/chats/{chat}/queue/{queuedMessage}/promote

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID
queuedMessagepathintegertrueQueued message ID

Example responses

202 Response

{ "detail": "string", "message": "string", "validations": [ { "detail": "string", "field": "string" } ] }

Responses

StatusMeaningDescriptionSchema
202AcceptedAcceptedcodersdk.Response

To perform this operation, you must be authenticated. Learn more.

Reconcile invalid chat state

Code samples

# Example request using curl curl -X POST http://coder-server:8080/api/v2/chats/{chat}/reconcile-invalid \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

POST /api/v2/chats/{chat}/reconcile-invalid

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID

Example responses

200 Response

{ "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [ { "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "archived": true, "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", "children": [], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" } ], "client_type": "ui", "context": { "dirty": true, "dirty_since": "2019-08-24T14:15:22Z", "error": "string", "resources": [ { "error": "string", "kind": "instruction_file", "size_bytes": 0, "skill_description": "string", "skill_name": "string", "source": "string", "status": "ok", "tools": [ { "description": "string", "name": "string" } ] } ] }, "created_at": "2019-08-24T14:15:22Z", "diff_status": { "additions": 0, "approved": true, "author_avatar_url": "string", "author_login": "string", "base_branch": "string", "changed_files": 0, "changes_requested": true, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "commits": 0, "deletions": 0, "head_branch": "string", "pr_number": 0, "pull_request_draft": true, "pull_request_state": "string", "pull_request_title": "string", "refreshed_at": "2019-08-24T14:15:22Z", "reviewer_count": 0, "stale_at": "2019-08-24T14:15:22Z", "url": "string" }, "files": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "mime_type": "string", "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "size_bytes": 0 } ], "has_unread": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "labels": { "property1": "string", "property2": "string" }, "last_error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", "last_reasoning_effort": "string", "last_turn_summary": "string", "mcp_server_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", "owner_name": "string", "owner_username": "string", "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", "pin_order": 0, "plan_mode": "plan", "queued_for_capacity": true, "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", "shared": true, "status": "waiting", "summary": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "warnings": [ "string" ], "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.Chat

To perform this operation, you must be authenticated. Learn more.

Stream chat events via WebSockets

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/{chat}/stream \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/{chat}/stream

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID
after_idqueryintegerfalseSkip snapshot messages with id at or before this cursor

Example responses

200 Response

[ { "action_required": { "tool_calls": [ { "args": "string", "tool_call_id": "string", "tool_name": "string" } ] }, "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "error": { "detail": "string", "kind": "generic", "message": "string", "provider": "string", "retryable": true, "status_code": 0 }, "message": { "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "content": [ { "args": [ 0 ], "args_delta": "string", "completed_at": "2019-08-24T14:15:22Z", "content": "string", "context_file_agent_id": { "uuid": "string", "valid": true }, "context_file_content": "string", "context_file_directory": "string", "context_file_os": "string", "context_file_path": "string", "context_file_skill_meta_file": "string", "context_file_truncated": true, "created_at": "2019-08-24T14:15:22Z", "data": [ 0 ], "end_line": 0, "file_id": { "uuid": "string", "valid": true }, "file_name": "string", "hook_rewritten": true, "is_error": true, "is_media": true, "mcp_server_config_id": { "uuid": "string", "valid": true }, "media_type": "string", "name": "string", "parsed_commands": [ [ "string" ] ], "provider_executed": true, "provider_metadata": [ 0 ], "result": [ 0 ], "result_delta": "string", "result_reset": true, "skill_description": "string", "skill_dir": "string", "skill_name": "string", "source_id": "string", "start_line": 0, "text": "string", "title": "string", "tool_call_id": "string", "tool_name": "string", "type": "text", "url": "string" } ], "created_at": "2019-08-24T14:15:22Z", "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "id": 0, "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", "role": "system", "usage": { "cache_creation_tokens": 0, "cache_read_tokens": 0, "context_limit": 0, "input_tokens": 0, "output_tokens": 0, "reasoning_tokens": 0, "total_tokens": 0 } }, "message_part": { "generation_attempt": 0, "history_version": 0, "part": { "args": [ 0 ], "args_delta": "string", "completed_at": "2019-08-24T14:15:22Z", "content": "string", "context_file_agent_id": { "uuid": "string", "valid": true }, "context_file_content": "string", "context_file_directory": "string", "context_file_os": "string", "context_file_path": "string", "context_file_skill_meta_file": "string", "context_file_truncated": true, "created_at": "2019-08-24T14:15:22Z", "data": [ 0 ], "end_line": 0, "file_id": { "uuid": "string", "valid": true }, "file_name": "string", "hook_rewritten": true, "is_error": true, "is_media": true, "mcp_server_config_id": { "uuid": "string", "valid": true }, "media_type": "string", "name": "string", "parsed_commands": [ [ "string" ] ], "provider_executed": true, "provider_metadata": [ 0 ], "result": [ 0 ], "result_delta": "string", "result_reset": true, "skill_description": "string", "skill_dir": "string", "skill_name": "string", "source_id": "string", "start_line": 0, "text": "string", "title": "string", "tool_call_id": "string", "tool_name": "string", "type": "text", "url": "string" }, "role": "system", "seq": 0 }, "queued_messages": [ { "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", "content": [ { "args": [ 0 ], "args_delta": "string", "completed_at": "2019-08-24T14:15:22Z", "content": "string", "context_file_agent_id": { "uuid": "string", "valid": true }, "context_file_content": "string", "context_file_directory": "string", "context_file_os": "string", "context_file_path": "string", "context_file_skill_meta_file": "string", "context_file_truncated": true, "created_at": "2019-08-24T14:15:22Z", "data": [ 0 ], "end_line": 0, "file_id": { "uuid": "string", "valid": true }, "file_name": "string", "hook_rewritten": true, "is_error": true, "is_media": true, "mcp_server_config_id": { "uuid": "string", "valid": true }, "media_type": "string", "name": "string", "parsed_commands": [ [ "string" ] ], "provider_executed": true, "provider_metadata": [ 0 ], "result": [ 0 ], "result_delta": "string", "result_reset": true, "skill_description": "string", "skill_dir": "string", "skill_name": "string", "source_id": "string", "start_line": 0, "text": "string", "title": "string", "tool_call_id": "string", "tool_name": "string", "type": "text", "url": "string" } ], "created_at": "2019-08-24T14:15:22Z", "id": 0, "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205" } ], "retry": { "attempt": 0, "delay_ms": 0, "error": "string", "kind": "generic", "provider": "string", "retrying_at": "2019-08-24T14:15:22Z", "status_code": 0 }, "status": { "status": "waiting" }, "type": "message_part" } ]

Responses

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.ChatStreamEvent

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» action_requiredcodersdk.ChatStreamActionRequiredfalse
»» tool_callsarrayfalse
»»» argsstringfalse
»»» tool_call_idstringfalse
»»» tool_namestringfalse
» chat_idstring(uuid)false
» errorcodersdk.ChatErrorfalse
»» detailstringfalseDetail is optional provider-specific context shown alongside the normalized error message when available.
»» kindcodersdk.ChatErrorKindfalseKind classifies the error for consistent client rendering.
»» messagestringfalseMessage is the normalized, user-facing error message.
»» providerstringfalseProvider identifies the upstream model provider when known.
»» retryablebooleanfalseRetryable reports whether the underlying error is transient.
»» status_codeintegerfalseStatus code is the best-effort upstream HTTP status code.
» messagecodersdk.ChatMessagefalse
»» chat_idstring(uuid)false
»» contentarrayfalse
»»» argsarrayfalse
»»» args_deltastringfalse
»»» completed_atstring(date-time)falseCompleted at is the time a reasoning part finished streaming, so reasoning duration can be computed as completed_at minus created_at. For interrupted reasoning, this is the interruption time. Absent when reasoning timestamp data was not recorded (e.g. messages persisted before this feature was added).
»»» contentstringfalseThe code content from the diff that was commented on.
»»» context_file_agent_iduuid.NullUUIDfalseContext file agent ID is the workspace agent that provided this context file. Used to detect when the agent changes (e.g. workspace rebuilt) so instruction files can be re-persisted with fresh content.
»»»» uuidstringfalse
»»»» validbooleanfalseValid is true if UUID is not NULL
»»» context_file_contentstringfalseContext file content holds the file content sent to the LLM. Internal only: stripped before API responses to keep payloads small. The backend reads it when building the prompt via partsToMessageParts.
»»» context_file_directorystringfalseContext file directory is the working directory of the workspace agent. Internal only: same purpose as ContextFileOS.
»»» context_file_osstringfalseContext file os is the operating system of the workspace agent. Internal only: used during prompt expansion so the LLM knows the OS even on turns where InsertSystem is not called.
»»» context_file_pathstringfalseContext file path is the absolute path of a file loaded into the LLM context (e.g. an AGENTS.md instruction file).
»»» context_file_skill_meta_filestringfalseContext file skill meta file is the basename of the skill meta file (e.g. "SKILL.md") at the time of persistence. Internal only: restored on subsequent turns so the read_skill tool uses the correct filename even when the agent configured a non-default value.
»»» context_file_truncatedbooleanfalseContext file truncated indicates the file exceeded the 64KiB instruction file limit and was truncated.
»»» created_atstring(date-time)falseCreated at is the timestamp this part carries. The semantics depend on the part type: for tool-call and tool-result parts it is the time the call was emitted or the result was produced (tool duration is the result's created_at minus the call's created_at); for reasoning parts it is the time reasoning started streaming.
»»» dataarrayfalse
»»» end_lineintegerfalse
»»» file_iduuid.NullUUIDfalse
»»»» uuidstringfalse
»»»» validbooleanfalseValid is true if UUID is not NULL
»»» file_namestringfalse
»»» hook_rewrittenbooleanfalseHook rewritten indicates that a lifecycle hook replaced model-proposed tool input.
»»» is_errorbooleanfalse
»»» is_mediabooleanfalse
»»» mcp_server_config_iduuid.NullUUIDfalse
»»»» uuidstringfalse
»»»» validbooleanfalseValid is true if UUID is not NULL
»»» media_typestringfalse
»»» namestringfalse
»»» parsed_commandsarrayfalseParsed commands holds parsed programs from an execute tool call's shell command, one entry per simple command in source order. Each entry is [program] or [program, arg] where arg is the first non-flag positional argument. Program names are normalized to their base name (e.g. /usr/bin/go becomes go). Only populated when ToolName is "execute" and the command parses successfully; nil otherwise.
»»» provider_executedbooleanfalseProvider executed indicates the tool call was executed by the provider (e.g. Anthropic computer use).
»»» provider_metadataarrayfalseProvider metadata holds provider-specific response metadata (e.g. Anthropic cache control hints) as raw JSON. Internal only: stripped by db2sdk before API responses.
»»» resultarrayfalse
»»» result_deltastringfalse
»»» result_resetbooleanfalse
»»» skill_descriptionstringfalseSkill description is the short description from the skill's SKILL.md frontmatter.
»»» skill_dirstringfalseSkill dir is the absolute path to the skill directory inside the workspace filesystem. Internal only: used by read_skill/read_skill_file tools to locate skill files.
»»» skill_namestringfalseSkill name is the kebab-case name of a discovered skill from the workspace's .agents/skills/ directory.
»»» source_idstringfalse
»»» start_lineintegerfalse
»»» textstringfalse
»»» titlestringfalse
»»» tool_call_idstringfalse
»»» tool_namestringfalse
»»» typecodersdk.ChatMessagePartTypefalse
»»» urlstringfalse
»» created_atstring(date-time)false
»» created_bystring(uuid)false
»» idintegerfalse
»» model_config_idstring(uuid)false
»» rolecodersdk.ChatMessageRolefalse
»» usagecodersdk.ChatMessageUsagefalse
»»» cache_creation_tokensintegerfalse
»»» cache_read_tokensintegerfalse
»»» context_limitintegerfalse
»»» input_tokensintegerfalse
»»» output_tokensintegerfalse
»»» reasoning_tokensintegerfalse
»»» total_tokensintegerfalse
» message_partcodersdk.ChatStreamMessagePartfalse
»» generation_attemptintegerfalse
»» history_versionintegerfalse
»» partcodersdk.ChatMessagePartfalse
»» rolecodersdk.ChatMessageRolefalse
»» seqintegerfalse
» queued_messagesarrayfalse
»» chat_idstring(uuid)false
»» contentarrayfalse
»» created_atstring(date-time)false
»» idintegerfalse
»» model_config_idstring(uuid)false
» retrycodersdk.ChatStreamRetryfalse
»» attemptintegerfalseAttempt is the 1-indexed retry attempt number.
»» delay_msintegerfalseDelay ms is the backoff delay in milliseconds before the retry.
»» errorstringfalseError is the normalized error message from the failed attempt.
»» kindcodersdk.ChatErrorKindfalseKind classifies the retry reason for consistent client rendering.
»» providerstringfalseProvider identifies the upstream model provider when known.
»» retrying_atstring(date-time)falseRetrying at is the timestamp when the retry will be attempted.
»» status_codeintegerfalseStatus code is the best-effort upstream HTTP status code.
» statuscodersdk.ChatStreamStatusfalse
»» statuscodersdk.ChatStatusfalse
» typecodersdk.ChatStreamEventTypefalse

Enumerated Values

PropertyValue(s)
kindauth, config, content_filter, generic, hook_denied, hook_dispatch_failed, missing_key, overloaded, provider_disabled, rate_limit, stream_silence_timeout, timeout, usage_limit
typeaction_required, context-file, error, file, file-reference, history_reset, hook-context, hook-notice, message, message_part, preview_reset, queue_update, reasoning, retry, skill, source, status, text, tool-call, tool-result
roleassistant, system, tool, user
statuserror, interrupting, requires_action, running, waiting

To perform this operation, you must be authenticated. Learn more.

Watch chat workspace git state via WebSockets

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/chats/{chat}/stream/git \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/chats/{chat}/stream/git

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID

Example responses

200 Response

{ "message": "string", "repositories": [ { "branch": "string", "remote_origin": "string", "removed": true, "repo_root": "string", "unified_diff": "string" } ], "scanned_at": "2019-08-24T14:15:22Z", "type": "changes" }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.WorkspaceAgentGitServerMessage

To perform this operation, you must be authenticated. Learn more.

Propose chat title

Code samples

# Example request using curl curl -X POST http://coder-server:8080/api/v2/chats/{chat}/title/propose \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

POST /api/v2/chats/{chat}/title/propose

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID

Example responses

200 Response

{ "title": "string" }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.ProposeChatTitleResponse

To perform this operation, you must be authenticated. Learn more.

Submit chat tool results

Code samples

# Example request using curl curl -X POST http://coder-server:8080/api/v2/chats/{chat}/tool-results \ -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY'

POST /api/v2/chats/{chat}/tool-results

Body parameter

{ "results": [ { "is_error": true, "output": [ 0 ], "tool_call_id": "string" } ] }

Parameters

NameInTypeRequiredDescription
chatpathstring(uuid)trueChat ID
bodybodycodersdk.SubmitToolResultsRequesttrueRequest body

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.

List AI models and provider descriptors in an organization

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/chats/models \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/chats/models

Parameters

NameInTypeRequiredDescription
organizationpathstringtrueOrganization name or ID

Example responses

200 Response

{ "models": [ { "ai_provider_id": "5a3b8ff9-20e7-4c37-ba1a-5b433e355819", "compression_threshold": 0, "context_limit": 0, "created_at": "2019-08-24T14:15:22Z", "display_name": "string", "enabled": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "is_default": true, "model": "string", "model_config": { "frequency_penalty": 0, "max_output_tokens": 0, "openai_config": { "use_responses_api": true }, "presence_penalty": 0, "provider_options": { "anthropic": { "allowed_domains": [ "string" ], "blocked_domains": [ "string" ], "context_1m_enabled": true, "disable_parallel_tool_use": true, "send_reasoning": true, "thinking": { "budget_tokens": 0 }, "thinking_display": "string", "web_search_enabled": true }, "google": { "cached_content": "string", "safety_settings": [ { "category": "string", "threshold": "string" } ], "thinking_config": { "include_thoughts": true, "thinking_budget": 0, "thinking_level": "string" }, "threshold": "string", "web_search_enabled": true }, "openai": { "allowed_domains": [ "string" ], "include": [ "string" ], "instructions": "string", "log_probs": true, "logit_bias": { "property1": 0, "property2": 0 }, "max_completion_tokens": 0, "max_tool_calls": 0, "metadata": { "property1": null, "property2": null }, "parallel_tool_calls": true, "prediction": { "property1": null, "property2": null }, "prompt_cache_key": "string", "reasoning_summary": "string", "safety_identifier": "string", "search_context_size": "string", "service_tier": "string", "store": true, "strict_json_schema": true, "structured_outputs": true, "text_verbosity": "string", "top_log_probs": 0, "user": "string", "web_search_enabled": true }, "openaicompat": { "user": "string" }, "openrouter": { "extra_body": { "property1": null, "property2": null }, "include_usage": true, "log_probs": true, "logit_bias": { "property1": 0, "property2": 0 }, "parallel_tool_calls": true, "provider": { "allow_fallbacks": true, "data_collection": "string", "ignore": [ "string" ], "only": [ "string" ], "order": [ "string" ], "quantizations": [ "string" ], "require_parameters": true, "sort": "string" }, "reasoning": { "enabled": true, "exclude": true, "max_tokens": 0 }, "user": "string" }, "vercel": { "extra_body": { "property1": null, "property2": null }, "logit_bias": { "property1": 0, "property2": 0 }, "logprobs": true, "parallel_tool_calls": true, "providerOptions": { "models": [ "string" ], "order": [ "string" ] }, "reasoning": { "enabled": true, "exclude": true, "max_tokens": 0 }, "top_logprobs": 0, "user": "string" } }, "reasoning_effort": { "default": "string", "max": "string" }, "temperature": 0, "top_k": 0, "top_p": 0 }, "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "reasoning_efforts": [ "string" ], "updated_at": "2019-08-24T14:15:22Z" } ], "providers": [ { "allow_user_api_key": true, "available": true, "display_name": "string", "enabled": true, "has_api_key": true, "has_effective_api_key": true, "has_user_api_key": true, "icon": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "type": "string", "unavailable_reason": "missing_api_key" } ], "unsupported_providers": [ { "display_name": "string", "provider": "string" } ] }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.OrganizationChatModelsResponse

To perform this operation, you must be authenticated. Learn more.

Create an AI model in an organization

Code samples

# Example request using curl curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/chats/models \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

POST /api/v2/organizations/{organization}/chats/models

Body parameter

{ "ai_provider_id": "5a3b8ff9-20e7-4c37-ba1a-5b433e355819", "compression_threshold": 0, "context_limit": 0, "display_name": "string", "enabled": true, "is_default": true, "model": "string", "model_config": { "frequency_penalty": 0, "max_output_tokens": 0, "openai_config": { "use_responses_api": true }, "presence_penalty": 0, "provider_options": { "anthropic": { "allowed_domains": [ "string" ], "blocked_domains": [ "string" ], "context_1m_enabled": true, "disable_parallel_tool_use": true, "send_reasoning": true, "thinking": { "budget_tokens": 0 }, "thinking_display": "string", "web_search_enabled": true }, "google": { "cached_content": "string", "safety_settings": [ { "category": "string", "threshold": "string" } ], "thinking_config": { "include_thoughts": true, "thinking_budget": 0, "thinking_level": "string" }, "threshold": "string", "web_search_enabled": true }, "openai": { "allowed_domains": [ "string" ], "include": [ "string" ], "instructions": "string", "log_probs": true, "logit_bias": { "property1": 0, "property2": 0 }, "max_completion_tokens": 0, "max_tool_calls": 0, "metadata": { "property1": null, "property2": null }, "parallel_tool_calls": true, "prediction": { "property1": null, "property2": null }, "prompt_cache_key": "string", "reasoning_summary": "string", "safety_identifier": "string", "search_context_size": "string", "service_tier": "string", "store": true, "strict_json_schema": true, "structured_outputs": true, "text_verbosity": "string", "top_log_probs": 0, "user": "string", "web_search_enabled": true }, "openaicompat": { "user": "string" }, "openrouter": { "extra_body": { "property1": null, "property2": null }, "include_usage": true, "log_probs": true, "logit_bias": { "property1": 0, "property2": 0 }, "parallel_tool_calls": true, "provider": { "allow_fallbacks": true, "data_collection": "string", "ignore": [ "string" ], "only": [ "string" ], "order": [ "string" ], "quantizations": [ "string" ], "require_parameters": true, "sort": "string" }, "reasoning": { "enabled": true, "exclude": true, "max_tokens": 0 }, "user": "string" }, "vercel": { "extra_body": { "property1": null, "property2": null }, "logit_bias": { "property1": 0, "property2": 0 }, "logprobs": true, "parallel_tool_calls": true, "providerOptions": { "models": [ "string" ], "order": [ "string" ] }, "reasoning": { "enabled": true, "exclude": true, "max_tokens": 0 }, "top_logprobs": 0, "user": "string" } }, "reasoning_effort": { "default": "string", "max": "string" }, "temperature": 0, "top_k": 0, "top_p": 0 } }

Parameters

NameInTypeRequiredDescription
organizationpathstringtrueOrganization name or ID
bodybodycodersdk.CreateChatModelRequesttrueModel

Example responses

201 Response

{ "ai_provider_id": "5a3b8ff9-20e7-4c37-ba1a-5b433e355819", "compression_threshold": 0, "context_limit": 0, "created_at": "2019-08-24T14:15:22Z", "display_name": "string", "enabled": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "is_default": true, "model": "string", "model_config": { "frequency_penalty": 0, "max_output_tokens": 0, "openai_config": { "use_responses_api": true }, "presence_penalty": 0, "provider_options": { "anthropic": { "allowed_domains": [ "string" ], "blocked_domains": [ "string" ], "context_1m_enabled": true, "disable_parallel_tool_use": true, "send_reasoning": true, "thinking": { "budget_tokens": 0 }, "thinking_display": "string", "web_search_enabled": true }, "google": { "cached_content": "string", "safety_settings": [ { "category": "string", "threshold": "string" } ], "thinking_config": { "include_thoughts": true, "thinking_budget": 0, "thinking_level": "string" }, "threshold": "string", "web_search_enabled": true }, "openai": { "allowed_domains": [ "string" ], "include": [ "string" ], "instructions": "string", "log_probs": true, "logit_bias": { "property1": 0, "property2": 0 }, "max_completion_tokens": 0, "max_tool_calls": 0, "metadata": { "property1": null, "property2": null }, "parallel_tool_calls": true, "prediction": { "property1": null, "property2": null }, "prompt_cache_key": "string", "reasoning_summary": "string", "safety_identifier": "string", "search_context_size": "string", "service_tier": "string", "store": true, "strict_json_schema": true, "structured_outputs": true, "text_verbosity": "string", "top_log_probs": 0, "user": "string", "web_search_enabled": true }, "openaicompat": { "user": "string" }, "openrouter": { "extra_body": { "property1": null, "property2": null }, "include_usage": true, "log_probs": true, "logit_bias": { "property1": 0, "property2": 0 }, "parallel_tool_calls": true, "provider": { "allow_fallbacks": true, "data_collection": "string", "ignore": [ "string" ], "only": [ "string" ], "order": [ "string" ], "quantizations": [ "string" ], "require_parameters": true, "sort": "string" }, "reasoning": { "enabled": true, "exclude": true, "max_tokens": 0 }, "user": "string" }, "vercel": { "extra_body": { "property1": null, "property2": null }, "logit_bias": { "property1": 0, "property2": 0 }, "logprobs": true, "parallel_tool_calls": true, "providerOptions": { "models": [ "string" ], "order": [ "string" ] }, "reasoning": { "enabled": true, "exclude": true, "max_tokens": 0 }, "top_logprobs": 0, "user": "string" } }, "reasoning_effort": { "default": "string", "max": "string" }, "temperature": 0, "top_k": 0, "top_p": 0 }, "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "reasoning_efforts": [ "string" ], "updated_at": "2019-08-24T14:15:22Z" }

Responses

StatusMeaningDescriptionSchema
201CreatedCreatedcodersdk.ChatModel

To perform this operation, you must be authenticated. Learn more.

List user AI provider key configurations

Code samples

# Example request using curl curl -X GET http://coder-server:8080/api/v2/users/{user}/ai-provider-keys \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

GET /api/v2/users/{user}/ai-provider-keys

Parameters

NameInTypeRequiredDescription
userpathstringtrueUser ID, username, or me

Example responses

200 Response

[ { "byok_enabled": true, "has_provider_api_key": true, "has_user_api_key": true, "provider": { "deleted": true, "display_name": "string", "enabled": true, "icon": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "type": "openai" } } ]

Responses

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.UserAIProviderKeyConfig

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» byok_enabledbooleanfalse
» has_provider_api_keybooleanfalse
» has_user_api_keybooleanfalse
» providercodersdk.AIProviderSummaryfalse
»» deletedbooleanfalse
»» display_namestringfalse
»» enabledbooleanfalse
»» iconstringfalse
»» idstring(uuid)false
»» namestringfalse
»» typecodersdk.AIProviderTypefalse

Enumerated Values

PropertyValue(s)
typeanthropic, azure, bedrock, copilot, google, openai, openai-compat, openrouter, vercel

To perform this operation, you must be authenticated. Learn more.

Update user AI provider key

Code samples

# Example request using curl curl -X PUT http://coder-server:8080/api/v2/users/{user}/ai-provider-keys/{aiProvider} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/users/{user}/ai-provider-keys/{aiProvider}

Body parameter

{ "api_key": "string" }

Parameters

NameInTypeRequiredDescription
userpathstringtrueUser ID, username, or me
aiProviderpathstring(uuid)trueAI provider ID
bodybodycodersdk.CreateUserAIProviderKeyRequesttrueRequest body

Example responses

200 Response

{ "byok_enabled": true, "has_provider_api_key": true, "has_user_api_key": true, "provider": { "deleted": true, "display_name": "string", "enabled": true, "icon": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "type": "openai" } }

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.UserAIProviderKeyConfig

To perform this operation, you must be authenticated. Learn more.

Delete user AI provider key

Code samples

# Example request using curl curl -X DELETE http://coder-server:8080/api/v2/users/{user}/ai-provider-keys/{aiProvider} \ -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/users/{user}/ai-provider-keys/{aiProvider}

Parameters

NameInTypeRequiredDescription
userpathstringtrueUser ID, username, or me
aiProviderpathstring(uuid)trueAI provider ID

Responses

StatusMeaningDescriptionSchema
204No ContentNo Content

To perform this operation, you must be authenticated. Learn more.