coder/docs/reference/api/chats.md at 2ee96f82f947a14861956c18fdd957a439b8a671

opensource/coder

Fork 0

mirror of https://github.com/coder/coder.git synced 2026-10-16 14:48:56 +08:00

Files

T

Michael Suchacz 41f5caafec fix: fold web searches, answer reasoning, and OpenAI narration into working blocks (#30529 )

2026-10-12 22:53:07 +02:00

274 KiB

Generated

Raw Blame History

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>` (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. Requires the chat-projects experiment.

Example responses

[
  {
    "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
    "archived": true,
    "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb",
    "children": [
      {}
    ],
    "client_type": "ui",
    "context": {
      "dirty": true,
      "dirty_since": "2019-08-24T14:15:22Z",
      "error": "string",
      "resources": [
        {
          "error": "string",
          "kind": "instruction_file",
          "size_bytes": 0,
          "skill_description": "string",
          "skill_name": "string",
          "source": "string",
          "status": "ok",
          "tools": [
            {
              "description": "string",
              "name": "string"
            }
          ]
        }
      ]
    },
    "created_at": "2019-08-24T14:15:22Z",
    "diff_status": {
      "additions": 0,
      "approved": true,
      "author_avatar_url": "string",
      "author_login": "string",
      "base_branch": "string",
      "changed_files": 0,
      "changes_requested": true,
      "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
      "commits": 0,
      "deletions": 0,
      "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	Description
`[array item]`	array	false
`» agent_id`	string(uuid)	false
`» archived`	boolean	false
`» build_id`	string(uuid)	false
`» children`	codersdk.Chat	false	Children holds child (subagent) chats nested under this root chat. Always initialized to an empty slice so the JSON field is present as []. Child chats cannot create their own subagents, so nesting depth is capped at 1 and this slice is always empty for child chats.
`» client_type`	codersdk.ChatClientType	false
`» context`	codersdk.ChatContext	false	Context reports the chat's pinned workspace-context state and whether it has drifted from the agent's latest pushed snapshot. Nil when the chat has no pinned context yet.
`»» dirty`	boolean	false	Dirty is true when the agent's latest snapshot hash differs from the chat's pinned hash.
`»» dirty_since`	string(date-time)	false	Dirty since is when drift was first detected; nil when not dirty.
`»» error`	string	false	Error is the snapshot-level error copied from the pinned snapshot (empty when healthy).
`»» resources`	array	false	Resources is the chat's pinned context (instruction files and skills) the prompt is built from, metadata only (no bodies). It is populated only on the single-chat GET response; list and watch payloads leave it nil to stay lightweight.
`»»» error`	string	false	Error explains a non-ok Status; empty when healthy. May also carry a non-fatal warning when Status is ok.
`»»» kind`	codersdk.ChatContextResourceKind	false
`»»» size_bytes`	integer	false	Size bytes is the original payload size in bytes.
`»»» skill_description`	string	false
`»»» skill_name`	string	false	Skill name and SkillDescription are populated only for skill kinds.
`»»» source`	string	false	Source is the resource locator: the canonical file path for an instruction file, the skill directory for a skill, the file path for an MCP config, or the server name for an MCP server.
`»»» status`	codersdk.ChatContextResourceStatus	false	Status is the resource's health. Non-ok resources (invalid, unreadable, oversize, excluded) are still reported so the UI can surface why a resource was dropped from the prompt instead of silently omitting it; their body-specific fields (skill name, tools) are empty.
`»»» tools`	array	false	Tools lists the tools exposed by an MCP server. Populated only for the mcp_server kind; nil otherwise.
`»»»» description`	string	false	Description is the tool's human-readable summary; may be empty.
`»»»» name`	string	false	Name is the tool name with the `<server>__` prefix the agent adds stripped, so it reads as the server exposes it.
`» created_at`	string(date-time)	false
`» diff_status`	codersdk.ChatDiffStatus	false	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`	`auth`, `config`, `content_filter`, `generic`, `hook_denied`, `hook_dispatch_failed`, `instruction_file`, `mcp_config`, `mcp_server`, `missing_key`, `overloaded`, `provider_disabled`, `rate_limit`, `skill`, `stream_silence_timeout`, `timeout`, `usage_limit`
`status`	`error`, `excluded`, `interrupting`, `invalid`, `ok`, `oversize`, `requires_action`, `running`, `unreadable`, `waiting`
`plan_mode`	`plan`
`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

{
  "client_type": "ui",
  "content": [
    {
      "content": "string",
      "end_line": 0,
      "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
      "file_name": "string",
      "start_line": 0,
      "text": "string",
      "type": "text",
      "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": [
        0
      ],
      "name": "string"
    }
  ],
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.CreateChatRequest	true	Create chat request

Example responses

{
  "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  "archived": true,
  "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb",
  "children": [
    {
      "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
      "archived": true,
      "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb",
      "children": [],
      "client_type": "ui",
      "context": {
        "dirty": true,
        "dirty_since": "2019-08-24T14:15:22Z",
        "error": "string",
        "resources": [
          {
            "error": "string",
            "kind": "instruction_file",
            "size_bytes": 0,
            "skill_description": "string",
            "skill_name": "string",
            "source": "string",
            "status": "ok",
            "tools": [
              {
                "description": "string",
                "name": "string"
              }
            ]
          }
        ]
      },
      "created_at": "2019-08-24T14:15:22Z",
      "diff_status": {
        "additions": 0,
        "approved": true,
        "author_avatar_url": "string",
        "author_login": "string",
        "base_branch": "string",
        "changed_files": 0,
        "changes_requested": true,
        "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
        "commits": 0,
        "deletions": 0,
        "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",
        "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

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

Responses

Status	Meaning	Description	Schema
200	OK	OK	coderd.chatsByWorkspaceResponse

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

Get chat auto archive days

Code samples

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

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

Example responses

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "custom_prompt": "string"
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.UserChatCustomPrompt	true	Request body

Example responses

{
  "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

{
  "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

{
  "workspace_ttl_ms": 0
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.UpdateChatWorkspaceTTLRequest	true	Request body

Responses

Status	Meaning	Description	Schema
204	No Content	No Content

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

Upload chat file

Code samples

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

POST /api/v2/chats/files

Parameters

Name	In	Type	Required	Description
`organization`	query	string(uuid)	true	Organization ID
`Content-Disposition`	header	string	true	Attachment disposition carrying the file name
`body`	body	string	true	Raw file binary data

Example responses

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

Responses

Status	Meaning	Description	Schema
201	Created	Created	codersdk.UploadChatFileResponse
413	Payload Too Large	Request body exceeds 10 MiB	codersdk.Response

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

Get chat file

Code samples

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

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

Parameters

Name	In	Type	Required	Description
`file`	path	string(uuid)	true	File ID

Responses

Status	Meaning	Description	Schema
200	OK	OK

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

Watch chat events for a user via WebSockets

Code samples

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

GET /api/v2/chats/watch

Example responses

{
  "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",
          "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
200	OK	OK	codersdk.ChatWatchEvent

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

Get chat by ID

Code samples

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

GET /api/v2/chats/{chat}

Parameters

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

Example responses

{
  "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  "archived": true,
  "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb",
  "children": [
    {
      "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
      "archived": true,
      "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb",
      "children": [],
      "client_type": "ui",
      "context": {
        "dirty": true,
        "dirty_since": "2019-08-24T14:15:22Z",
        "error": "string",
        "resources": [
          {
            "error": "string",
            "kind": "instruction_file",
            "size_bytes": 0,
            "skill_description": "string",
            "skill_name": "string",
            "source": "string",
            "status": "ok",
            "tools": [
              {
                "description": "string",
                "name": "string"
              }
            ]
          }
        ]
      },
      "created_at": "2019-08-24T14:15:22Z",
      "diff_status": {
        "additions": 0,
        "approved": true,
        "author_avatar_url": "string",
        "author_login": "string",
        "base_branch": "string",
        "changed_files": 0,
        "changes_requested": true,
        "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
        "commits": 0,
        "deletions": 0,
        "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",
        "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}

{
  "archived": true,
  "labels": {
    "property1": "string",
    "property2": "string"
  },
  "pin_order": 0,
  "plan_mode": "plan",
  "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

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.

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

{
  "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  "archived": true,
  "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb",
  "children": [
    {
      "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
      "archived": true,
      "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb",
      "children": [],
      "client_type": "ui",
      "context": {
        "dirty": true,
        "dirty_since": "2019-08-24T14:15:22Z",
        "error": "string",
        "resources": [
          {
            "error": "string",
            "kind": "instruction_file",
            "size_bytes": 0,
            "skill_description": "string",
            "skill_name": "string",
            "source": "string",
            "status": "ok",
            "tools": [
              {
                "description": "string",
                "name": "string"
              }
            ]
          }
        ]
      },
      "created_at": "2019-08-24T14:15:22Z",
      "diff_status": {
        "additions": 0,
        "approved": true,
        "author_avatar_url": "string",
        "author_login": "string",
        "base_branch": "string",
        "changed_files": 0,
        "changes_requested": true,
        "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
        "commits": 0,
        "deletions": 0,
        "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",
        "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

{
  "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

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

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.ChatDiffContents

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

Interrupt chat

Code samples

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

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

Parameters

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

Example responses

{
  "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  "archived": true,
  "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb",
  "children": [
    {
      "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
      "archived": true,
      "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb",
      "children": [],
      "client_type": "ui",
      "context": {
        "dirty": true,
        "dirty_since": "2019-08-24T14:15:22Z",
        "error": "string",
        "resources": [
          {
            "error": "string",
            "kind": "instruction_file",
            "size_bytes": 0,
            "skill_description": "string",
            "skill_name": "string",
            "source": "string",
            "status": "ok",
            "tools": [
              {
                "description": "string",
                "name": "string"
              }
            ]
          }
        ]
      },
      "created_at": "2019-08-24T14:15:22Z",
      "diff_status": {
        "additions": 0,
        "approved": true,
        "author_avatar_url": "string",
        "author_login": "string",
        "base_branch": "string",
        "changed_files": 0,
        "changes_requested": true,
        "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
        "commits": 0,
        "deletions": 0,
        "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",
        "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

{
  "has_more": true,
  "messages": [
    {
      "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
      "content": [
        {
          "args": [
            0
          ],
          "args_delta": "string",
          "completed_at": "2019-08-24T14:15:22Z",
          "content": "string",
          "context_file_agent_id": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
          "context_file_content": "string",
          "context_file_directory": "string",
          "context_file_os": "string",
          "context_file_path": "string",
          "context_file_skill_meta_file": "string",
          "context_file_truncated": true,
          "created_at": "2019-08-24T14:15:22Z",
          "data": [
            0
          ],
          "end_line": 0,
          "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
          "file_name": "string",
          "hook_rewritten": true,
          "is_error": true,
          "is_media": true,
          "mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
          "media_type": "string",
          "name": "string",
          "narration": true,
          "parsed_commands": [
            [
              "string"
            ]
          ],
          "provider_executed": true,
          "provider_metadata": [
            0
          ],
          "reasoning_delta": "string",
          "result": [
            0
          ],
          "result_delta": "string",
          "result_reset": true,
          "skill_description": "string",
          "skill_dir": "string",
          "skill_name": "string",
          "source_id": "string",
          "start_line": 0,
          "text": "string",
          "title": "string",
          "tool_call_id": "string",
          "tool_name": "string",
          "type": "text",
          "url": "string",
          "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": [
    {
      "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
      "content": [
        {
          "args": [
            0
          ],
          "args_delta": "string",
          "completed_at": "2019-08-24T14:15:22Z",
          "content": "string",
          "context_file_agent_id": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
          "context_file_content": "string",
          "context_file_directory": "string",
          "context_file_os": "string",
          "context_file_path": "string",
          "context_file_skill_meta_file": "string",
          "context_file_truncated": true,
          "created_at": "2019-08-24T14:15:22Z",
          "data": [
            0
          ],
          "end_line": 0,
          "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
          "file_name": "string",
          "hook_rewritten": true,
          "is_error": true,
          "is_media": true,
          "mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
          "media_type": "string",
          "name": "string",
          "narration": true,
          "parsed_commands": [
            [
              "string"
            ]
          ],
          "provider_executed": true,
          "provider_metadata": [
            0
          ],
          "reasoning_delta": "string",
          "result": [
            0
          ],
          "result_delta": "string",
          "result_reset": true,
          "skill_description": "string",
          "skill_dir": "string",
          "skill_name": "string",
          "source_id": "string",
          "start_line": 0,
          "text": "string",
          "title": "string",
          "tool_call_id": "string",
          "tool_name": "string",
          "type": "text",
          "url": "string",
          "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",
      "id": 0,
      "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205"
    }
  ],
  "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

{
  "busy_behavior": "queue",
  "content": [
    {
      "content": "string",
      "end_line": 0,
      "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
      "file_name": "string",
      "start_line": 0,
      "text": "string",
      "type": "text",
      "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

{
  "message": {
    "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
    "content": [
      {
        "args": [
          0
        ],
        "args_delta": "string",
        "completed_at": "2019-08-24T14:15:22Z",
        "content": "string",
        "context_file_agent_id": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
        "context_file_content": "string",
        "context_file_directory": "string",
        "context_file_os": "string",
        "context_file_path": "string",
        "context_file_skill_meta_file": "string",
        "context_file_truncated": true,
        "created_at": "2019-08-24T14:15:22Z",
        "data": [
          0
        ],
        "end_line": 0,
        "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
        "file_name": "string",
        "hook_rewritten": true,
        "is_error": true,
        "is_media": true,
        "mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
        "media_type": "string",
        "name": "string",
        "narration": true,
        "parsed_commands": [
          [
            "string"
          ]
        ],
        "provider_executed": true,
        "provider_metadata": [
          0
        ],
        "reasoning_delta": "string",
        "result": [
          0
        ],
        "result_delta": "string",
        "result_reset": true,
        "skill_description": "string",
        "skill_dir": "string",
        "skill_name": "string",
        "source_id": "string",
        "start_line": 0,
        "text": "string",
        "title": "string",
        "tool_call_id": "string",
        "tool_name": "string",
        "type": "text",
        "url": "string",
        "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": [
            0
          ],
          "args_delta": "string",
          "completed_at": "2019-08-24T14:15:22Z",
          "content": "string",
          "context_file_agent_id": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
          "context_file_content": "string",
          "context_file_directory": "string",
          "context_file_os": "string",
          "context_file_path": "string",
          "context_file_skill_meta_file": "string",
          "context_file_truncated": true,
          "created_at": "2019-08-24T14:15:22Z",
          "data": [
            0
          ],
          "end_line": 0,
          "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
          "file_name": "string",
          "hook_rewritten": true,
          "is_error": true,
          "is_media": true,
          "mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
          "media_type": "string",
          "name": "string",
          "narration": true,
          "parsed_commands": [
            [
              "string"
            ]
          ],
          "provider_executed": true,
          "provider_metadata": [
            0
          ],
          "reasoning_delta": "string",
          "result": [
            0
          ],
          "result_delta": "string",
          "result_reset": true,
          "skill_description": "string",
          "skill_dir": "string",
          "skill_name": "string",
          "source_id": "string",
          "start_line": 0,
          "text": "string",
          "title": "string",
          "tool_call_id": "string",
          "tool_name": "string",
          "type": "text",
          "url": "string",
          "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": {
    "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
    "content": [
      {
        "args": [
          0
        ],
        "args_delta": "string",
        "completed_at": "2019-08-24T14:15:22Z",
        "content": "string",
        "context_file_agent_id": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
        "context_file_content": "string",
        "context_file_directory": "string",
        "context_file_os": "string",
        "context_file_path": "string",
        "context_file_skill_meta_file": "string",
        "context_file_truncated": true,
        "created_at": "2019-08-24T14:15:22Z",
        "data": [
          0
        ],
        "end_line": 0,
        "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
        "file_name": "string",
        "hook_rewritten": true,
        "is_error": true,
        "is_media": true,
        "mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
        "media_type": "string",
        "name": "string",
        "narration": true,
        "parsed_commands": [
          [
            "string"
          ]
        ],
        "provider_executed": true,
        "provider_metadata": [
          0
        ],
        "reasoning_delta": "string",
        "result": [
          0
        ],
        "result_delta": "string",
        "result_reset": true,
        "skill_description": "string",
        "skill_dir": "string",
        "skill_name": "string",
        "source_id": "string",
        "start_line": 0,
        "text": "string",
        "title": "string",
        "tool_call_id": "string",
        "tool_name": "string",
        "type": "text",
        "url": "string",
        "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",
    "id": 0,
    "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205"
  },
  "warnings": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.CreateChatMessageResponse

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

Edit chat message

Code samples

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

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

{
  "content": [
    {
      "content": "string",
      "end_line": 0,
      "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
      "file_name": "string",
      "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

{
  "deleted_message_ids": [
    0
  ],
  "message": {
    "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
    "content": [
      {
        "args": [
          0
        ],
        "args_delta": "string",
        "completed_at": "2019-08-24T14:15:22Z",
        "content": "string",
        "context_file_agent_id": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
        "context_file_content": "string",
        "context_file_directory": "string",
        "context_file_os": "string",
        "context_file_path": "string",
        "context_file_skill_meta_file": "string",
        "context_file_truncated": true,
        "created_at": "2019-08-24T14:15:22Z",
        "data": [
          0
        ],
        "end_line": 0,
        "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
        "file_name": "string",
        "hook_rewritten": true,
        "is_error": true,
        "is_media": true,
        "mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
        "media_type": "string",
        "name": "string",
        "narration": true,
        "parsed_commands": [
          [
            "string"
          ]
        ],
        "provider_executed": true,
        "provider_metadata": [
          0
        ],
        "reasoning_delta": "string",
        "result": [
          0
        ],
        "result_delta": "string",
        "result_reset": true,
        "skill_description": "string",
        "skill_dir": "string",
        "skill_name": "string",
        "source_id": "string",
        "start_line": 0,
        "text": "string",
        "title": "string",
        "tool_call_id": "string",
        "tool_name": "string",
        "type": "text",
        "url": "string",
        "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": [
            0
          ],
          "args_delta": "string",
          "completed_at": "2019-08-24T14:15:22Z",
          "content": "string",
          "context_file_agent_id": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
          "context_file_content": "string",
          "context_file_directory": "string",
          "context_file_os": "string",
          "context_file_path": "string",
          "context_file_skill_meta_file": "string",
          "context_file_truncated": true,
          "created_at": "2019-08-24T14:15:22Z",
          "data": [
            0
          ],
          "end_line": 0,
          "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
          "file_name": "string",
          "hook_rewritten": true,
          "is_error": true,
          "is_media": true,
          "mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
          "media_type": "string",
          "name": "string",
          "narration": true,
          "parsed_commands": [
            [
              "string"
            ]
          ],
          "provider_executed": true,
          "provider_metadata": [
            0
          ],
          "reasoning_delta": "string",
          "result": [
            0
          ],
          "result_delta": "string",
          "result_reset": true,
          "skill_description": "string",
          "skill_dir": "string",
          "skill_name": "string",
          "source_id": "string",
          "start_line": 0,
          "text": "string",
          "title": "string",
          "tool_call_id": "string",
          "tool_name": "string",
          "type": "text",
          "url": "string",
          "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

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

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.ChatPromptsResponse

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

Delete chat queued message

Code samples

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

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

Parameters

Name	In	Type	Required	Description
`chat`	path	string(uuid)	true	Chat ID
`queuedMessage`	path	integer	true	Queued message ID

Responses

Status	Meaning	Description	Schema
204	No Content	No Content

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

Promote chat queued message

Code samples

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

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

Parameters

Name	In	Type	Required	Description
`chat`	path	string(uuid)	true	Chat ID
`queuedMessage`	path	integer	true	Queued message ID

Example responses

{
  "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

{
  "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  "archived": true,
  "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb",
  "children": [
    {
      "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
      "archived": true,
      "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb",
      "children": [],
      "client_type": "ui",
      "context": {
        "dirty": true,
        "dirty_since": "2019-08-24T14:15:22Z",
        "error": "string",
        "resources": [
          {
            "error": "string",
            "kind": "instruction_file",
            "size_bytes": 0,
            "skill_description": "string",
            "skill_name": "string",
            "source": "string",
            "status": "ok",
            "tools": [
              {
                "description": "string",
                "name": "string"
              }
            ]
          }
        ]
      },
      "created_at": "2019-08-24T14:15:22Z",
      "diff_status": {
        "additions": 0,
        "approved": true,
        "author_avatar_url": "string",
        "author_login": "string",
        "base_branch": "string",
        "changed_files": 0,
        "changes_requested": true,
        "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
        "commits": 0,
        "deletions": 0,
        "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",
        "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

Parameters

Name	In	Type	Required	Description
`chat`	path	string(uuid)	true	Chat ID
`after_id`	query	integer	false	Skip snapshot messages with id at or before this cursor

Example responses

[
  {
    "action_required": {
      "tool_calls": [
        {
          "args": "string",
          "tool_call_id": "string",
          "tool_name": "string"
        }
      ]
    },
    "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
    "error": {
      "detail": "string",
      "kind": "generic",
      "message": "string",
      "provider": "string",
      "retryable": true,
      "status_code": 0
    },
    "message": {
      "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
      "content": [
        {
          "args": [
            0
          ],
          "args_delta": "string",
          "completed_at": "2019-08-24T14:15:22Z",
          "content": "string",
          "context_file_agent_id": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
          "context_file_content": "string",
          "context_file_directory": "string",
          "context_file_os": "string",
          "context_file_path": "string",
          "context_file_skill_meta_file": "string",
          "context_file_truncated": true,
          "created_at": "2019-08-24T14:15:22Z",
          "data": [
            0
          ],
          "end_line": 0,
          "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
          "file_name": "string",
          "hook_rewritten": true,
          "is_error": true,
          "is_media": true,
          "mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
          "media_type": "string",
          "name": "string",
          "narration": true,
          "parsed_commands": [
            [
              "string"
            ]
          ],
          "provider_executed": true,
          "provider_metadata": [
            0
          ],
          "reasoning_delta": "string",
          "result": [
            0
          ],
          "result_delta": "string",
          "result_reset": true,
          "skill_description": "string",
          "skill_dir": "string",
          "skill_name": "string",
          "source_id": "string",
          "start_line": 0,
          "text": "string",
          "title": "string",
          "tool_call_id": "string",
          "tool_name": "string",
          "type": "text",
          "url": "string",
          "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": [
          0
        ],
        "args_delta": "string",
        "completed_at": "2019-08-24T14:15:22Z",
        "content": "string",
        "context_file_agent_id": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
        "context_file_content": "string",
        "context_file_directory": "string",
        "context_file_os": "string",
        "context_file_path": "string",
        "context_file_skill_meta_file": "string",
        "context_file_truncated": true,
        "created_at": "2019-08-24T14:15:22Z",
        "data": [
          0
        ],
        "end_line": 0,
        "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
        "file_name": "string",
        "hook_rewritten": true,
        "is_error": true,
        "is_media": true,
        "mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
        "media_type": "string",
        "name": "string",
        "narration": true,
        "parsed_commands": [
          [
            "string"
          ]
        ],
        "provider_executed": true,
        "provider_metadata": [
          0
        ],
        "reasoning_delta": "string",
        "result": [
          0
        ],
        "result_delta": "string",
        "result_reset": true,
        "skill_description": "string",
        "skill_dir": "string",
        "skill_name": "string",
        "source_id": "string",
        "start_line": 0,
        "text": "string",
        "title": "string",
        "tool_call_id": "string",
        "tool_name": "string",
        "type": "text",
        "url": "string",
        "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": [
      {
        "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86",
        "content": [
          {
            "args": [
              0
            ],
            "args_delta": "string",
            "completed_at": "2019-08-24T14:15:22Z",
            "content": "string",
            "context_file_agent_id": "2e577c68-2ec9-4c84-a77a-5b3e1d7eae09",
            "context_file_content": "string",
            "context_file_directory": "string",
            "context_file_os": "string",
            "context_file_path": "string",
            "context_file_skill_meta_file": "string",
            "context_file_truncated": true,
            "created_at": "2019-08-24T14:15:22Z",
            "data": [
              0
            ],
            "end_line": 0,
            "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
            "file_name": "string",
            "hook_rewritten": true,
            "is_error": true,
            "is_media": true,
            "mcp_server_config_id": "a9f436ed-69e7-459c-8308-a67ff5387e3e",
            "media_type": "string",
            "name": "string",
            "narration": true,
            "parsed_commands": [
              [
                "string"
              ]
            ],
            "provider_executed": true,
            "provider_metadata": [
              0
            ],
            "reasoning_delta": "string",
            "result": [
              0
            ],
            "result_delta": "string",
            "result_reset": true,
            "skill_description": "string",
            "skill_dir": "string",
            "skill_name": "string",
            "source_id": "string",
            "start_line": 0,
            "text": "string",
            "title": "string",
            "tool_call_id": "string",
            "tool_name": "string",
            "type": "text",
            "url": "string",
            "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",
        "id": 0,
        "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205"
      }
    ],
    "retry": {
      "attempt": 0,
      "delay_ms": 0,
      "error": "string",
      "kind": "generic",
      "provider": "string",
      "retrying_at": "2019-08-24T14:15:22Z",
      "status_code": 0
    },
    "status": {
      "status": "waiting"
    },
    "type": "message_part"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.ChatStreamEvent

Response Schema

Status Code 200

Name	Type	Required	Description
`[array item]`	array	false
`» action_required`	codersdk.ChatStreamActionRequired	false
`»» tool_calls`	array	false
`»»» args`	string	false
`»»» tool_call_id`	string	false
`»»» tool_name`	string	false
`» chat_id`	string(uuid)	false
`» error`	codersdk.ChatError	false
`»» detail`	string	false	Detail is optional provider-specific context shown alongside the normalized error message when available.
`»» kind`	codersdk.ChatErrorKind	false	Kind classifies the error for consistent client rendering.
`»» message`	string	false	Message is the normalized, user-facing error message.
`»» provider`	string	false	Provider identifies the upstream model provider when known.
`»» retryable`	boolean	false	Retryable reports whether the underlying error is transient.
`»» status_code`	integer	false	Status code is the best-effort upstream HTTP status code.
`» message`	codersdk.ChatMessage	false
`»» chat_id`	string(uuid)	false
`»» content`	array	false
`»»» args`	array	false
`»»» args_delta`	string	false
`»»» completed_at`	string(date-time)	false	Completed at is the time a reasoning part finished streaming, so reasoning duration can be computed as completed_at minus created_at. For interrupted reasoning, this is the interruption time. Absent when reasoning timestamp data was not recorded (e.g. messages persisted before this feature was added).
`»»» content`	string	false	The code content from the diff that was commented on.
`»»» context_file_agent_id`	string(uuid)	false	Context file agent ID is the workspace agent that provided this context file. Used to detect when the agent changes (e.g. workspace rebuilt) so instruction files can be re-persisted with fresh content.
`»»» context_file_content`	string	false	Context file content holds the file content sent to the LLM. Internal only: stripped before API responses to keep payloads small. The backend reads it when building the prompt via partsToMessageParts.
`»»» context_file_directory`	string	false	Context file directory is the working directory of the workspace agent. Internal only: same purpose as ContextFileOS.
`»»» context_file_os`	string	false	Context file os is the operating system of the workspace agent. Internal only: used during prompt expansion so the LLM knows the OS even on turns where InsertSystem is not called.
`»»» context_file_path`	string	false	Context file path is the absolute path of a file loaded into the LLM context (e.g. an AGENTS.md instruction file).
`»»» context_file_skill_meta_file`	string	false	Context file skill meta file is the basename of the skill meta file (e.g. "SKILL.md") at the time of persistence. Internal only: restored on subsequent turns so the read_skill tool uses the correct filename even when the agent configured a non-default value.
`»»» context_file_truncated`	boolean	false	Context file truncated indicates the file exceeded the 64KiB instruction file limit and was truncated.
`»»» created_at`	string(date-time)	false	Created at is the timestamp this part carries. The semantics depend on the part type: for tool-call and tool-result parts it is the time the call was emitted or the result was produced (tool duration is the result's created_at minus the call's created_at); for reasoning parts it is the time reasoning started streaming.
`»»» data`	array	false
`»»» end_line`	integer	false
`»»» file_id`	string(uuid)	false
`»»» file_name`	string	false
`»»» hook_rewritten`	boolean	false	Hook rewritten indicates that a lifecycle hook replaced model-proposed tool input.
`»»» is_error`	boolean	false
`»»» is_media`	boolean	false
`»»» mcp_server_config_id`	string(uuid)	false
`»»» media_type`	string	false
`»»» name`	string	false
`»»» 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).
`»»» provider_metadata`	array	false	Provider metadata holds provider-specific response metadata (e.g. Anthropic cache control hints) as raw JSON. Internal only: stripped by db2sdk before API responses.
`»»» reasoning_delta`	string	false
`»»» result`	array	false
`»»» result_delta`	string	false
`»»» result_reset`	boolean	false
`»»» skill_description`	string	false	Skill description is the short description from the skill's SKILL.md frontmatter.
`»»» skill_dir`	string	false	Skill dir is the absolute path to the skill directory inside the workspace filesystem. Internal only: used by read_skill/read_skill_file tools to locate skill files.
`»»» skill_name`	string	false	Skill name is the kebab-case name of a discovered skill from the workspace's .agents/skills/ directory.
`»»» source_id`	string	false
`»»» start_line`	integer	false
`»»» text`	string	false
`»»» title`	string	false
`»»» tool_call_id`	string	false
`»»» tool_name`	string	false
`»»» type`	codersdk.ChatMessagePartType	false
`»»» url`	string	false
`»»» 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
`»» chat_id`	string(uuid)	false
`»» content`	array	false
`»» created_at`	string(date-time)	false
`»» id`	integer	false
`»» model_config_id`	string(uuid)	false
`» retry`	codersdk.ChatStreamRetry	false
`»» attempt`	integer	false	Attempt is the 1-indexed retry attempt number.
`»» delay_ms`	integer	false	Delay ms is the backoff delay in milliseconds before the retry.
`»» error`	string	false	Error is the normalized error message from the failed attempt.
`»» kind`	codersdk.ChatErrorKind	false	Kind classifies the retry reason for consistent client rendering.
`»» provider`	string	false	Provider identifies the upstream model provider when known.
`»» retrying_at`	string(date-time)	false	Retrying at is the timestamp when the retry will be attempted.
`»» status_code`	integer	false	Status code is the best-effort upstream HTTP status code.
`» status`	codersdk.ChatStreamStatus	false
`»» status`	codersdk.ChatStatus	false
`» type`	codersdk.ChatStreamEventType	false

Enumerated Values

Property	Value(s)
`kind`	`auth`, `config`, `content_filter`, `generic`, `hook_denied`, `hook_dispatch_failed`, `missing_key`, `overloaded`, `provider_disabled`, `rate_limit`, `stream_silence_timeout`, `timeout`, `usage_limit`
`type`	`action_required`, `context-file`, `error`, `file`, `file-reference`, `history_reset`, `hook-context`, `hook-notice`, `message`, `message_part`, `preview_reset`, `queue_update`, `reasoning`, `retry`, `skill`, `source`, `status`, `text`, `tool-call`, `tool-result`, `workspace-file-reference`
`role`	`assistant`, `system`, `tool`, `user`
`status`	`error`, `interrupting`, `requires_action`, `running`, `waiting`

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

Watch chat workspace git state via WebSockets

Code samples

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

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

Parameters

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

Example responses

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

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.WorkspaceAgentGitServerMessage

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

Propose chat title

Code samples

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

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

Parameters

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

Example responses

{
  "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

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

Parameters

Name	In	Type	Required	Description
`chat`	path	string(uuid)	true	Chat ID
`body`	body	codersdk.SubmitToolResultsRequest	true	Request body

Responses

Status	Meaning	Description	Schema
204	No Content	No Content

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

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

{
  "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

{
  "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

{
  "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

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

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.OrganizationChatModelsResponse

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

Create an AI model in an organization

Code samples

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

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

{
  "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

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

Responses

Status	Meaning	Description	Schema
201	Created	Created	codersdk.ChatModel

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

List user AI provider key configurations

Code samples

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

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

Parameters

Name	In	Type	Required	Description
`user`	path	string	true	User ID, username, or me

Example responses

[
  {
    "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
`[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}

