Files
Nick Vigilanteandcoder[bot] 579b9995e8 fix: document WebSocket routes as 101 responses in the Swagger spec (#30125)
Six WebSocket routes were documented as `200` responses: `chats/watch`,
`chats/{chat}/stream`, `chats/{chat}/stream/git`,
`chats/{chat}/stream/parts`, `workspaces/{workspace}/watch-ws`, and
`workspaceagents/{workspaceagent}/watch-metadata-ws`.

Mark them `@Success 101`, matching the other WebSocket routes, and
describe each message. `chats/{chat}/stream` and `stream/parts` send a
JSON array batch of events per message, so they keep `{array}`; the
others send one event per message.

Also document that the previous template version route returns `204`
with no body when there is no previous version.

Part of DOCS-1122, split from #30121.

<details>
<summary>CI flakes unrelated to this change</summary>

On `d23267b7c3`, two checks failed in code this PR does not touch.

-
[`TestChatTurnStopsAtStepLimit/Default`](https://github.com/coder/coder/actions/runs/40809166900/job/123235512188)
in `coderd/x/chatd` (test-go-pg, ubuntu): this PR changes only Swagger
comment annotations and generated docs, and does not touch the `chatd`
package.
-
[`updateWorkspace.spec.ts:76`](https://github.com/coder/coder/actions/runs/40809166900/job/123235512158)
(test-e2e): this PR changes no UI code, and the test exercises workspace
parameter updates.

</details>

---
🤖 Built with AI assistance.

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
2026-11-18 14:05:18 -05:00

290 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, status:<waiting|running|error|requires_action|interrupting|paused> (chat status, repeated or comma-separated), pr_status:<draft|open|merged|closed|none> (none matches chats with no pull request) 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
project_id query string(uuid) false Only chats in this project.

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",
          "source_path": "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,
      "git_branch": "string",
      "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",
      "remote_origin": "string",
      "reviewer_count": 0,
      "stale_at": "2019-08-24T14:15:22Z",
      "url": "string"
    },
    "diff_statuses": [
      {
        "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,
        "git_branch": "string",
        "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",
        "remote_origin": "string",
        "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",
    "inline_mcp_servers": [
      {
        "allow_in_subagents": true,
        "created_at": "2019-08-24T14:15:22Z",
        "forward_coder_headers": true,
        "has_custom_headers": true,
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "slug": "string",
        "tool_allow_list": [
          "string"
        ],
        "tool_deny_list": [
          "string"
        ],
        "updated_at": "2019-08-24T14:15:22Z",
        "url": "string"
      }
    ],
    "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",
    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
    "queued_for_capacity": true,
    "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
    "shared": true,
    "status": "waiting",
    "summary": "string",
    "title": "string",
    "title_source": "fallback",
    "title_updated_at": "2019-08-24T14:15:22Z",
    "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 workspace-context inventory, 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, the server name for an MCP server, or an ACP harness slug.
»»» source_path string false Source path is the configuration directory for an ACP harness.
»»» 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 Diff status is the primary pull request. It is the ref with the most recent git report.
»» 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
»» git_branch string 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
»» remote_origin string false
»» reviewer_count integer false
»» stale_at string(date-time) false
»» url string false
» diff_statuses array false Diff statuses lists every ref the chat tracks. The order is stable and follows the first report of each ref. DiffStatus marks the primary.
»» 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
»» git_branch string 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
»» remote_origin string 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 and via UpdateChatRequest.Read.
» id string(uuid) false
» inline_mcp_servers array false Inline mcp servers lists the inline MCP servers declared on the chat, without headers. Only the single-chat GET sets it. Experimental.
»» allow_in_subagents boolean false
»» created_at string(date-time) false
»» forward_coder_headers boolean false
»» has_custom_headers boolean false
»» id string(uuid) false
»» slug string false
»» tool_allow_list array false
»» tool_deny_list array false
»» updated_at string(date-time) false
»» url string false URL is empty unless the chat owner makes the request.
» 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
» project_id string(uuid) 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
» title_source codersdk.ChatTitleSource false Title source is where Title came from. A title write applies only when the current source ranks the same as or lower than the incoming one, in the order fallback, generated, user.
» title_updated_at string(date-time) false Title updated at orders title changes. Title writes do not change UpdatedAt.
» updated_at string(date-time) false
» warnings array false
» workspace_id string(uuid) false

Enumerated Values

Property Value(s)
client_type api, ui
kind acp_harness, 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, paused, requires_action, running, unreadable, waiting
plan_mode plan
title_source fallback, generated, user

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",
      "skill_name": "string",
      "skill_source": "personal",
      "start_line": 0,
      "text": "string",
      "type": "text",
      "workspace_file_media_type": "string",
      "workspace_file_name": "string",
      "workspace_file_path": "string",
      "workspace_file_size": 0,
      "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
    }
  ],
  "inline_mcp_servers": [
    {
      "allow_in_subagents": true,
      "forward_coder_headers": true,
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "slug": "string",
      "tool_allow_list": [
        "string"
      ],
      "tool_deny_list": [
        "string"
      ],
      "url": "string"
    }
  ],
  "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",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "reasoning_effort": "string",
  "system_prompt": "string",
  "title": "string",
  "unsafe_dynamic_tools": [
    {
      "description": "string",
      "input_schema": {},
      "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",
            "source_path": "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,
        "git_branch": "string",
        "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",
        "remote_origin": "string",
        "reviewer_count": 0,
        "stale_at": "2019-08-24T14:15:22Z",
        "url": "string"
      },
      "diff_statuses": [
        {
          "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,
          "git_branch": "string",
          "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",
          "remote_origin": "string",
          "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",
      "inline_mcp_servers": [
        {
          "allow_in_subagents": true,
          "created_at": "2019-08-24T14:15:22Z",
          "forward_coder_headers": true,
          "has_custom_headers": true,
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "slug": "string",
          "tool_allow_list": [
            "string"
          ],
          "tool_deny_list": [
            "string"
          ],
          "updated_at": "2019-08-24T14:15:22Z",
          "url": "string"
        }
      ],
      "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",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "queued_for_capacity": true,
      "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
      "shared": true,
      "status": "waiting",
      "summary": "string",
      "title": "string",
      "title_source": "fallback",
      "title_updated_at": "2019-08-24T14:15:22Z",
      "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",
        "source_path": "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,
    "git_branch": "string",
    "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",
    "remote_origin": "string",
    "reviewer_count": 0,
    "stale_at": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "diff_statuses": [
    {
      "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,
      "git_branch": "string",
      "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",
      "remote_origin": "string",
      "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",
  "inline_mcp_servers": [
    {
      "allow_in_subagents": true,
      "created_at": "2019-08-24T14:15:22Z",
      "forward_coder_headers": true,
      "has_custom_headers": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "slug": "string",
      "tool_allow_list": [
        "string"
      ],
      "tool_deny_list": [
        "string"
      ],
      "updated_at": "2019-08-24T14:15:22Z",
      "url": "string"
    }
  ],
  "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",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "queued_for_capacity": true,
  "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
  "shared": true,
  "status": "waiting",
  "summary": "string",
  "title": "string",
  "title_source": "fallback",
  "title_updated_at": "2019-08-24T14:15:22Z",
  "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
400 Bad Request Bad Request codersdk.Response
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 advisor config

Code samples

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

GET /api/v2/chats/config/advisor

Example responses

200 Response

{
  "enabled": true,
  "max_output_tokens": 0,
  "max_uses_per_run": 0
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.AdvisorConfig

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

Update chat advisor config

Code samples

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

PUT /api/v2/chats/config/advisor

Body parameter

{
  "max_output_tokens": 0,
  "max_uses_per_run": 0
}

Parameters

Name In Type Required Description
body body codersdk.UpdateAdvisorConfigRequest true Request body

Example responses

400 Response

Responses

Status Meaning Description Schema
204 No Content No Content
400 Bad Request Bad Request codersdk.Response
403 Forbidden Forbidden codersdk.Response

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 filename as a quoted string.
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

Upgrades to a WebSocket and sends one event per message. The server closes the connection if you send a message.

Example responses

101 Response

{
  "changed_diff_status": {
    "ref": {
      "git_branch": "string",
      "remote_origin": "string"
    },
    "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,
      "git_branch": "string",
      "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",
      "remote_origin": "string",
      "reviewer_count": 0,
      "stale_at": "2019-08-24T14:15:22Z",
      "url": "string"
    }
  },
  "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",
          "source_path": "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,
      "git_branch": "string",
      "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",
      "remote_origin": "string",
      "reviewer_count": 0,
      "stale_at": "2019-08-24T14:15:22Z",
      "url": "string"
    },
    "diff_statuses": [
      {
        "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,
        "git_branch": "string",
        "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",
        "remote_origin": "string",
        "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",
    "inline_mcp_servers": [
      {
        "allow_in_subagents": true,
        "created_at": "2019-08-24T14:15:22Z",
        "forward_coder_headers": true,
        "has_custom_headers": true,
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "slug": "string",
        "tool_allow_list": [
          "string"
        ],
        "tool_deny_list": [
          "string"
        ],
        "updated_at": "2019-08-24T14:15:22Z",
        "url": "string"
      }
    ],
    "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",
    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
    "queued_for_capacity": true,
    "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
    "shared": true,
    "status": "waiting",
    "summary": "string",
    "title": "string",
    "title_source": "fallback",
    "title_updated_at": "2019-08-24T14:15:22Z",
    "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
101 Switching Protocols Switching Protocols 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",
            "source_path": "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,
        "git_branch": "string",
        "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",
        "remote_origin": "string",
        "reviewer_count": 0,
        "stale_at": "2019-08-24T14:15:22Z",
        "url": "string"
      },
      "diff_statuses": [
        {
          "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,
          "git_branch": "string",
          "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",
          "remote_origin": "string",
          "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",
      "inline_mcp_servers": [
        {
          "allow_in_subagents": true,
          "created_at": "2019-08-24T14:15:22Z",
          "forward_coder_headers": true,
          "has_custom_headers": true,
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "slug": "string",
          "tool_allow_list": [
            "string"
          ],
          "tool_deny_list": [
            "string"
          ],
          "updated_at": "2019-08-24T14:15:22Z",
          "url": "string"
        }
      ],
      "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",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "queued_for_capacity": true,
      "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
      "shared": true,
      "status": "waiting",
      "summary": "string",
      "title": "string",
      "title_source": "fallback",
      "title_updated_at": "2019-08-24T14:15:22Z",
      "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",
        "source_path": "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,
    "git_branch": "string",
    "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",
    "remote_origin": "string",
    "reviewer_count": 0,
    "stale_at": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "diff_statuses": [
    {
      "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,
      "git_branch": "string",
      "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",
      "remote_origin": "string",
      "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",
  "inline_mcp_servers": [
    {
      "allow_in_subagents": true,
      "created_at": "2019-08-24T14:15:22Z",
      "forward_coder_headers": true,
      "has_custom_headers": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "slug": "string",
      "tool_allow_list": [
        "string"
      ],
      "tool_deny_list": [
        "string"
      ],
      "updated_at": "2019-08-24T14:15:22Z",
      "url": "string"
    }
  ],
  "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",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "queued_for_capacity": true,
  "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
  "shared": true,
  "status": "waiting",
  "summary": "string",
  "title": "string",
  "title_source": "fallback",
  "title_updated_at": "2019-08-24T14:15:22Z",
  "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 'Accept: */*' \
  -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",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "read": true,
  "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

Example responses

400 Response

Responses

Status Meaning Description Schema
204 No Content No Content
400 Bad Request Bad Request codersdk.Response

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

List chat attachments

Code samples

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

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

Returns every file part in the user-visible user and assistant messages of a chat, newest first, so a client can list a chat's attachments without paging through every message in the chat.

Parameters

Name In Type Required Description
chat path string(uuid) true Chat ID
before_id query integer false Return attachments from messages with id < before_id

Example responses

200 Response

{
  "attachments": [
    {
      "file": {
        "data": "string",
        "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
        "media_type": "string",
        "name": "string",
        "type": "file"
      },
      "message_id": 0,
      "part_index": 0,
      "role": "user"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.ChatAttachmentsResponse

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",
            "source_path": "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,
        "git_branch": "string",
        "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",
        "remote_origin": "string",
        "reviewer_count": 0,
        "stale_at": "2019-08-24T14:15:22Z",
        "url": "string"
      },
      "diff_statuses": [
        {
          "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,
          "git_branch": "string",
          "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",
          "remote_origin": "string",
          "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",
      "inline_mcp_servers": [
        {
          "allow_in_subagents": true,
          "created_at": "2019-08-24T14:15:22Z",
          "forward_coder_headers": true,
          "has_custom_headers": true,
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "slug": "string",
          "tool_allow_list": [
            "string"
          ],
          "tool_deny_list": [
            "string"
          ],
          "updated_at": "2019-08-24T14:15:22Z",
          "url": "string"
        }
      ],
      "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",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "queued_for_capacity": true,
      "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
      "shared": true,
      "status": "waiting",
      "summary": "string",
      "title": "string",
      "title_source": "fallback",
      "title_updated_at": "2019-08-24T14:15:22Z",
      "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",
        "source_path": "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,
    "git_branch": "string",
    "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",
    "remote_origin": "string",
    "reviewer_count": 0,
    "stale_at": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "diff_statuses": [
    {
      "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,
      "git_branch": "string",
      "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",
      "remote_origin": "string",
      "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",
  "inline_mcp_servers": [
    {
      "allow_in_subagents": true,
      "created_at": "2019-08-24T14:15:22Z",
      "forward_coder_headers": true,
      "has_custom_headers": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "slug": "string",
      "tool_allow_list": [
        "string"
      ],
      "tool_deny_list": [
        "string"
      ],
      "updated_at": "2019-08-24T14:15:22Z",
      "url": "string"
    }
  ],
  "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",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "queued_for_capacity": true,
  "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
  "shared": true,
  "status": "waiting",
  "summary": "string",
  "title": "string",
  "title_source": "fallback",
  "title_updated_at": "2019-08-24T14:15:22Z",
  "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
origin query string false Remote origin selecting the ref to diff
branch query string false Git branch selecting the ref to diff

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

Interrupts the active turn of a chat. If the chat has nothing to interrupt, for example because its turn already ended, the endpoint returns the chat unchanged.

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",
            "source_path": "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,
        "git_branch": "string",
        "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",
        "remote_origin": "string",
        "reviewer_count": 0,
        "stale_at": "2019-08-24T14:15:22Z",
        "url": "string"
      },
      "diff_statuses": [
        {
          "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,
          "git_branch": "string",
          "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",
          "remote_origin": "string",
          "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",
      "inline_mcp_servers": [
        {
          "allow_in_subagents": true,
          "created_at": "2019-08-24T14:15:22Z",
          "forward_coder_headers": true,
          "has_custom_headers": true,
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "slug": "string",
          "tool_allow_list": [
            "string"
          ],
          "tool_deny_list": [
            "string"
          ],
          "updated_at": "2019-08-24T14:15:22Z",
          "url": "string"
        }
      ],
      "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",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "queued_for_capacity": true,
      "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
      "shared": true,
      "status": "waiting",
      "summary": "string",
      "title": "string",
      "title_source": "fallback",
      "title_updated_at": "2019-08-24T14:15:22Z",
      "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",
        "source_path": "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,
    "git_branch": "string",
    "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",
    "remote_origin": "string",
    "reviewer_count": 0,
    "stale_at": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "diff_statuses": [
    {
      "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,
      "git_branch": "string",
      "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",
      "remote_origin": "string",
      "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",
  "inline_mcp_servers": [
    {
      "allow_in_subagents": true,
      "created_at": "2019-08-24T14:15:22Z",
      "forward_coder_headers": true,
      "has_custom_headers": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "slug": "string",
      "tool_allow_list": [
        "string"
      ],
      "tool_deny_list": [
        "string"
      ],
      "updated_at": "2019-08-24T14:15:22Z",
      "url": "string"
    }
  ],
  "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",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "queued_for_capacity": true,
  "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
  "shared": true,
  "status": "waiting",
  "summary": "string",
  "title": "string",
  "title_source": "fallback",
  "title_updated_at": "2019-08-24T14:15:22Z",
  "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": {},
          "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": "string",
          "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",
          "narration": true,
          "parsed_commands": [
            [
              "string"
            ]
          ],
          "provider_executed": true,
          "reasoning_delta": "string",
          "result": {},
          "result_delta": "string",
          "result_reset": true,
          "skill_description": "string",
          "skill_dir": "string",
          "skill_name": "string",
          "skill_source": "personal",
          "source_id": "string",
          "start_line": 0,
          "text": "string",
          "title": "string",
          "tool_call_id": "string",
          "tool_name": "string",
          "type": "text",
          "url": "string",
          "workspace_file_media_type": "string",
          "workspace_file_name": "string",
          "workspace_file_path": "string",
          "workspace_file_size": 0,
          "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
      "id": 0,
      "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205",
      "queued_message_id": 0,
      "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": [
    {
      "busy_behavior": "steer",
      "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
      "content": [
        {
          "args": {},
          "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": "string",
          "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",
          "narration": true,
          "parsed_commands": [
            [
              "string"
            ]
          ],
          "provider_executed": true,
          "reasoning_delta": "string",
          "result": {},
          "result_delta": "string",
          "result_reset": true,
          "skill_description": "string",
          "skill_dir": "string",
          "skill_name": "string",
          "skill_source": "personal",
          "source_id": "string",
          "start_line": 0,
          "text": "string",
          "title": "string",
          "tool_call_id": "string",
          "tool_name": "string",
          "type": "text",
          "url": "string",
          "workspace_file_media_type": "string",
          "workspace_file_name": "string",
          "workspace_file_path": "string",
          "workspace_file_size": 0,
          "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "editing_since": "2019-08-24T14:15:22Z",
      "id": 0,
      "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205",
      "reasoning_effort": "string"
    }
  ],
  "snapshot_version": 0,
  "turn_start_id": 0
}

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": "steer",
  "content": [
    {
      "content": "string",
      "end_line": 0,
      "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
      "file_name": "string",
      "skill_name": "string",
      "skill_source": "personal",
      "start_line": 0,
      "text": "string",
      "type": "text",
      "workspace_file_media_type": "string",
      "workspace_file_name": "string",
      "workspace_file_path": "string",
      "workspace_file_size": 0,
      "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
    }
  ],
  "inline_mcp_servers": [
    {
      "allow_in_subagents": true,
      "forward_coder_headers": true,
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "slug": "string",
      "tool_allow_list": [
        "string"
      ],
      "tool_deny_list": [
        "string"
      ],
      "url": "string"
    }
  ],
  "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": {},
        "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": "string",
        "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",
        "narration": true,
        "parsed_commands": [
          [
            "string"
          ]
        ],
        "provider_executed": true,
        "reasoning_delta": "string",
        "result": {},
        "result_delta": "string",
        "result_reset": true,
        "skill_description": "string",
        "skill_dir": "string",
        "skill_name": "string",
        "skill_source": "personal",
        "source_id": "string",
        "start_line": 0,
        "text": "string",
        "title": "string",
        "tool_call_id": "string",
        "tool_name": "string",
        "type": "text",
        "url": "string",
        "workspace_file_media_type": "string",
        "workspace_file_name": "string",
        "workspace_file_path": "string",
        "workspace_file_size": 0,
        "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
    "id": 0,
    "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205",
    "queued_message_id": 0,
    "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": {},
          "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": "string",
          "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",
          "narration": true,
          "parsed_commands": [
            [
              "string"
            ]
          ],
          "provider_executed": true,
          "reasoning_delta": "string",
          "result": {},
          "result_delta": "string",
          "result_reset": true,
          "skill_description": "string",
          "skill_dir": "string",
          "skill_name": "string",
          "skill_source": "personal",
          "source_id": "string",
          "start_line": 0,
          "text": "string",
          "title": "string",
          "tool_call_id": "string",
          "tool_name": "string",
          "type": "text",
          "url": "string",
          "workspace_file_media_type": "string",
          "workspace_file_name": "string",
          "workspace_file_path": "string",
          "workspace_file_size": 0,
          "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
      "id": 0,
      "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205",
      "queued_message_id": 0,
      "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": {
    "busy_behavior": "steer",
    "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
    "content": [
      {
        "args": {},
        "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": "string",
        "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",
        "narration": true,
        "parsed_commands": [
          [
            "string"
          ]
        ],
        "provider_executed": true,
        "reasoning_delta": "string",
        "result": {},
        "result_delta": "string",
        "result_reset": true,
        "skill_description": "string",
        "skill_dir": "string",
        "skill_name": "string",
        "skill_source": "personal",
        "source_id": "string",
        "start_line": 0,
        "text": "string",
        "title": "string",
        "tool_call_id": "string",
        "tool_name": "string",
        "type": "text",
        "url": "string",
        "workspace_file_media_type": "string",
        "workspace_file_name": "string",
        "workspace_file_path": "string",
        "workspace_file_size": 0,
        "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "editing_since": "2019-08-24T14:15:22Z",
    "id": 0,
    "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205",
    "reasoning_effort": "string"
  },
  "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",
      "skill_name": "string",
      "skill_source": "personal",
      "start_line": 0,
      "text": "string",
      "type": "text",
      "workspace_file_media_type": "string",
      "workspace_file_name": "string",
      "workspace_file_path": "string",
      "workspace_file_size": 0,
      "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
    }
  ],
  "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": {},
        "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": "string",
        "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",
        "narration": true,
        "parsed_commands": [
          [
            "string"
          ]
        ],
        "provider_executed": true,
        "reasoning_delta": "string",
        "result": {},
        "result_delta": "string",
        "result_reset": true,
        "skill_description": "string",
        "skill_dir": "string",
        "skill_name": "string",
        "skill_source": "personal",
        "source_id": "string",
        "start_line": 0,
        "text": "string",
        "title": "string",
        "tool_call_id": "string",
        "tool_name": "string",
        "type": "text",
        "url": "string",
        "workspace_file_media_type": "string",
        "workspace_file_name": "string",
        "workspace_file_path": "string",
        "workspace_file_size": 0,
        "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
    "id": 0,
    "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205",
    "queued_message_id": 0,
    "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": {},
          "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": "string",
          "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",
          "narration": true,
          "parsed_commands": [
            [
              "string"
            ]
          ],
          "provider_executed": true,
          "reasoning_delta": "string",
          "result": {},
          "result_delta": "string",
          "result_reset": true,
          "skill_description": "string",
          "skill_dir": "string",
          "skill_name": "string",
          "skill_source": "personal",
          "source_id": "string",
          "start_line": 0,
          "text": "string",
          "title": "string",
          "tool_call_id": "string",
          "tool_name": "string",
          "type": "text",
          "url": "string",
          "workspace_file_media_type": "string",
          "workspace_file_name": "string",
          "workspace_file_path": "string",
          "workspace_file_size": 0,
          "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
      "id": 0,
      "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205",
      "queued_message_id": 0,
      "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.

Edit chat queued message

Code samples

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

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

Body parameter

{
  "content": [
    {
      "content": "string",
      "end_line": 0,
      "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
      "file_name": "string",
      "skill_name": "string",
      "skill_source": "personal",
      "start_line": 0,
      "text": "string",
      "type": "text",
      "workspace_file_media_type": "string",
      "workspace_file_name": "string",
      "workspace_file_path": "string",
      "workspace_file_size": 0,
      "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
    }
  ],
  "editing": true,
  "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205",
  "reasoning_effort": "string"
}

Parameters

Name In Type Required Description
chat path string(uuid) true Chat ID
queuedMessage path integer true Queued message ID
body body codersdk.EditChatQueuedMessageRequest true Edit chat queued message request

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",
            "source_path": "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,
        "git_branch": "string",
        "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",
        "remote_origin": "string",
        "reviewer_count": 0,
        "stale_at": "2019-08-24T14:15:22Z",
        "url": "string"
      },
      "diff_statuses": [
        {
          "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,
          "git_branch": "string",
          "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",
          "remote_origin": "string",
          "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",
      "inline_mcp_servers": [
        {
          "allow_in_subagents": true,
          "created_at": "2019-08-24T14:15:22Z",
          "forward_coder_headers": true,
          "has_custom_headers": true,
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "slug": "string",
          "tool_allow_list": [
            "string"
          ],
          "tool_deny_list": [
            "string"
          ],
          "updated_at": "2019-08-24T14:15:22Z",
          "url": "string"
        }
      ],
      "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",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "queued_for_capacity": true,
      "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
      "shared": true,
      "status": "waiting",
      "summary": "string",
      "title": "string",
      "title_source": "fallback",
      "title_updated_at": "2019-08-24T14:15:22Z",
      "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",
        "source_path": "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,
    "git_branch": "string",
    "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",
    "remote_origin": "string",
    "reviewer_count": 0,
    "stale_at": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "diff_statuses": [
    {
      "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,
      "git_branch": "string",
      "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",
      "remote_origin": "string",
      "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",
  "inline_mcp_servers": [
    {
      "allow_in_subagents": true,
      "created_at": "2019-08-24T14:15:22Z",
      "forward_coder_headers": true,
      "has_custom_headers": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "slug": "string",
      "tool_allow_list": [
        "string"
      ],
      "tool_deny_list": [
        "string"
      ],
      "updated_at": "2019-08-24T14:15:22Z",
      "url": "string"
    }
  ],
  "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",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "queued_for_capacity": true,
  "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7",
  "shared": true,
  "status": "waiting",
  "summary": "string",
  "title": "string",
  "title_source": "fallback",
  "title_updated_at": "2019-08-24T14:15:22Z",
  "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

Upgrades to a WebSocket and sends each message as a JSON array holding a batch of one or more events. The server closes the connection if you send a message.

Each WebSocket message is a JSON array of events.

The server increases a chat's snapshot_version by 1 each time it changes the chat's messages, queue, or status. A change's snapshot_version is the chat's snapshot_version when the server made the change. Only the newest messages page, which GET /api/v2/chats/{chat}/messages returns when you set neither before_id nor after_id, includes the chat's snapshot_version. The server reads snapshot_version before the messages and the queue, so the page can include changes with a higher snapshot_version. The stream can send changes that are already in the page.

The server reads the chat when the stream opens and each time the chat changes. Each read sends the changes since the previous read. When you set snapshot_version to a value S, the first read sends what changed at a snapshot_version of S or greater:

  • A message event for each message that isn't deleted.
  • A history_reset event for each edit.
  • A queue_update event, if the queue changed.

The server ignores after_id when you set snapshot_version. The server returns 400 Bad Request when snapshot_version isn't an integer, is less than 1, or is greater than the chat's snapshot_version.

On a stream that you open with snapshot_version, the message, queue_update, and history_reset events include snapshot_version. Each read sends these events in order of snapshot_version. Within one snapshot_version, the read sends the history_reset event first, then the message events in order of message ID, then the queue_update event. The status, error, action_required, retry, and preview_reset events of the read come after them. The server sends message_part events between reads.

A history_reset event on such a stream includes history_reset.from_message_id, the ID of a message that was edited. The edit deleted that message and every message after it. When managing history state, delete every message with that ID or higher. After the history_reset event, the stream sends each message with that ID or higher that isn't deleted.

A messages page that you request with before_id includes no snapshot_version. If an edit occurs after the server reads the page, the page can contain messages that the edit deleted.

On each new connection, the server sends the chat's current status again. When the chat has an error, a pending retry, or pending tool calls, the server also sends the error, retry, or action_required event again. The server then again sends the message_part events of the response that the agent is writing, from its first part.

When you don't set snapshot_version, the events don't include snapshot_version, and history_reset events don't include from_message_id. After a history_reset event, the server sends every message in the chat as message events. On a new connection, when after_id is the ID of a message in the chat that isn't deleted, the server sends only the messages with a higher ID that aren't deleted. When after_id is unset or is the ID of a deleted message in the chat, the server sends every message that isn't deleted, after a history_reset event if the chat has a deleted message.

When the server can't subscribe to the chat or read it, the server returns 500 Internal Server Error and doesn't open the WebSocket connection.

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. Ignored when snapshot_version is set
snapshot_version query integer false Send what changed at this snapshot version or later

Example responses

101 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
    },
    "history_reset": {
      "from_message_id": 0
    },
    "message": {
      "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
      "content": [
        {
          "args": {},
          "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": "string",
          "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",
          "narration": true,
          "parsed_commands": [
            [
              "string"
            ]
          ],
          "provider_executed": true,
          "reasoning_delta": "string",
          "result": {},
          "result_delta": "string",
          "result_reset": true,
          "skill_description": "string",
          "skill_dir": "string",
          "skill_name": "string",
          "skill_source": "personal",
          "source_id": "string",
          "start_line": 0,
          "text": "string",
          "title": "string",
          "tool_call_id": "string",
          "tool_name": "string",
          "type": "text",
          "url": "string",
          "workspace_file_media_type": "string",
          "workspace_file_name": "string",
          "workspace_file_path": "string",
          "workspace_file_size": 0,
          "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
      "id": 0,
      "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205",
      "queued_message_id": 0,
      "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": {},
        "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": "string",
        "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",
        "narration": true,
        "parsed_commands": [
          [
            "string"
          ]
        ],
        "provider_executed": true,
        "reasoning_delta": "string",
        "result": {},
        "result_delta": "string",
        "result_reset": true,
        "skill_description": "string",
        "skill_dir": "string",
        "skill_name": "string",
        "skill_source": "personal",
        "source_id": "string",
        "start_line": 0,
        "text": "string",
        "title": "string",
        "tool_call_id": "string",
        "tool_name": "string",
        "type": "text",
        "url": "string",
        "workspace_file_media_type": "string",
        "workspace_file_name": "string",
        "workspace_file_path": "string",
        "workspace_file_size": 0,
        "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
      },
      "role": "system",
      "seq": 0
    },
    "queued_messages": [
      {
        "busy_behavior": "steer",
        "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
        "content": [
          {
            "args": {},
            "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": "string",
            "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",
            "narration": true,
            "parsed_commands": [
              [
                "string"
              ]
            ],
            "provider_executed": true,
            "reasoning_delta": "string",
            "result": {},
            "result_delta": "string",
            "result_reset": true,
            "skill_description": "string",
            "skill_dir": "string",
            "skill_name": "string",
            "skill_source": "personal",
            "source_id": "string",
            "start_line": 0,
            "text": "string",
            "title": "string",
            "tool_call_id": "string",
            "tool_name": "string",
            "type": "text",
            "url": "string",
            "workspace_file_media_type": "string",
            "workspace_file_name": "string",
            "workspace_file_path": "string",
            "workspace_file_size": 0,
            "workspace_file_workspace_id": "74c05446-1c56-4543-82a9-03f2bf73b2ab"
          }
        ],
        "created_at": "2019-08-24T14:15:22Z",
        "editing_since": "2019-08-24T14:15:22Z",
        "id": 0,
        "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205",
        "reasoning_effort": "string"
      }
    ],
    "retry": {
      "attempt": 0,
      "delay_ms": 0,
      "error": "string",
      "kind": "generic",
      "provider": "string",
      "retrying_at": "2019-08-24T14:15:22Z",
      "status_code": 0
    },
    "snapshot_version": 0,
    "status": {
      "status": "waiting"
    },
    "type": "message_part"
  }
]

Responses

Status Meaning Description Schema
101 Switching Protocols Switching Protocols array of codersdk.ChatStreamEvent

Response Schema

Status Code 101

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.
» history_reset codersdk.ChatStreamHistoryReset false History reset is set on history_reset events of streams opened with a snapshot_version.
»» from_message_id integer false From message ID is the ID of a message that was edited. The edit deleted that message and every message after it. When managing history state, delete every message with this ID or higher. The messages that follow were written by the edit or after it and should be kept.
» message codersdk.ChatMessage false
»» chat_id string(uuid) false
»» content array false
»»» args object 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 string(byte) false Data holds an inline file's bytes, which JSON carries as a base64 string.
»»» 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
»»» narration boolean false Narration marks assistant text that the model labeled as commentary on its work rather than its answer. Only providers that label their output set it.
»»» 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).
»»» reasoning_delta string false
»»» result object false Result is the tool output, which can be any JSON value.
»»» 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, and shown to the model for an invoked workspace skill so it can run the skill's scripts.
»»» skill_name string false Skill name is the kebab-case name of the skill.
»»» skill_source codersdk.ChatSkillSource false Skill source is where the invoked skill of a skill-invocation part is stored.
»»» 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
»»» workspace_file_media_type string false Workspace file media type is the best-effort declared MIME type.
»»» workspace_file_name string false Workspace file name is the sanitized basename of a workspace upload.
»»» workspace_file_path string false Workspace file path is the absolute path of a workspace upload. The bytes live on the workspace filesystem; only metadata is persisted on the message.
»»» workspace_file_size integer false Workspace file size is the byte size of a workspace upload.
»»» workspace_file_workspace_id string(uuid) false Workspace file workspace ID identifies the workspace whose filesystem holds the uploaded bytes. References are only readable while the chat stays bound to that workspace.
»» created_at string(date-time) false
»» created_by string(uuid) false
»» id integer false
»» model_config_id string(uuid) false
»» queued_message_id integer false Queued message ID is the ID of the queued message this message was promoted from. It matches ChatQueuedMessage.ID in the response that queued the message. It is nil when the message was not promoted from the queue (edits create a new message without it) or when a server version that did not record the link created it.
»» 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 Reasoning tokens counts reasoning, which output_tokens already includes, so do not add the two.
»»» 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 Queued messages lists the queued messages in delivery order: steer messages first, then queue messages.
»» busy_behavior codersdk.ChatBusyBehavior false Busy behavior is the lane of the message. Steer messages go in before the next model call, and queue messages go in after the turn ends.
»» chat_id string(uuid) false
»» content array false
»» created_at string(date-time) false
»» editing_since string(date-time) false Editing since is set while the owner edits the message. A message under edit and every message behind it wait until the edit ends. A steer message under edit also holds the steer messages ahead of it. A turn that ends at a message under edit pauses the chat.
»» id integer false
»» model_config_id string(uuid) false
»» reasoning_effort string 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.
» snapshot_version integer false Snapshot version is set on the message, queue_update and history_reset events of streams opened with a snapshot_version. It is the chat's snapshot version when the change that the event reports was made. To reconnect, open the stream with the highest one received from the messages page or from events.
» 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
skill_source org, personal, project, workspace
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, skill-invocation, source, status, text, tool-call, tool-result, workspace-file-reference
role assistant, system, tool, user
busy_behavior queue, steer
status error, interrupting, paused, 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

Upgrades to a WebSocket. Each server message is either a changes message with a delta of repository changes after the previous message or an error message, and you can send {"type": "refresh"} to request an immediate re-scan.

Parameters

Name In Type Required Description
chat path string(uuid) true Chat ID

Example responses

101 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
101 Switching Protocols Switching Protocols 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": {},
      "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.

Upload a file to a chat's workspace

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/chats/{chat}/workspace-files \
  -H 'Content-Type: */*' \
  -H 'Accept: application/json' \
  -H 'Content-Disposition: string' \
  -H 'Coder-Session-Token: API_KEY' \
  --data-binary '@archive.zip'

POST /api/v2/chats/{chat}/workspace-files

Streams the request body into the chat workspace's upload directory. The request Content-Type header is recorded as the file's media type. There is no server-imposed size cap; client cancellation aborts the stream and the agent leaves no partial target file behind.

Parameters

Name In Type Required Description
chat path string(uuid) true Chat ID
Content-Disposition header string true Filename of the file (attachment; filename=...)
body body string true Raw file binary data

Example responses

201 Response

{
  "media_type": "string",
  "name": "string",
  "path": "string",
  "size": 0,
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.UploadChatWorkspaceFileResponse
400 Bad Request Bad Request codersdk.Response
403 Forbidden Forbidden codersdk.Response
409 Conflict Conflict codersdk.Response
429 Too Many Requests Too Many Requests codersdk.Response
500 Internal Server Error Internal Server Error codersdk.Response
502 Bad Gateway Bad Gateway codersdk.Response

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

Get organization chat system prompt

Code samples

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

GET /api/v2/organizations/{organization}/chats/config/system-prompt

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID

Example responses

200 Response

{
  "system_prompt": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OrganizationChatSystemPromptResponse

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

Update organization chat system prompt

Code samples

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

PUT /api/v2/organizations/{organization}/chats/config/system-prompt

Body parameter

{
  "system_prompt": "string"
}

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID
body body codersdk.UpdateOrganizationChatSystemPromptRequest 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,
      "computer_use_provider": "anthropic",
      "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,
  "computer_use_provider": "anthropic",
  "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.