Owners and owner-level service accounts can now start a Coder Agents
chat on behalf of another user by setting `owner_id` on `POST
/api/v2/chats`. The field is optional and defaults to the caller, so
existing clients are unaffected. A delegated owner must be an active,
non-system member of the requested organization; anything else returns
400 `Chat owner must be an active member of the organization.` once the
caller has passed the authorization gates below.
A chat runs entirely with its owner's credentials (synthetic API key,
workspace access, OIDC and provider tokens), so creating one for someone
else is acting as that user. On top of org-scoped `chat:create` for the
owner, the caller must hold the authority to create API keys for that
user, which is what the token endpoint demands to mint their session.
Org admins therefore cannot use it; site owners and owner-role service
accounts can. For the same reason the workspace binding, model config,
and MCP server IDs are validated as the owner rather than the caller,
and the owner must themselves hold `chat:create` (organization service
accounts do not). The initial user message is attributed to the caller
through `chatd.CreateOptions.CreatedBy`.
An earlier revision of this PR exposed the same behavior as `POST
/api/v2/users/{user}/chats`; that route and
`codersdk.Client.CreateUserChat` were removed in `62a8be3dd32` in favor
of the request field. An explicit zero `owner_id` is rejected with 400
rather than silently defaulting to the caller. Coverage lives in
`TestPostChats_OwnerID`.
<details>
<summary>Review record (path-based revision, gates unchanged)</summary>
- Two-axis code review (Standards, Spec) plus a simplicity audit ran as
Xum sub-agents on `1f3189898f0`. The Spec axis found the workspace
binding was authorized as the caller, fixed in `363d45281d8` with
red-green coverage in `WorkspaceNotAccessibleToOwner`. The additional
API-key gate and the `CreatedBy` attribution go beyond the workspaces
pattern and were kept deliberately for the reasons above.
- Codex review on `363d45281d8`: one P2, suspended, dormant, or system
users could be targeted and would get a chat that can never run because
AI Bridge refuses to authorize them. Fixed in `c065437e359` with
`OwnerSuspended` (red on the old head); thread replied to and resolved.
- Codex review on `c065437e359`: one P2, an explicit or
personal-override model config the caller can read but the owner cannot
was accepted and chatd would silently fall back to the default model at
run time. Fixed in `aa88b608182` by resolving the model config and MCP
server IDs under the owner's context, with
`ModelConfigNotAccessibleToOwner` (red on the old head); thread replied
to and resolved.
- Codex review on `aa88b608182`: one P2, an organization service account
(which deliberately holds no chat permissions) could be targeted because
the chat permission check ran as the caller. Fixed in `a6fe8075c30` by
also requiring the owner subject to hold `chat:create`, with
`OwnerWithoutChatPermission` (red on the old head); thread replied to
and resolved.
- Codex review on `a6fe8075c30`: one P2, the active/non-system check was
skipped when the caller could not read the owner's user object. Fixed in
`0dd8bb4dd44` by moving the check behind the authorization gates with a
system-restricted lookup; thread replied to and resolved. In
`62a8be3dd32` that lookup became a single `OrganizationMembers` query,
which also covers membership and excludes system and deleted users.
- Codex review on `62a8be3dd32` (the `owner_id` revision): two P2s. An
explicit zero `owner_id` was treated as omitted and created the chat for
the caller; fixed in `f54b4f33d36` with a 400 and `OwnerIDNil` (red on
the old head). Creation and the read-back still ran as the caller while
the preflight ran as the owner; fixed in the same commit by passing
`ownerCtx` to `CreateChat`, `GetChatByID`, title generation, and the
file-metadata fetch. That second scenario is unreachable today (only the
built-in `owner` role holds `api_key:create` for others, and site-wide
custom roles are refused by both the API and dbauthz), so it has no
dedicated red test. Both threads replied to and resolved.
</details>
<details>
<summary>Remote UAT record (path-based revision)</summary>
Remote UAT on dogfood (chat `d7442df3-693f-4403-805f-2de52f7bdbed`, Xum
sub-agent as critical runner) tested head `21ed6b389cc`, the last
path-based revision. Licensed dev server, real Haiku 4.5 model, 77
logged API requests, 23 inspected screenshots. Endorsed verdict:
**PASS**. Site owner creates a chat for member X: X sees it, gets real
answers to the admin prompt and to follow-ups, and state survives reload
and mid-response refresh. The creating admin gets `403 Only the chat
owner may send messages.` and a read-only view; an unrelated member gets
404. Org admin, member, user-admin, and template-admin callers get 403;
owner-role service account 201. Suspended, dormant, and service-account
targets 400; owner-inaccessible workspace, model config, or MCP server
400; 300 KiB body 413. The `owner_id` revision changes only how the
owner is supplied and the non-member response (400 instead of 404); the
authorization and eligibility gates it exercised are unchanged and
covered by `TestPostChats_OwnerID`.
Non-blocking findings for the author's judgment, none of them
regressions of this PR:
1. X's UI shows no author on the admin-written first message and offers
X "Edit" on it; `created_by` carries the admin but the frontend does not
surface it.
2. A site owner who is not a member of the organization can still create
a chat for its members (201), while a self-owned `POST /chats` returns
403 for the same organization; same asymmetry as `postUserWorkspaces`.
3. The creating admin can archive, rename, and interrupt X's chat
although it cannot message it (pre-existing chat authz).
4. Owner-inaccessible model config or MCP server is reported as "not
found or disabled" with no hint that the owner, not the caller, lacks
access.
5. Dormant (never logged in) targets are refused because AI Bridge
rejects non-active users; a new hire cannot be given a chat until first
login.
6. The endpoint docs list only 201 and 413.
</details>
> Xum (an AI agent) acted on behalf of @ibetitsmike for this PR.
223 KiB
Generated
title, description
| title | description |
|---|---|
| Chats | REST endpoints for Coder Agents Chats API (programmatic agent sessions). |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 101 | Switching Protocols | Switching 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q |
query | string | false | Search 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>. |
label |
query | array[string] | false | Filter by label as key:value. Repeat for multiple (AND logic). |
after_id |
query | string(uuid) | false | After ID |
limit |
query | integer | false | Page limit |
offset |
query | integer | false | Page 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | array of codersdk.Chat |
Response Schema
Status Code 200
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
[array item] |
array | false | ||
» agent_id |
string(uuid) | false | ||
» archived |
boolean | false | ||
» build_id |
string(uuid) | false | ||
» children |
codersdk.Chat | false | Children 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_type |
codersdk.ChatClientType | false | ||
» context |
codersdk.ChatContext | false | Context 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. | |
»» dirty |
boolean | false | Dirty is true when the agent's latest snapshot hash differs from the chat's pinned hash. | |
»» dirty_since |
string(date-time) | false | Dirty since is when drift was first detected; nil when not dirty. | |
»» error |
string | false | Error is the snapshot-level error copied from the pinned snapshot (empty when healthy). | |
»» resources |
array | false | Resources 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. | |
»»» error |
string | false | Error explains a non-ok Status; empty when healthy. May also carry a non-fatal warning when Status is ok. | |
»»» kind |
codersdk.ChatContextResourceKind | false | ||
»»» size_bytes |
integer | false | Size bytes is the original payload size in bytes. | |
»»» skill_description |
string | false | ||
»»» skill_name |
string | false | Skill name and SkillDescription are populated only for skill kinds. | |
»»» source |
string | false | Source 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. | |
»»» status |
codersdk.ChatContextResourceStatus | false | Status 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. | |
»»» tools |
array | false | Tools lists the tools exposed by an MCP server. Populated only for the mcp_server kind; nil otherwise. | |
»»»» description |
string | false | Description is the tool's human-readable summary; may be empty. | |
»»»» name |
string | false | Name is the tool name with the <server>__ prefix the agent adds stripped, so it reads as the server exposes it. |
|
» created_at |
string(date-time) | false | ||
» diff_status |
codersdk.ChatDiffStatus | false | ||
»» additions |
integer | false | ||
»» approved |
boolean | false | ||
»» author_avatar_url |
string | false | ||
»» author_login |
string | false | ||
»» base_branch |
string | false | ||
»» changed_files |
integer | false | ||
»» changes_requested |
boolean | false | ||
»» chat_id |
string(uuid) | false | ||
»» commits |
integer | false | ||
»» deletions |
integer | false | ||
»» head_branch |
string | false | ||
»» pr_number |
integer | false | ||
»» pull_request_draft |
boolean | false | ||
»» pull_request_state |
string | false | ||
»» pull_request_title |
string | false | ||
»» refreshed_at |
string(date-time) | false | ||
»» reviewer_count |
integer | false | ||
»» stale_at |
string(date-time) | false | ||
»» url |
string | false | ||
» files |
array | false | ||
»» created_at |
string(date-time) | false | ||
»» id |
string(uuid) | false | ||
»» mime_type |
string | false | ||
»» name |
string | false | ||
»» organization_id |
string(uuid) | false | ||
»» owner_id |
string(uuid) | false | ||
»» size_bytes |
integer | false | ||
» has_unread |
boolean | false | Has unread is true when assistant messages exist beyond the owner's read cursor, which updates on stream connect and disconnect. | |
» id |
string(uuid) | false | ||
» labels |
object | false | ||
»» [any property] |
string | false | ||
» last_error |
codersdk.ChatError | false | ||
»» detail |
string | false | Detail is optional provider-specific context shown alongside the normalized error message when available. | |
»» kind |
codersdk.ChatErrorKind | false | Kind classifies the error for consistent client rendering. | |
»» message |
string | false | Message is the normalized, user-facing error message. | |
»» provider |
string | false | Provider identifies the upstream model provider when known. | |
»» retryable |
boolean | false | Retryable reports whether the underlying error is transient. | |
»» status_code |
integer | false | Status code is the best-effort upstream HTTP status code. | |
» last_model_config_id |
string(uuid) | false | ||
» last_reasoning_effort |
string | false | ||
» last_turn_summary |
string | false | ||
» mcp_server_ids |
array | false | ||
» organization_id |
string(uuid) | false | ||
» owner_id |
string(uuid) | false | ||
» owner_name |
string | false | ||
» owner_username |
string | false | ||
» parent_chat_id |
string(uuid) | false | ||
» pin_order |
integer | false | ||
» plan_mode |
codersdk.ChatPlanMode | false | ||
» queued_for_capacity |
boolean | false | Queued 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_id |
string(uuid) | false | ||
» shared |
boolean | false | Shared is true when this chat's root chat has explicit user or group ACL entries. | |
» status |
codersdk.ChatStatus | false | ||
» summary |
string | false | Summary is the persisted whole-chat summary, generated in the background. It is nil until the first summary has been produced. | |
» title |
string | false | ||
» updated_at |
string(date-time) | false | ||
» warnings |
array | false | ||
» workspace_id |
string(uuid) | false |
Enumerated Values
| Property | Value(s) |
|---|---|
client_type |
api, ui |
kind |
auth, 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 |
status |
error, excluded, interrupting, invalid, ok, oversize, requires_action, running, unreadable, waiting |
plan_mode |
plan |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.CreateChatRequest | true | Create 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Created | codersdk.Chat |
| 413 | Payload Too Large | Request body exceeds 256 KiB | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
workspace_ids |
query | string | false | Comma-separated workspace IDs |
Example responses
200 Response
{
"property1": "string",
"property2": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | coderd.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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.UpdateChatAutoArchiveDaysRequest | true | Request body |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.UpdateChatDebugLoggingAllowUsersRequest | true | Request body |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.UpdateChatDebugRetentionDaysRequest | true | Request body |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.UpdateChatPersonalModelOverridesAdminSettingsRequest | true | Request body |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.UpdateChatPlanModeInstructionsRequest | true | Request body |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.UpdateChatSystemPromptRequest | true | Request body |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.UpdateUserChatDebugLoggingRequest | true | Request body |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.UserChatCustomPrompt | true | Request body |
Example responses
200 Response
{
"custom_prompt": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.UpdateChatWorkspaceTTLRequest | true | Request body |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organization |
query | string(uuid) | true | Organization ID |
Content-Disposition |
header | string | true | Attachment disposition carrying the file name |
body |
body | string | true | Raw file binary data |
Example responses
201 Response
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Created | codersdk.UploadChatFileResponse |
| 413 | Payload Too Large | Request body exceeds 10 MiB | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
file |
path | string(uuid) | true | File ID |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
body |
body | codersdk.UpdateChatRequest | true | Update chat request |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
Example responses
200 Response
{
"chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
"request_count": 0,
"total_cost_micros": 0,
"unpriced_request_count": 0
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
before_id |
query | integer | false | Return messages with id < before_id |
after_id |
query | integer | false | Return messages with id > after_id |
limit |
query | integer | false | Page 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": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
"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": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"file_name": "string",
"hook_rewritten": true,
"is_error": true,
"is_media": true,
"mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
"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": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
"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": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"file_name": "string",
"hook_rewritten": true,
"is_error": true,
"is_media": true,
"mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
"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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
body |
body | codersdk.CreateChatMessageRequest | true | Create 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": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
"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": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"file_name": "string",
"hook_rewritten": true,
"is_error": true,
"is_media": true,
"mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
"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": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
"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": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"file_name": "string",
"hook_rewritten": true,
"is_error": true,
"is_media": true,
"mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
"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": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
"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": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"file_name": "string",
"hook_rewritten": true,
"is_error": true,
"is_media": true,
"mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
"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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
message |
path | integer | true | Message ID |
body |
body | codersdk.EditChatMessageRequest | true | Edit 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": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
"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": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"file_name": "string",
"hook_rewritten": true,
"is_error": true,
"is_media": true,
"mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
"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": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
"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": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"file_name": "string",
"hook_rewritten": true,
"is_error": true,
"is_media": true,
"mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
"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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
limit |
query | integer | false | Page size, 0 to 2000. 0 (the default) means the server-side default of 500. |
Example responses
200 Response
{
"prompts": [
{
"id": 0,
"text": "string"
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
queuedMessage |
path | integer | true | Queued message ID |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
queuedMessage |
path | integer | true | Queued message ID |
Example responses
202 Response
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 202 | Accepted | Accepted | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
after_id |
query | integer | false | Skip 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": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
"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": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"file_name": "string",
"hook_rewritten": true,
"is_error": true,
"is_media": true,
"mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
"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": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
"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": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"file_name": "string",
"hook_rewritten": true,
"is_error": true,
"is_media": true,
"mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
"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": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
"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": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"file_name": "string",
"hook_rewritten": true,
"is_error": true,
"is_media": true,
"mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
"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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | array of codersdk.ChatStreamEvent |
Response Schema
Status Code 200
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
[array item] |
array | false | ||
» action_required |
codersdk.ChatStreamActionRequired | false | ||
»» tool_calls |
array | false | ||
»»» args |
string | false | ||
»»» tool_call_id |
string | false | ||
»»» tool_name |
string | false | ||
» chat_id |
string(uuid) | false | ||
» error |
codersdk.ChatError | false | ||
»» detail |
string | false | Detail is optional provider-specific context shown alongside the normalized error message when available. | |
»» kind |
codersdk.ChatErrorKind | false | Kind classifies the error for consistent client rendering. | |
»» message |
string | false | Message is the normalized, user-facing error message. | |
»» provider |
string | false | Provider identifies the upstream model provider when known. | |
»» retryable |
boolean | false | Retryable reports whether the underlying error is transient. | |
»» status_code |
integer | false | Status code is the best-effort upstream HTTP status code. | |
» message |
codersdk.ChatMessage | false | ||
»» chat_id |
string(uuid) | false | ||
»» content |
array | false | ||
»»» args |
array | false | ||
»»» args_delta |
string | false | ||
»»» completed_at |
string(date-time) | false | Completed 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). | |
»»» content |
string | false | The code content from the diff that was commented on. | |
»»» context_file_agent_id |
string(uuid) | false | Context 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. | |
»»» context_file_content |
string | false | Context 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_directory |
string | false | Context file directory is the working directory of the workspace agent. Internal only: same purpose as ContextFileOS. | |
»»» context_file_os |
string | false | Context 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_path |
string | false | Context 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_file |
string | false | Context 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_truncated |
boolean | false | Context file truncated indicates the file exceeded the 64KiB instruction file limit and was truncated. | |
»»» created_at |
string(date-time) | false | Created 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. | |
»»» data |
array | false | ||
»»» end_line |
integer | false | ||
»»» file_id |
string(uuid) | false | ||
»»» file_name |
string | false | ||
»»» hook_rewritten |
boolean | false | Hook rewritten indicates that a lifecycle hook replaced model-proposed tool input. | |
»»» is_error |
boolean | false | ||
»»» is_media |
boolean | false | ||
»»» mcp_server_config_id |
string(uuid) | false | ||
»»» media_type |
string | false | ||
»»» name |
string | false | ||
»»» parsed_commands |
array | false | Parsed 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_executed |
boolean | false | Provider executed indicates the tool call was executed by the provider (e.g. Anthropic computer use). | |
»»» provider_metadata |
array | false | Provider metadata holds provider-specific response metadata (e.g. Anthropic cache control hints) as raw JSON. Internal only: stripped by db2sdk before API responses. | |
»»» result |
array | false | ||
»»» result_delta |
string | false | ||
»»» result_reset |
boolean | false | ||
»»» skill_description |
string | false | Skill description is the short description from the skill's SKILL.md frontmatter. | |
»»» skill_dir |
string | false | Skill 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_name |
string | false | Skill name is the kebab-case name of a discovered skill from the workspace's .agents/skills/ directory. | |
»»» source_id |
string | false | ||
»»» start_line |
integer | false | ||
»»» text |
string | false | ||
»»» title |
string | false | ||
»»» tool_call_id |
string | false | ||
»»» tool_name |
string | false | ||
»»» type |
codersdk.ChatMessagePartType | false | ||
»»» url |
string | false | ||
»» created_at |
string(date-time) | false | ||
»» created_by |
string(uuid) | false | ||
»» id |
integer | false | ||
»» model_config_id |
string(uuid) | false | ||
»» role |
codersdk.ChatMessageRole | false | ||
»» usage |
codersdk.ChatMessageUsage | false | ||
»»» cache_creation_tokens |
integer | false | ||
»»» cache_read_tokens |
integer | false | ||
»»» context_limit |
integer | false | ||
»»» input_tokens |
integer | false | ||
»»» output_tokens |
integer | false | ||
»»» reasoning_tokens |
integer | false | ||
»»» total_tokens |
integer | false | ||
» message_part |
codersdk.ChatStreamMessagePart | false | ||
»» generation_attempt |
integer | false | ||
»» history_version |
integer | false | ||
»» part |
codersdk.ChatMessagePart | false | ||
»» role |
codersdk.ChatMessageRole | false | ||
»» seq |
integer | false | ||
» queued_messages |
array | false | ||
»» chat_id |
string(uuid) | false | ||
»» content |
array | false | ||
»» created_at |
string(date-time) | false | ||
»» id |
integer | false | ||
»» model_config_id |
string(uuid) | false | ||
» retry |
codersdk.ChatStreamRetry | false | ||
»» attempt |
integer | false | Attempt is the 1-indexed retry attempt number. | |
»» delay_ms |
integer | false | Delay ms is the backoff delay in milliseconds before the retry. | |
»» error |
string | false | Error is the normalized error message from the failed attempt. | |
»» kind |
codersdk.ChatErrorKind | false | Kind classifies the retry reason for consistent client rendering. | |
»» provider |
string | false | Provider identifies the upstream model provider when known. | |
»» retrying_at |
string(date-time) | false | Retrying at is the timestamp when the retry will be attempted. | |
»» status_code |
integer | false | Status code is the best-effort upstream HTTP status code. | |
» status |
codersdk.ChatStreamStatus | false | ||
»» status |
codersdk.ChatStatus | false | ||
» type |
codersdk.ChatStreamEventType | false |
Enumerated Values
| Property | Value(s) |
|---|---|
kind |
auth, config, content_filter, generic, hook_denied, hook_dispatch_failed, missing_key, overloaded, provider_disabled, rate_limit, stream_silence_timeout, timeout, usage_limit |
type |
action_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 |
role |
assistant, system, tool, user |
status |
error, 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
Example responses
200 Response
{
"title": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
chat |
path | string(uuid) | true | Chat ID |
body |
body | codersdk.SubmitToolResultsRequest | true | Request body |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organization |
path | string | true | Organization 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": {
"reasoning_model": true,
"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_mode": "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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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": {
"reasoning_model": true,
"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_mode": "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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organization |
path | string | true | Organization name or ID |
body |
body | codersdk.CreateChatModelRequest | true | Model |
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": {
"reasoning_model": true,
"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_mode": "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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Created | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user |
path | string | true | User 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | array of codersdk.UserAIProviderKeyConfig |
Response Schema
Status Code 200
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
[array item] |
array | false | ||
» byok_enabled |
boolean | false | ||
» has_provider_api_key |
boolean | false | ||
» has_user_api_key |
boolean | false | ||
» provider |
codersdk.AIProviderSummary | false | ||
»» deleted |
boolean | false | ||
»» display_name |
string | false | ||
»» enabled |
boolean | false | ||
»» icon |
string | false | ||
»» id |
string(uuid) | false | ||
»» name |
string | false | ||
»» type |
codersdk.AIProviderType | false |
Enumerated Values
| Property | Value(s) |
|---|---|
type |
anthropic, 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user |
path | string | true | User ID, username, or me |
aiProvider |
path | string(uuid) | true | AI provider ID |
body |
body | codersdk.CreateUserAIProviderKeyRequest | true | Request 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user |
path | string | true | User ID, username, or me |
aiProvider |
path | string(uuid) | true | AI provider ID |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | No Content |
To perform this operation, you must be authenticated. Learn more.