{
  "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

{
  "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.

274 KiB Generated Raw Blame History

Connect to chat workspace desktop via WebSockets

Code samples

Parameters

Responses

List chats

Code samples

Parameters

Example responses

Responses

Response Schema

Enumerated Values

Create chat

Code samples

Parameters

Example responses

Responses

List chats by workspace

Code samples

Parameters

Example responses

Responses

Get chat auto archive days

Code samples

Example responses

Responses

Update chat auto archive days

Code samples

Parameters

Responses

Get chat debug logging setting

Code samples

Example responses

Responses

Update chat debug logging setting

Code samples

Parameters

Responses

Get chat debug retention days

Code samples

Example responses

Responses

Update chat debug retention days

Code samples

Parameters

Responses

Get chat personal model override settings

Code samples

Example responses

Responses

Update chat personal model override settings

Code samples

Parameters

Responses

Get chat plan mode instructions

Code samples

Example responses

Responses

Update chat plan mode instructions

Code samples

Parameters

Responses

Get chat system prompt

Code samples

Example responses

Responses

Update chat system prompt

Code samples

Parameters

Responses

Get user chat debug logging setting

Code samples

Example responses

Responses

Update user chat debug logging setting

Code samples

Parameters

Responses

Get user chat custom prompt

Code samples

274 KiB

Generated

Raw Blame History