Migrate from the Tasks API to the Chats API
Migrate your integrations from the removed Coder Tasks API to the Coder Agents Chats API.
On this page
Warning
Coder Tasks was deprecated in Coder v2.34 and has been removed, including the Tasks API (/api/v2/tasks).
To read about Coder Tasks, use a previous version of the Coder documentation, from a release before v2.36.
The Tasks API (/api/v2/tasks) and the Chats API (/api/v2/chats) serve similar goals (programmatic access to AI-powered coding agents) but they differ significantly in architecture, capabilities, and usage patterns.
This guide walks you through updating your integrations from the Tasks API to the Chats API.
When to migrate
Migrate now. Coder Tasks has been removed, so requests to the Tasks API fail.
If your integrations still call the Tasks API, migrate to the Chats API and Coder Agents. Coder Agents runs the agent loop in the Coder control plane rather than inside the workspace, and is the supported path going forward.
The two systems are not interchangeable. Tasks and Chats are separate resources with separate APIs, so plan to update your integrations rather than expecting a drop-in replacement.
Key architectural differences
Before mapping individual endpoints, understand the structural changes:
| Aspect | Tasks API | Chats API |
|---|---|---|
| Agent execution | Agent runs inside the workspace (via AgentAPI) | Agent loop runs in the control plane |
| Large language model (LLM) credentials | Injected into workspace environment | Stored in control plane only; never enters the workspace |
| Workspace provisioning | You specify a template_version_id at creation | The agent auto-selects a template and provisions on demand |
| Template requirements | Requires coder_ai_task resource, coder_task data source, and an agent module | Any template with a clear description works |
| Chat state | Stored in the workspace (AgentAPI state file) | Persisted in the Coder database |
| Conversation model | Single prompt with optional follow-up input | Multi-turn chat with message history, queuing, and editing |
| Real-time updates | HTTP polling (GET .../logs) | WebSocket streaming (GET .../stream) |
| Sub-agents | Not supported | Built-in sub-agent delegation |
Endpoint mapping
The table below maps each Tasks API endpoint to its Chats API equivalent.
| Operation | Tasks API | Chats API |
|---|---|---|
| List | GET /api/v2/tasks | GET /api/v2/chats |
| Create | POST /api/v2/tasks/{user} | POST /api/v2/chats |
| Get by ID | GET /api/v2/tasks/{user}/{task} | GET /api/v2/chats/{chat} |
| Delete | DELETE /api/v2/tasks/{user}/{task} | PATCH /api/v2/chats/{chat} with {"archived": true} |
| Send follow-up | POST /api/v2/tasks/{user}/{task}/send | POST /api/v2/chats/{chat}/messages |
| Update input | PATCH /api/v2/tasks/{user}/{task}/input | PATCH /api/v2/chats/{chat}/messages/{message} |
| Get logs / stream | GET /api/v2/tasks/{user}/{task}/logs | GET /api/v2/chats/{chat}/stream (WebSocket) |
| Pause | POST /api/v2/tasks/{user}/{task}/pause | POST /api/v2/chats/{chat}/interrupt |
| Resume | POST /api/v2/tasks/{user}/{task}/resume | POST /api/v2/chats/{chat}/messages (send a new message) |
| Watch all | n/a | GET /api/v2/chats/watch (WebSocket) |
| Get messages | n/a | GET /api/v2/chats/{chat}/messages |
| List models | n/a | GET /api/v2/organizations/{organization}/chats/models |
| Upload file | n/a | POST /api/v2/chats/files |
Migration steps
Configure an LLM provider
With Tasks, LLM credentials are injected into the workspace as environment variables (for example, ANTHROPIC_API_KEY).
With Coder Agents, credentials are configured once in the control plane:
- Navigate to Admin settings > AI and select Providers.
- Add or update a provider with its credentials and upstream endpoint, then save it.
- Navigate to Admin settings > AI > Models.
- Select the correct organization.
- Add at least one model, and set it as the default.
You no longer pass API keys in template variables or workspace environment. See Getting started with Coder Agents for more information.
Update task creation calls
Tasks API. You specify the user, template version, and a prompt string:
# Tasks API: create a task
curl -X POST https://coder.example.com/api/v2/tasks/me \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"template_version_id": "<template-version-uuid>",
"input": "Fix the failing tests in the auth service"
}'Chats API. You send structured content parts. No template or user path segment is required:
# Chats API: create a chat
curl -X POST https://coder.example.com/api/v2/chats \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"organization_id": "<your-org-id>",
"content": [
{"type": "text", "text": "Fix the failing tests in the auth service"}
]
}'Key differences:
- The
{user}path parameter is removed. The authenticated user is inferred from the session token. organization_idis required in the request body. The caller must be a member of that organization.- The prompt is now an array of
ChatInputPartobjects (supportingtext,file, andfile-referencetypes) instead of a plain string. template_version_idandtemplate_version_preset_idare removed. The agent selects a template automatically based on the prompt and available template descriptions. To pin to a specific workspace, passworkspace_idinstead.- Optionally pass
model_config_idto override the default model, ormcp_server_idsto attach Model Context Protocol (MCP) servers. - Optionally pass
titleto set the chat's title. A title you set is kept. Automatic title generation runs only whentitleis omitted.
Update follow-up message calls
Tasks API. Follow-ups use the send endpoint with a plain string:
# Tasks API: send input
curl -X POST https://coder.example.com/api/v2/tasks/me/my-task/send \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"input": "Now also update the integration tests"}'Chats API. Follow-ups use the messages endpoint with content parts:
# Chats API: send a message
curl -X POST \
https://coder.example.com/api/v2/chats/$CHAT_ID/messages \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": [
{"type": "text", "text": "Now also update the integration tests"}
]
}'If the agent is busy, the busy_behavior field controls when the message reaches the agent:
steer(default): before the agent's next model call in the current turn.queue: after the current turn ends.
Call POST /api/v2/chats/{chat}/interrupt only to stop the turn, not to send a message.
The response includes a queued field that shows whether the message was delivered immediately or held for later delivery.
Switch from log polling to WebSocket streaming
Tasks API. You poll for logs:
# Tasks API: get logs
curl https://coder.example.com/api/v2/tasks/me/my-task/logs \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN"Chats API. You request the newest messages page, then open a one-way WebSocket connection that sends each later change:
GET https://coder.example.com/api/v2/chats/{chat}/messages
GET wss://coder.example.com/api/v2/chats/{chat}/stream?snapshot_version={snapshot_version}Each WebSocket message is a JSON array of events.
Each event has a type field:
| Event type | Description |
|---|---|
message_part | A chunk of the agent's response (text, tool call, etc.) |
preview_reset | Remove the message_part content that you received before this event |
message | A message was created, so add the message or replace your message that has the same ID |
history_reset | An edit deleted messages, so delete your messages that have an ID of history_reset.from_message_id or higher |
status | The chat status changed (e.g., running → waiting) |
error | An error occurred during processing |
retry | The control plane is retrying a failed LLM call |
queue_update | The queued message list changed (the event includes the whole list) |
action_required | The agent called a tool you provided, so run the tool and send the result with POST /api/v2/chats/{chat}/tool-results |
The server increases a chat's snapshot_version each time it changes the chat's messages, queue, or status.
To keep your client in sync with the chat:
- Request the newest messages page with
GET /api/v2/chats/{chat}/messages, withoutbefore_idorafter_id. - Store the
snapshot_version,messages, andqueued_messagesfrom the response. - Open the stream with
snapshot_versionset to the stored value. - Apply each event as the event table describes.
- When an event includes a
snapshot_versionthat is higher than the stored value, store the new value. - When the connection closes, fails to open, or sends a WebSocket message that isn't valid JSON:
- Remove the
message_partcontent. - Remove what your client shows for the
retryevent. - Wait before you reconnect. After each failed attempt, double the wait.
- Open the stream again with the stored
snapshot_version. - If the server returns
400 Bad Request, discard your client's state and start again from step 1.
- Remove the
On the next connection, the server again sends the message_part events of the response that the agent is writing.
If a retry is pending, the server also sends the retry event again.
Do not reconnect with after_id.
Suppose your client misses an edit, then sends a message and reconnects with that message's ID as after_id.
The stream doesn't send a history_reset event for that edit, so your client keeps the messages that the edit deleted.
It also doesn't send the messages written between the edit and your message.
The stream can send a change that your client already has.
Apply the change again: a message event replaces the message that has the same ID, and a queue_update event replaces the whole queue.
Each connection also sends action_required again while the chat's tool calls wait for results, so run the tool only once for each tool call ID.
If you applied a history_reset event after you sent a before_id request, discard that request's response.
Then send the before_id request again with the lowest message ID that you have.
Send actions, such as new messages, edits, and tool results, as HTTP requests. Do not apply their response bodies to your client's state, because the stream sends the result of each action.
For the order of events and the errors that the stream returns, refer to Stream chat events via WebSockets.
Update status handling
Task and chat statuses use different values.
The Chats API status set is defined in codersdk.ChatStatus:
| Tasks API status | Chats API status | Notes |
|---|---|---|
pending | running | Chats have no separate queued state; a chat that hasn't been picked up yet reports running. |
running | running | Agent is actively working. |
complete | waiting | Idle. Newly created, finished successfully, or interrupted. This is the default idle state. |
paused | n/a | The Tasks API pause stops the workspace. The Chats API has no workspace-stopping status; use interrupt plus separate workspace lifecycle. The Chats API paused status (last row) is unrelated: it marks a queued message under edit. |
failed | error | Agent encountered an error. |
| n/a | requires_action | Agent invoked a client-provided tool and is waiting for the result before continuing. |
| n/a | interrupting | An interrupt was requested and the agent is winding down the current run. |
| n/a | paused | A turn finished while the next queued message, or any queued steer message, was under edit; the agent does not run again until the edit ends. Queued messages wait behind it, and a steer message under edit also holds the steer messages ahead of it. A message sent with steer runs first, unless the message under edit is also a steer message, and the chat pauses again when that turn ends. Ending the edit via PATCH /chats/{chat}/queue/{queuedMessage} with {"editing": false} sends that message. |
The Chats API uses waiting as the default idle state (not complete).
A chat enters waiting when it is first created (before any message is queued) and again whenever a run finishes or is interrupted, so treat waiting as "the agent is not currently working" rather than only "the agent just finished."
Replace delete with archive
The Tasks API uses DELETE to remove a task.
The Chats API uses archiving:
- curl -X DELETE https://coder.example.com/api/v2/tasks/me/my-task \
- -H "Coder-Session-Token: $CODER_SESSION_TOKEN"
+ curl -X PATCH https://coder.example.com/api/v2/chats/$CHAT_ID \
+ -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"archived": true}'Archived chats can be restored by setting archived to false.
Replace pause/resume with interrupt and messaging
Tasks API. Pause and resume stop and start the workspace:
# Tasks API
curl -X POST \
https://coder.example.com/api/v2/tasks/me/my-task/pause \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN"
curl -X POST \
https://coder.example.com/api/v2/tasks/me/my-task/resume \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN"Chats API. Interrupt stops the current agent loop. Sending a new message resumes processing:
# Chats API: interrupt
curl -X POST \
https://coder.example.com/api/v2/chats/$CHAT_ID/interrupt \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN"
# Chats API: resume by sending a new message
curl -X POST \
https://coder.example.com/api/v2/chats/$CHAT_ID/messages \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": [
{"type": "text", "text": "Continue where you left off"}
]
}'In the Tasks API, pausing stops the workspace and frees compute. In the Chats API, interrupt stops the agent loop in the control plane. The workspace might remain running. The workspace lifecycle is managed independently.
Update GitHub Actions integrations
If you use the Create Task Action GitHub Action, replace it with the dedicated coder/create-agent-chat-action.
It handles the API call, the GitHub user lookup, and the optional issue comment, so most existing workflows can swap one uses: line and rename a few inputs.
We are actively shipping new features for create-agent-chat-action, so pin to a major version (for example @v0) and watch the releases for updates.
# .github/workflows/triage-bug.yaml
jobs:
coder-create-task:
runs-on: ubuntu-latest
if: github.event.label.name == 'coder'
steps:
- - name: Coder Create Task
- uses: coder/create-task-action@v0
- with:
- coder-url: ${{ secrets.CODER_URL }}
- coder-token: ${{ secrets.CODER_TOKEN }}
- coder-organization: "default"
- coder-template-name: "my-template"
- coder-task-name-prefix: "gh-task"
- coder-task-prompt: >-
- Use the gh CLI to read
- ${{ github.event.issue.html_url }},
- fix the issue, and create a PR.
- github-user-id: ${{ github.event.sender.id }}
- github-issue-url: ${{ github.event.issue.html_url }}
- github-token: ${{ github.token }}
- comment-on-issue: true
+ - name: Coder Create Agent Chat
+ uses: coder/create-agent-chat-action@v0
+ with:
+ coder-url: ${{ secrets.CODER_URL }}
+ coder-token: ${{ secrets.CODER_TOKEN }}
+ chat-prompt: >-
+ Use the gh CLI to read
+ ${{ github.event.issue.html_url }},
+ fix the issue, and create a PR.
+ github-url: ${{ github.event.issue.html_url }}
+ github-token: ${{ github.token }}
+ comment-on-issue: trueKey differences from the Tasks GitHub Action (GHA):
- No
coder-template-nameorcoder-task-name-prefix. The agent auto-provisions a workspace. Passworkspace-idif you want to pin to an existing workspace instead. - The prompt input is renamed from
coder-task-prompttochat-prompt. - LLM credentials are no longer passed through the template. They are configured in the Coder control plane.
- No user mapping: the Tasks GHA's
github-user-idinput has no equivalent in the action, which always creates chats as the user that owns thecoder-token. The Chats API accepts an optionalowner_idin the request body, but only when the caller can create API keys for that user.
See the action README for the full input and output reference, including the existing-chat-id input for sending follow-up messages on a previous chat.
Template recommendations
Note
This section contains recommendations that might evolve as Coder Agents matures. Review these against your deployment requirements.
With Coder Tasks, every task-capable template requires specific Terraform resources (coder_ai_task, coder_task, agent modules, and LLM API keys).
With Coder Agents, templates no longer need any of these.
The agent runs in the control plane and treats the workspace as plain compute.
However, we still recommend creating dedicated templates for agent workloads rather than reusing your standard developer templates unchanged. The reasons are different from Tasks, but the principle holds:
Why dedicated agent templates still matter
- Network boundaries. Agent workspaces inherit whatever network access the template allows. Because the agent does not need outbound access to LLM providers (that happens in the control plane), you can lock down agent templates to only reach the Coder control plane and your git provider. Standard developer templates typically allow broader access.
- No IDE tooling overhead. The agent connects via the workspace daemon's HTTP API, not through VS Code or JetBrains. Removing IDE extensions, desktop environments, and similar tooling from agent templates reduces image size and startup time.
- Scoped credentials. Agent workloads might warrant more restrictive credentials than interactive developer sessions. A dedicated template lets you provide a separate, narrower-scoped git token or service account without affecting your developers' workflow.
- Cost control. Agent workspaces can often use smaller compute resources than developer workspaces since they don't need to run IDEs, language servers, or other interactive tooling. A dedicated template lets you right-size the infrastructure.
What to include in agent templates
- Clear descriptions. The agent selects templates by reading names and descriptions. Include the target language, framework, repository, and type of work. For example: "Python backend services for the payments repo. Includes Poetry, Python 3.12, and PostgreSQL."
- Pre-installed dependencies.
Language runtimes, build tools,
git, and project-specific dependencies should be baked into the image. Time the agent spends installing tools is time not spent on the task. - Git configuration.
Make sure
gitis configured with credentials and author information so the agent can commit and push without additional setup. - Minimal parameters. Use sensible defaults so the agent can provision workspaces without guessing. Avoid required parameters with opaque identifiers.
What to remove from migrated task templates
If you are converting an existing task template for use with Coder Agents, you can safely remove the Tasks-specific Terraform resources. They are unused when the chat is driven by the Chats API:
terraform {
required_providers {
coder = {
source = "coder/coder"
- version = ">= 2.13"
+ version = ">= 2.13"
}
}
}
- data "coder_task" "me" {}
-
- resource "coder_ai_task" "task" {
- app_id = module.claude-code.task_app_id
- }
-
- module "claude-code" {
- source = "registry.coder.com/coder/claude-code/coder"
- version = "4.0.0"
- agent_id = coder_agent.main.id
- ai_prompt = data.coder_task.me.prompt
- claude_api_key = var.anthropic_api_key
- }
-
- variable "anthropic_api_key" {
- type = string
- description = "Anthropic API key"
- sensitive = true
- }
resource "coder_agent" "main" {
os = "linux"
arch = "amd64"
+ # No agent modules, no AgentAPI, no LLM keys needed.
+ # The Coder Agents control plane handles the agent loop.
}Important
Remove the Tasks-specific Terraform when you upgrade.
Tasks and Chats can no longer run side by side: Coder no longer injects CODER_TASK_ID or CODER_TASK_PROMPT, so builds of a template that keeps the coder_task data source can no longer populate it.
See Template Optimization for the full guide on writing discoverable descriptions, configuring network boundaries, scoping credentials, and pre-installing dependencies.
Pre-creating a workspace for deterministic results
Letting the agent pick a template and provision a workspace works well for exploratory chats. If your workflow requires deterministic results like:
- Automations
- Recurring processes
- Generally any case that needs a known reproducible environment
pre-create the workspace yourself and attach it when you create the chat.
The pattern is two API calls:
-
Create a workspace from a specific template via
POST /api/v2/users/{user}/workspaces. You control the template, the version, and any rich parameters. -
Create the chat with
workspace_idset to the new workspace.The agent runs against that workspace instead of selecting one heuristically.
# 1. Provision the workspace from the exact template you want.
WORKSPACE_ID=$(curl -s -X POST \
https://coder.example.com/api/v2/users/me/workspaces \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"template_id": "<your-agent-template-uuid>",
"name": "agent-run-${GITHUB_RUN_ID}"
}' | jq -r '.id')
# 2. Create the chat bound to that workspace.
curl -s -X POST https://coder.example.com/api/v2/chats \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"organization_id\": \"<your-org-id>\",
\"workspace_id\": \"$WORKSPACE_ID\",
\"content\": [
{\"type\": \"text\", \"text\": \"Fix the failing tests in the auth service\"}
]
}"This pattern is the closest analog to the Tasks API behavior of template_version_id plus coder-template-name: you decide which template runs, the agent decides what to do inside it.
The same approach works from the coder/create-agent-chat-action GHA, which exposes the same pin via its workspace-id input.
How to test your migration
After completing the migration steps above, walk through these checks to confirm the Chats API integration is working end-to-end.
Confirm LLM provider connectivity
List the available models in an organization to verify at least one provider is configured and reachable:
curl -s https://coder.example.com/api/v2/organizations/$CODER_ORGANIZATION/chats/models \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" | jq '.models[].display_name'If this returns an empty list or an error, revisit Step 1: Configure an LLM provider.
Create a chat and confirm the response
Create a simple chat that does not require a workspace.
Replace <your-org-id> with the ID of an organization you belong to.
To find the ID, run coder organizations list and copy the value in the id column.
curl -s -X POST https://coder.example.com/api/v2/chats \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"organization_id": "<your-org-id>",
"content": [{"type": "text", "text": "What is 2 + 2?"}]
}' | jq '{id, status, title}'You should receive a Chat object with status set to "running", since new chats begin processing immediately.
Save the id for subsequent steps.
Stream the response
Open a WebSocket connection to verify the agent processes the prompt and returns a response. Using websocat:
websocat -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
"wss://coder.example.com/api/v2/chats/$CHAT_ID/stream"websocat prints JSON arrays of events.
The arrays include message and status events.
While the agent writes its response, the arrays also include message_part events.
The chat should eventually reach "waiting" status, indicating the agent completed its response.
Send a follow-up message
Verify multi-turn conversation works:
curl -s -X POST \
"https://coder.example.com/api/v2/chats/$CHAT_ID/messages" \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": [{"type": "text", "text": "Now multiply that by 10"}]
}' | jq '{queued}'The response should include "queued": false (delivered immediately) or "queued": true (the agent was busy, so the message is delivered before the agent's next model call).
Test workspace provisioning
Create a workspace from your converted agent template through the standard Coder UI, then attach it to a new chat from the chat composer:
- In the Coder dashboard, create a workspace from the agent template you migrated.
- Open Agents and start a new chat.
- In the composer, use the workspace picker to attach the workspace you just created.
- Send a prompt that exercises the workspace, for example: "List the files in the root directory of this workspace."
The response stream should show the agent invoking workspace tools (such as execute) against the attached workspace.
After the chat finishes, verify the chat is bound to the workspace via the API:
curl -s "https://coder.example.com/api/v2/chats/$CHAT_ID" \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" | jq '{workspace_id, status}'A workspace_id matching the workspace you attached confirms the chat is driving that workspace end-to-end.
Auto-provisioning from the chat flow is also supported but is easier to verify once the manual-attach path is working.
Verify interrupt works
Start a long-running chat and interrupt it:
curl -s -X POST \
"https://coder.example.com/api/v2/chats/$CHAT_ID/interrupt" \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN"Then confirm the chat status returns to "waiting":
curl -s "https://coder.example.com/api/v2/chats/$CHAT_ID" \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" | jq '.status'Validate archive and restore
# Archive
curl -s -X PATCH \
"https://coder.example.com/api/v2/chats/$CHAT_ID" \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"archived": true}'
# Confirm it no longer appears in the default list
curl -s "https://coder.example.com/api/v2/chats" \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
| jq --arg id "$CHAT_ID" '[.[] | select(.id == $id)] | length'
# Should return 0
# Restore
curl -s -X PATCH \
"https://coder.example.com/api/v2/chats/$CHAT_ID" \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"archived": false}'Quick checklist
Use this list to confirm each part of your integration:
- At least one LLM model is configured in the organization and returned by
/organizations/{organization}/chats/models POST /chatscreates a chat and returns a validChatobject- WebSocket stream at
/chats/{chat}/streamdelivers events - Follow-up messages via
/chats/{chat}/messagesare accepted - Chat attached to a workspace from the converted template runs tools against that workspace
POST /chats/{chat}/interruptstops the agent and returns towaiting- Archive and restore via
PATCH /chats/{chat}works - (If applicable) GitHub Actions workflow creates chats successfully
Features available only in the Chats API
The Chats API includes capabilities that have no equivalent in the Tasks API:
| Feature | Description |
|---|---|
| WebSocket streaming | Real-time event stream via GET /chats/{chat}/stream instead of HTTP polling |
| Watch all chats | GET /chats/watch pushes events for all chats owned by the user |
| Message editing | PATCH /chats/{chat}/messages/{message} to edit a sent message and re-process |
| Message steering and queuing | Follow-up messages steer a busy agent's current turn by default, or queue until the turn ends |
| Queued message editing | PATCH /chats/{chat}/queue/{queuedMessage} to edit a queued message before the agent processes it |
| File uploads | Attach images via POST /chats/files and reference them in messages |
| Model selection | GET /organizations/{organization}/chats/models to discover models; override per-chat or per-message |
| MCP server attachment | Attach MCP servers to a chat for tool augmentation |
| Labels | Key-value metadata on chats for filtering (label query parameter) |
| Sub-agents | Agent can spawn child agents for parallel work |
| Diff/PR tracking | GET /chats/{chat}/diff returns change tracking and PR metadata |
| Title generation | POST /chats/{chat}/title/propose returns a suggested title |
| Pinning | Pin and reorder chats via the pin_order field |
| Automatic workspace provisioning | Created for workspace access or to obtain missing tools, skills, MCP integrations, or context |
Response schema changes
The Tasks API returns a Task object with workspace-centric fields.
The Chats API returns a Chat object with conversation-centric fields:
| Tasks API field | Chats API equivalent | Notes |
|---|---|---|
id | id | Both are universally unique identifiers (UUIDs) |
initial_prompt | First message in GET /chats/{chat}/messages | Prompt is a message, not a top-level field |
display_name | title | Auto-generated or set via PATCH |
status | status | Different enum values (see status table above) |
current_state | Latest status event from the stream | No equivalent top-level field |
workspace_id | workspace_id | Nullable in Chats. Can be null if no workspace was provisioned |
workspace_status | n/a | Manage workspace lifecycle separately |
template_id | n/a | Not exposed; the agent selects templates internally |
owner_id | owner_id | Same concept |
name | n/a | Chats use id for identification, not human-readable names |
CLI changes
The Tasks CLI (coder task) was removed, and Coder does not ship an interactive Coder Agents terminal user interface (TUI).
Use the web UI for interactive chat and direct API calls for automation.
The table below maps the removed commands to their Chats API equivalents.
| Removed Tasks CLI | Chats equivalent |
|---|---|
coder task create | Web UI or POST /chats |
coder task list | Web UI or GET /chats |
coder task logs | GET /chats/{chat}/stream (WebSocket) |
coder task pause | POST /chats/{chat}/interrupt |
coder task resume | Send a follow-up message to the chat |