From e7360da974d69a13b75c6ace26c7c79869e6e681 Mon Sep 17 00:00:00 2001 From: david-fraley <67079030+david-fraley@users.noreply.github.com> Date: Tue, 5 May 2026 14:52:54 -0400 Subject: [PATCH] docs: generate Chats API docs from swagger annotations (#24830) --- AGENTS.md | 3 - coderd/apidoc/docs.go | 1805 +++++++++++++++ coderd/apidoc/swagger.json | 1698 ++++++++++++++ coderd/exp_chats.go | 183 ++ codersdk/chats.go | 2 +- docs/ai-coder/agents/chats-api.md | 406 ---- docs/ai-coder/agents/getting-started.md | 6 +- docs/ai-coder/best-practices.md | 2 +- docs/manifest.json | 15 +- docs/reference/api/chats.md | 2732 +++++++++++++++++++++++ docs/reference/api/schemas.md | 2152 ++++++++++++++++++ scripts/apidocgen/postprocess/main.go | 13 + site/src/api/typesGenerated.ts | 2 +- 13 files changed, 8597 insertions(+), 422 deletions(-) delete mode 100644 docs/ai-coder/agents/chats-api.md diff --git a/AGENTS.md b/AGENTS.md index 0aa58f7c57..5542dded10 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -110,9 +110,6 @@ app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID) - For experimental or unstable API paths, skip public doc generation with `// @x-apidocgen {"skip": true}` after the `@Router` annotation. This keeps them out of the published API reference until they stabilize. -- Experimental chat endpoints in `coderd/exp_chats.go` omit swagger - annotations entirely. Do not add `@Summary`, `@Router`, or other - swagger comments to handlers in that file. ### Database Query Naming diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index db52e176e2..98c50b7120 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -12221,6 +12221,671 @@ const docTemplate = `{ ] } }, + "/experimental/chats": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "List chats", + "operationId": "list-chats", + "parameters": [ + { + "type": "string", + "description": "Search query", + "name": "q", + "in": "query" + }, + { + "type": "string", + "description": "Filter by label as key:value. Repeat for multiple (AND logic).", + "name": "label", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Chat" + } + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + }, + "post": { + "description": "Experimental: this endpoint is subject to change.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Create chat", + "operationId": "create-chat", + "parameters": [ + { + "description": "Create chat request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.CreateChatRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.Chat" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/files": { + "post": { + "description": "Experimental: this endpoint is subject to change.", + "consumes": [ + "image/png", + "image/jpeg", + "image/gif", + "image/webp", + "text/plain", + "text/markdown", + "text/csv", + "application/json", + "application/pdf" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Upload chat file", + "operationId": "upload-chat-file", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "query", + "required": true + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.UploadChatFileResponse" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/files/{file}": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "image/png", + "image/jpeg", + "image/gif", + "image/webp", + "text/plain", + "text/markdown", + "text/csv", + "application/json", + "application/pdf" + ], + "tags": [ + "Chats" + ], + "summary": "Get chat file", + "operationId": "get-chat-file", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "File ID", + "name": "file", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK" + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/models": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "List chat models", + "operationId": "list-chat-models", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.ChatModelsResponse" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/watch": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Watch chat events for a user via WebSockets", + "operationId": "watch-chat-events-for-a-user-via-websockets", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.ChatWatchEvent" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Get chat by ID", + "operationId": "get-chat-by-id", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Chat" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + }, + "patch": { + "description": "Experimental: this endpoint is subject to change.", + "consumes": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Update chat", + "operationId": "update-chat", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + }, + { + "description": "Update chat request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.UpdateChatRequest" + } + } + ], + "responses": { + "204": { + "description": "No Content" + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/diff": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Get chat diff contents", + "operationId": "get-chat-diff-contents", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.ChatDiffContents" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/interrupt": { + "post": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Interrupt chat", + "operationId": "interrupt-chat", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Chat" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/messages": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "List chat messages", + "operationId": "list-chat-messages", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "Return messages with id \u003c before_id", + "name": "before_id", + "in": "query" + }, + { + "type": "integer", + "description": "Return messages with id \u003e after_id", + "name": "after_id", + "in": "query" + }, + { + "type": "integer", + "description": "Page size, 1 to 200. Defaults to 50.", + "name": "limit", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.ChatMessagesResponse" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + }, + "post": { + "description": "Experimental: this endpoint is subject to change.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Send chat message", + "operationId": "send-chat-message", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + }, + { + "description": "Create chat message request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.CreateChatMessageRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.CreateChatMessageResponse" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/messages/{message}": { + "patch": { + "description": "Experimental: this endpoint is subject to change.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Edit chat message", + "operationId": "edit-chat-message", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "Message ID", + "name": "message", + "in": "path", + "required": true + }, + { + "description": "Edit chat message request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.EditChatMessageRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.EditChatMessageResponse" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/stream": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Stream chat events via WebSockets", + "operationId": "stream-chat-events-via-websockets", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.ChatStreamEvent" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/stream/desktop": { + "get": { + "description": "Raw binary WebSocket stream of the chat workspace desktop.\nExperimental: this endpoint is subject to change.", + "produces": [ + "application/octet-stream" + ], + "tags": [ + "Chats" + ], + "summary": "Connect to chat workspace desktop via WebSockets", + "operationId": "connect-to-chat-workspace-desktop-via-websockets", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "101": { + "description": "Switching Protocols" + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/stream/git": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Watch chat workspace git state via WebSockets", + "operationId": "watch-chat-workspace-git-state-via-websockets", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.WorkspaceAgentGitServerMessage" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/title/regenerate": { + "post": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "application/json" + ], + "tags": [ + "Chats" + ], + "summary": "Regenerate chat title", + "operationId": "regenerate-chat-title", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Chat" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, "/oauth2/authorize": { "get": { "tags": [ @@ -14767,6 +15432,144 @@ const docTemplate = `{ } } }, + "codersdk.Chat": { + "type": "object", + "properties": { + "agent_id": { + "type": "string", + "format": "uuid" + }, + "archived": { + "type": "boolean" + }, + "build_id": { + "type": "string", + "format": "uuid" + }, + "children": { + "description": "Children holds child (subagent) chats nested under this root\nchat. Always initialized to an empty slice so the JSON field\nis present as []. Child chats cannot create their own\nsubagents, so nesting depth is capped at 1 and this slice is\nalways empty for child chats.", + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Chat" + } + }, + "client_type": { + "$ref": "#/definitions/codersdk.ChatClientType" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "diff_status": { + "$ref": "#/definitions/codersdk.ChatDiffStatus" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatFileMetadata" + } + }, + "has_unread": { + "description": "HasUnread is true when assistant messages exist beyond\nthe owner's read cursor, which updates on stream\nconnect and disconnect.", + "type": "boolean" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "last_error": { + "$ref": "#/definitions/codersdk.ChatError" + }, + "last_injected_context": { + "description": "LastInjectedContext holds the most recently persisted\ninjected context parts (AGENTS.md files and skills). It\nis updated only when context changes, on first workspace\nattach or agent change.", + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatMessagePart" + } + }, + "last_model_config_id": { + "type": "string", + "format": "uuid" + }, + "mcp_server_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "organization_id": { + "type": "string", + "format": "uuid" + }, + "owner_id": { + "type": "string", + "format": "uuid" + }, + "parent_chat_id": { + "type": "string", + "format": "uuid" + }, + "pin_order": { + "type": "integer" + }, + "plan_mode": { + "$ref": "#/definitions/codersdk.ChatPlanMode" + }, + "root_chat_id": { + "type": "string", + "format": "uuid" + }, + "status": { + "$ref": "#/definitions/codersdk.ChatStatus" + }, + "title": { + "type": "string" + }, + "updated_at": { + "type": "string", + "format": "date-time" + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + }, + "workspace_id": { + "type": "string", + "format": "uuid" + } + } + }, + "codersdk.ChatBusyBehavior": { + "type": "string", + "enum": [ + "queue", + "interrupt" + ], + "x-enum-varnames": [ + "ChatBusyBehaviorQueue", + "ChatBusyBehaviorInterrupt" + ] + }, + "codersdk.ChatClientType": { + "type": "string", + "enum": [ + "ui", + "api" + ], + "x-enum-varnames": [ + "ChatClientTypeUI", + "ChatClientTypeAPI" + ] + }, "codersdk.ChatConfig": { "type": "object", "properties": { @@ -14778,6 +15581,566 @@ const docTemplate = `{ } } }, + "codersdk.ChatDiffContents": { + "type": "object", + "properties": { + "branch": { + "type": "string" + }, + "chat_id": { + "type": "string", + "format": "uuid" + }, + "diff": { + "type": "string" + }, + "provider": { + "type": "string" + }, + "pull_request_url": { + "type": "string" + }, + "remote_origin": { + "type": "string" + } + } + }, + "codersdk.ChatDiffStatus": { + "type": "object", + "properties": { + "additions": { + "type": "integer" + }, + "approved": { + "type": "boolean" + }, + "author_avatar_url": { + "type": "string" + }, + "author_login": { + "type": "string" + }, + "base_branch": { + "type": "string" + }, + "changed_files": { + "type": "integer" + }, + "changes_requested": { + "type": "boolean" + }, + "chat_id": { + "type": "string", + "format": "uuid" + }, + "commits": { + "type": "integer" + }, + "deletions": { + "type": "integer" + }, + "head_branch": { + "type": "string" + }, + "pr_number": { + "type": "integer" + }, + "pull_request_draft": { + "type": "boolean" + }, + "pull_request_state": { + "type": "string" + }, + "pull_request_title": { + "type": "string" + }, + "refreshed_at": { + "type": "string", + "format": "date-time" + }, + "reviewer_count": { + "type": "integer" + }, + "stale_at": { + "type": "string", + "format": "date-time" + }, + "url": { + "type": "string" + } + } + }, + "codersdk.ChatError": { + "type": "object", + "properties": { + "detail": { + "description": "Detail is optional provider-specific context shown alongside the\nnormalized error message when available.", + "type": "string" + }, + "kind": { + "description": "Kind classifies the error for consistent client rendering.", + "type": "string" + }, + "message": { + "description": "Message is the normalized, user-facing error message.", + "type": "string" + }, + "provider": { + "description": "Provider identifies the upstream model provider when known.", + "type": "string" + }, + "retryable": { + "description": "Retryable reports whether the underlying error is transient.", + "type": "boolean" + }, + "status_code": { + "description": "StatusCode is the best-effort upstream HTTP status code.", + "type": "integer" + } + } + }, + "codersdk.ChatFileMetadata": { + "type": "object", + "properties": { + "created_at": { + "type": "string", + "format": "date-time" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "mime_type": { + "type": "string" + }, + "name": { + "type": "string" + }, + "organization_id": { + "type": "string", + "format": "uuid" + }, + "owner_id": { + "type": "string", + "format": "uuid" + } + } + }, + "codersdk.ChatInputPart": { + "type": "object", + "properties": { + "content": { + "description": "The code content from the diff that was commented on.", + "type": "string" + }, + "end_line": { + "type": "integer" + }, + "file_id": { + "type": "string", + "format": "uuid" + }, + "file_name": { + "description": "The following fields are only set when Type is\nChatInputPartTypeFileReference.", + "type": "string" + }, + "start_line": { + "type": "integer" + }, + "text": { + "type": "string" + }, + "type": { + "$ref": "#/definitions/codersdk.ChatInputPartType" + } + } + }, + "codersdk.ChatInputPartType": { + "type": "string", + "enum": [ + "text", + "file", + "file-reference" + ], + "x-enum-varnames": [ + "ChatInputPartTypeText", + "ChatInputPartTypeFile", + "ChatInputPartTypeFileReference" + ] + }, + "codersdk.ChatMessage": { + "type": "object", + "properties": { + "chat_id": { + "type": "string", + "format": "uuid" + }, + "content": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatMessagePart" + } + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "created_by": { + "type": "string", + "format": "uuid" + }, + "id": { + "type": "integer" + }, + "model_config_id": { + "type": "string", + "format": "uuid" + }, + "role": { + "$ref": "#/definitions/codersdk.ChatMessageRole" + }, + "usage": { + "$ref": "#/definitions/codersdk.ChatMessageUsage" + } + } + }, + "codersdk.ChatMessagePart": { + "type": "object", + "properties": { + "args": { + "type": "array", + "items": { + "type": "integer" + } + }, + "args_delta": { + "type": "string" + }, + "content": { + "description": "The code content from the diff that was commented on.", + "type": "string" + }, + "context_file_agent_id": { + "description": "ContextFileAgentID is the workspace agent that provided\nthis context file. Used to detect when the agent changes\n(e.g. workspace rebuilt) so instruction files can be\nre-persisted with fresh content.", + "format": "uuid", + "allOf": [ + { + "$ref": "#/definitions/uuid.NullUUID" + } + ] + }, + "context_file_content": { + "description": "ContextFileContent holds the file content sent to the LLM.\nInternal only: stripped before API responses to keep\npayloads small. The backend reads it when building the\nprompt via partsToMessageParts.", + "type": "string" + }, + "context_file_directory": { + "description": "ContextFileDirectory is the working directory of the\nworkspace agent. Internal only: same purpose as\nContextFileOS.", + "type": "string" + }, + "context_file_os": { + "description": "ContextFileOS is the operating system of the workspace\nagent. Internal only: used during prompt expansion so\nthe LLM knows the OS even on turns where InsertSystem\nis not called.", + "type": "string" + }, + "context_file_path": { + "description": "ContextFilePath is the absolute path of a file loaded into\nthe LLM context (e.g. an AGENTS.md instruction file).", + "type": "string" + }, + "context_file_skill_meta_file": { + "description": "ContextFileSkillMetaFile is the basename of the skill\nmeta file (e.g. \"SKILL.md\") at the time of persistence.\nInternal only: restored on subsequent turns so the\nread_skill tool uses the correct filename even when the\nagent configured a non-default value.", + "type": "string" + }, + "context_file_truncated": { + "description": "ContextFileTruncated indicates the file exceeded the 64KiB\ninstruction file limit and was truncated.", + "type": "boolean" + }, + "created_at": { + "description": "CreatedAt records when this part was produced. Present on\ntool-call and tool-result parts so the frontend can compute\ntool execution duration.", + "type": "string", + "format": "date-time" + }, + "data": { + "type": "array", + "items": { + "type": "integer" + } + }, + "end_line": { + "type": "integer" + }, + "file_id": { + "format": "uuid", + "allOf": [ + { + "$ref": "#/definitions/uuid.NullUUID" + } + ] + }, + "file_name": { + "type": "string" + }, + "is_error": { + "type": "boolean" + }, + "is_media": { + "type": "boolean" + }, + "mcp_server_config_id": { + "format": "uuid", + "allOf": [ + { + "$ref": "#/definitions/uuid.NullUUID" + } + ] + }, + "media_type": { + "type": "string" + }, + "name": { + "type": "string" + }, + "provider_executed": { + "description": "ProviderExecuted indicates the tool call was executed by\nthe provider (e.g. Anthropic computer use).", + "type": "boolean" + }, + "provider_metadata": { + "description": "ProviderMetadata holds provider-specific response metadata\n(e.g. Anthropic cache control hints) as raw JSON. Internal\nonly: stripped by db2sdk before API responses.", + "type": "array", + "items": { + "type": "integer" + } + }, + "result": { + "type": "array", + "items": { + "type": "integer" + } + }, + "result_delta": { + "type": "string" + }, + "signature": { + "type": "string" + }, + "skill_description": { + "description": "SkillDescription is the short description from the skill's\nSKILL.md frontmatter.", + "type": "string" + }, + "skill_dir": { + "description": "SkillDir is the absolute path to the skill directory inside\nthe workspace filesystem. Internal only: used by\nread_skill/read_skill_file tools to locate skill files.", + "type": "string" + }, + "skill_name": { + "description": "SkillName is the kebab-case name of a discovered skill\nfrom the workspace's .agents/skills/ directory.", + "type": "string" + }, + "source_id": { + "type": "string" + }, + "start_line": { + "type": "integer" + }, + "text": { + "type": "string" + }, + "title": { + "type": "string" + }, + "tool_call_id": { + "type": "string" + }, + "tool_name": { + "type": "string" + }, + "type": { + "$ref": "#/definitions/codersdk.ChatMessagePartType" + }, + "url": { + "type": "string" + } + } + }, + "codersdk.ChatMessagePartType": { + "type": "string", + "enum": [ + "text", + "reasoning", + "tool-call", + "tool-result", + "source", + "file", + "file-reference", + "context-file", + "skill" + ], + "x-enum-varnames": [ + "ChatMessagePartTypeText", + "ChatMessagePartTypeReasoning", + "ChatMessagePartTypeToolCall", + "ChatMessagePartTypeToolResult", + "ChatMessagePartTypeSource", + "ChatMessagePartTypeFile", + "ChatMessagePartTypeFileReference", + "ChatMessagePartTypeContextFile", + "ChatMessagePartTypeSkill" + ] + }, + "codersdk.ChatMessageRole": { + "type": "string", + "enum": [ + "system", + "user", + "assistant", + "tool" + ], + "x-enum-varnames": [ + "ChatMessageRoleSystem", + "ChatMessageRoleUser", + "ChatMessageRoleAssistant", + "ChatMessageRoleTool" + ] + }, + "codersdk.ChatMessageUsage": { + "type": "object", + "properties": { + "cache_creation_tokens": { + "type": "integer" + }, + "cache_read_tokens": { + "type": "integer" + }, + "context_limit": { + "type": "integer" + }, + "input_tokens": { + "type": "integer" + }, + "output_tokens": { + "type": "integer" + }, + "reasoning_tokens": { + "type": "integer" + }, + "total_tokens": { + "type": "integer" + } + } + }, + "codersdk.ChatMessagesResponse": { + "type": "object", + "properties": { + "has_more": { + "type": "boolean" + }, + "messages": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatMessage" + } + }, + "queued_messages": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatQueuedMessage" + } + } + } + }, + "codersdk.ChatModel": { + "type": "object", + "properties": { + "display_name": { + "type": "string" + }, + "id": { + "type": "string" + }, + "model": { + "type": "string" + }, + "provider": { + "type": "string" + } + } + }, + "codersdk.ChatModelProvider": { + "type": "object", + "properties": { + "available": { + "type": "boolean" + }, + "models": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatModel" + } + }, + "provider": { + "type": "string" + }, + "unavailable_reason": { + "$ref": "#/definitions/codersdk.ChatModelProviderUnavailableReason" + } + } + }, + "codersdk.ChatModelProviderUnavailableReason": { + "type": "string", + "enum": [ + "missing_api_key", + "fetch_failed", + "user_api_key_required" + ], + "x-enum-varnames": [ + "ChatModelProviderUnavailableMissingAPIKey", + "ChatModelProviderUnavailableFetchFailed", + "ChatModelProviderUnavailableReasonUserAPIKeyRequired" + ] + }, + "codersdk.ChatModelsResponse": { + "type": "object", + "properties": { + "providers": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatModelProvider" + } + } + } + }, + "codersdk.ChatPlanMode": { + "type": "string", + "enum": [ + "plan" + ], + "x-enum-varnames": [ + "ChatPlanModePlan" + ] + }, + "codersdk.ChatQueuedMessage": { + "type": "object", + "properties": { + "chat_id": { + "type": "string", + "format": "uuid" + }, + "content": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatMessagePart" + } + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "id": { + "type": "integer" + }, + "model_config_id": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.ChatRetentionDaysResponse": { "type": "object", "properties": { @@ -14786,6 +16149,198 @@ const docTemplate = `{ } } }, + "codersdk.ChatStatus": { + "type": "string", + "enum": [ + "waiting", + "pending", + "running", + "paused", + "completed", + "error", + "requires_action" + ], + "x-enum-varnames": [ + "ChatStatusWaiting", + "ChatStatusPending", + "ChatStatusRunning", + "ChatStatusPaused", + "ChatStatusCompleted", + "ChatStatusError", + "ChatStatusRequiresAction" + ] + }, + "codersdk.ChatStreamActionRequired": { + "type": "object", + "properties": { + "tool_calls": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatStreamToolCall" + } + } + } + }, + "codersdk.ChatStreamEvent": { + "type": "object", + "properties": { + "action_required": { + "$ref": "#/definitions/codersdk.ChatStreamActionRequired" + }, + "chat_id": { + "type": "string", + "format": "uuid" + }, + "error": { + "$ref": "#/definitions/codersdk.ChatError" + }, + "message": { + "$ref": "#/definitions/codersdk.ChatMessage" + }, + "message_part": { + "$ref": "#/definitions/codersdk.ChatStreamMessagePart" + }, + "queued_messages": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatQueuedMessage" + } + }, + "retry": { + "$ref": "#/definitions/codersdk.ChatStreamRetry" + }, + "status": { + "$ref": "#/definitions/codersdk.ChatStreamStatus" + }, + "type": { + "$ref": "#/definitions/codersdk.ChatStreamEventType" + } + } + }, + "codersdk.ChatStreamEventType": { + "type": "string", + "enum": [ + "message_part", + "message", + "status", + "error", + "queue_update", + "retry", + "action_required" + ], + "x-enum-varnames": [ + "ChatStreamEventTypeMessagePart", + "ChatStreamEventTypeMessage", + "ChatStreamEventTypeStatus", + "ChatStreamEventTypeError", + "ChatStreamEventTypeQueueUpdate", + "ChatStreamEventTypeRetry", + "ChatStreamEventTypeActionRequired" + ] + }, + "codersdk.ChatStreamMessagePart": { + "type": "object", + "properties": { + "part": { + "$ref": "#/definitions/codersdk.ChatMessagePart" + }, + "role": { + "$ref": "#/definitions/codersdk.ChatMessageRole" + } + } + }, + "codersdk.ChatStreamRetry": { + "type": "object", + "properties": { + "attempt": { + "description": "Attempt is the 1-indexed retry attempt number.", + "type": "integer" + }, + "delay_ms": { + "description": "DelayMs is the backoff delay in milliseconds before the retry.", + "type": "integer" + }, + "error": { + "description": "Error is the normalized error message from the failed attempt.", + "type": "string" + }, + "kind": { + "description": "Kind classifies the retry reason for consistent client rendering.", + "type": "string" + }, + "provider": { + "description": "Provider identifies the upstream model provider when known.", + "type": "string" + }, + "retrying_at": { + "description": "RetryingAt is the timestamp when the retry will be attempted.", + "type": "string", + "format": "date-time" + }, + "status_code": { + "description": "StatusCode is the best-effort upstream HTTP status code.", + "type": "integer" + } + } + }, + "codersdk.ChatStreamStatus": { + "type": "object", + "properties": { + "status": { + "$ref": "#/definitions/codersdk.ChatStatus" + } + } + }, + "codersdk.ChatStreamToolCall": { + "type": "object", + "properties": { + "args": { + "type": "string" + }, + "tool_call_id": { + "type": "string" + }, + "tool_name": { + "type": "string" + } + } + }, + "codersdk.ChatWatchEvent": { + "type": "object", + "properties": { + "chat": { + "$ref": "#/definitions/codersdk.Chat" + }, + "kind": { + "$ref": "#/definitions/codersdk.ChatWatchEventKind" + }, + "tool_calls": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatStreamToolCall" + } + } + } + }, + "codersdk.ChatWatchEventKind": { + "type": "string", + "enum": [ + "status_change", + "title_change", + "created", + "deleted", + "diff_status_change", + "action_required" + ], + "x-enum-varnames": [ + "ChatWatchEventKindStatusChange", + "ChatWatchEventKindTitleChange", + "ChatWatchEventKindCreated", + "ChatWatchEventKindDeleted", + "ChatWatchEventKindDiffStatusChange", + "ChatWatchEventKindActionRequired" + ] + }, "codersdk.ConnectionLatency": { "type": "object", "properties": { @@ -14955,6 +16510,119 @@ const docTemplate = `{ } } }, + "codersdk.CreateChatMessageRequest": { + "type": "object", + "properties": { + "busy_behavior": { + "enum": [ + "queue", + "interrupt" + ], + "allOf": [ + { + "$ref": "#/definitions/codersdk.ChatBusyBehavior" + } + ] + }, + "content": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatInputPart" + } + }, + "mcp_server_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "model_config_id": { + "type": "string", + "format": "uuid" + }, + "plan_mode": { + "description": "PlanMode switches the chat's persistent plan mode.\nnil: no change, ptr to \"plan\": enable, ptr to \"\": clear.", + "allOf": [ + { + "$ref": "#/definitions/codersdk.ChatPlanMode" + } + ] + } + } + }, + "codersdk.CreateChatMessageResponse": { + "type": "object", + "properties": { + "message": { + "$ref": "#/definitions/codersdk.ChatMessage" + }, + "queued": { + "type": "boolean" + }, + "queued_message": { + "$ref": "#/definitions/codersdk.ChatQueuedMessage" + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "codersdk.CreateChatRequest": { + "type": "object", + "properties": { + "client_type": { + "$ref": "#/definitions/codersdk.ChatClientType" + }, + "content": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatInputPart" + } + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "mcp_server_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "model_config_id": { + "type": "string", + "format": "uuid" + }, + "organization_id": { + "type": "string", + "format": "uuid" + }, + "plan_mode": { + "$ref": "#/definitions/codersdk.ChatPlanMode" + }, + "system_prompt": { + "type": "string" + }, + "unsafe_dynamic_tools": { + "description": "UnsafeDynamicTools declares client-executed tools that the\nLLM can invoke. This API is highly experimental and highly\nsubject to change.", + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.DynamicTool" + } + }, + "workspace_id": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.CreateFirstUserOnboardingInfo": { "type": "object", "properties": { @@ -16214,6 +17882,49 @@ const docTemplate = `{ } } }, + "codersdk.DynamicTool": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "input_schema": { + "description": "InputSchema's JSON key \"input_schema\" uses snake_case for\nSDK consistency, deviating from the camelCase \"inputSchema\"\nconvention used by MCP.", + "type": "array", + "items": { + "type": "integer" + } + }, + "name": { + "type": "string" + } + } + }, + "codersdk.EditChatMessageRequest": { + "type": "object", + "properties": { + "content": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatInputPart" + } + } + } + }, + "codersdk.EditChatMessageResponse": { + "type": "object", + "properties": { + "message": { + "$ref": "#/definitions/codersdk.ChatMessage" + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, "codersdk.Entitlement": { "type": "string", "enum": [ @@ -21384,6 +23095,39 @@ const docTemplate = `{ } } }, + "codersdk.UpdateChatRequest": { + "type": "object", + "properties": { + "archived": { + "type": "boolean" + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "pin_order": { + "description": "PinOrder controls the chat's pinned state and position.\n- nil: no change to pin state.\n- 0: unpin the chat.\n- \u003e0 (chat is unpinned): pin the chat, appending it to\n the end of the pinned list. The specific value is\n ignored; the server assigns the next available position.\n- \u003e0 (chat is already pinned): move the chat to the\n requested position, shifting neighbors as needed. The\n value is clamped to [1, pinned_count].", + "type": "integer" + }, + "plan_mode": { + "description": "PlanMode switches the chat's persistent plan mode.\nnil: no change, ptr to \"plan\": enable, ptr to \"\": clear.", + "allOf": [ + { + "$ref": "#/definitions/codersdk.ChatPlanMode" + } + ] + }, + "title": { + "type": "string" + }, + "workspace_id": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.UpdateChatRetentionDaysRequest": { "type": "object", "properties": { @@ -21746,6 +23490,15 @@ const docTemplate = `{ } } }, + "codersdk.UploadChatFileResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.UploadResponse": { "type": "object", "properties": { @@ -22698,6 +24451,38 @@ const docTemplate = `{ "WorkspaceAgentDevcontainerStatusError" ] }, + "codersdk.WorkspaceAgentGitServerMessage": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "repositories": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.WorkspaceAgentRepoChanges" + } + }, + "scanned_at": { + "type": "string", + "format": "date-time" + }, + "type": { + "$ref": "#/definitions/codersdk.WorkspaceAgentGitServerMessageType" + } + } + }, + "codersdk.WorkspaceAgentGitServerMessageType": { + "type": "string", + "enum": [ + "changes", + "error" + ], + "x-enum-varnames": [ + "WorkspaceAgentGitServerMessageTypeChanges", + "WorkspaceAgentGitServerMessageTypeError" + ] + }, "codersdk.WorkspaceAgentHealth": { "type": "object", "properties": { @@ -22913,6 +24698,26 @@ const docTemplate = `{ } } }, + "codersdk.WorkspaceAgentRepoChanges": { + "type": "object", + "properties": { + "branch": { + "type": "string" + }, + "remote_origin": { + "type": "string" + }, + "removed": { + "type": "boolean" + }, + "repo_root": { + "type": "string" + }, + "unified_diff": { + "type": "string" + } + } + }, "codersdk.WorkspaceAgentScript": { "type": "object", "properties": { diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index f34aa8e898..12fae96382 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -10845,6 +10845,599 @@ ] } }, + "/experimental/chats": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "List chats", + "operationId": "list-chats", + "parameters": [ + { + "type": "string", + "description": "Search query", + "name": "q", + "in": "query" + }, + { + "type": "string", + "description": "Filter by label as key:value. Repeat for multiple (AND logic).", + "name": "label", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Chat" + } + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + }, + "post": { + "description": "Experimental: this endpoint is subject to change.", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "Create chat", + "operationId": "create-chat", + "parameters": [ + { + "description": "Create chat request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.CreateChatRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.Chat" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/files": { + "post": { + "description": "Experimental: this endpoint is subject to change.", + "consumes": [ + "image/png", + "image/jpeg", + "image/gif", + "image/webp", + "text/plain", + "text/markdown", + "text/csv", + "application/json", + "application/pdf" + ], + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "Upload chat file", + "operationId": "upload-chat-file", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "query", + "required": true + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.UploadChatFileResponse" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/files/{file}": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": [ + "image/png", + "image/jpeg", + "image/gif", + "image/webp", + "text/plain", + "text/markdown", + "text/csv", + "application/json", + "application/pdf" + ], + "tags": ["Chats"], + "summary": "Get chat file", + "operationId": "get-chat-file", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "File ID", + "name": "file", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK" + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/models": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "List chat models", + "operationId": "list-chat-models", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.ChatModelsResponse" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/watch": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "Watch chat events for a user via WebSockets", + "operationId": "watch-chat-events-for-a-user-via-websockets", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.ChatWatchEvent" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "Get chat by ID", + "operationId": "get-chat-by-id", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Chat" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + }, + "patch": { + "description": "Experimental: this endpoint is subject to change.", + "consumes": ["application/json"], + "tags": ["Chats"], + "summary": "Update chat", + "operationId": "update-chat", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + }, + { + "description": "Update chat request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.UpdateChatRequest" + } + } + ], + "responses": { + "204": { + "description": "No Content" + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/diff": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "Get chat diff contents", + "operationId": "get-chat-diff-contents", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.ChatDiffContents" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/interrupt": { + "post": { + "description": "Experimental: this endpoint is subject to change.", + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "Interrupt chat", + "operationId": "interrupt-chat", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Chat" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/messages": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "List chat messages", + "operationId": "list-chat-messages", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "Return messages with id \u003c before_id", + "name": "before_id", + "in": "query" + }, + { + "type": "integer", + "description": "Return messages with id \u003e after_id", + "name": "after_id", + "in": "query" + }, + { + "type": "integer", + "description": "Page size, 1 to 200. Defaults to 50.", + "name": "limit", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.ChatMessagesResponse" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + }, + "post": { + "description": "Experimental: this endpoint is subject to change.", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "Send chat message", + "operationId": "send-chat-message", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + }, + { + "description": "Create chat message request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.CreateChatMessageRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.CreateChatMessageResponse" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/messages/{message}": { + "patch": { + "description": "Experimental: this endpoint is subject to change.", + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "Edit chat message", + "operationId": "edit-chat-message", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "Message ID", + "name": "message", + "in": "path", + "required": true + }, + { + "description": "Edit chat message request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.EditChatMessageRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.EditChatMessageResponse" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/stream": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "Stream chat events via WebSockets", + "operationId": "stream-chat-events-via-websockets", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.ChatStreamEvent" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/stream/desktop": { + "get": { + "description": "Raw binary WebSocket stream of the chat workspace desktop.\nExperimental: this endpoint is subject to change.", + "produces": ["application/octet-stream"], + "tags": ["Chats"], + "summary": "Connect to chat workspace desktop via WebSockets", + "operationId": "connect-to-chat-workspace-desktop-via-websockets", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "101": { + "description": "Switching Protocols" + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/stream/git": { + "get": { + "description": "Experimental: this endpoint is subject to change.", + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "Watch chat workspace git state via WebSockets", + "operationId": "watch-chat-workspace-git-state-via-websockets", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.WorkspaceAgentGitServerMessage" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, + "/experimental/chats/{chat}/title/regenerate": { + "post": { + "description": "Experimental: this endpoint is subject to change.", + "produces": ["application/json"], + "tags": ["Chats"], + "summary": "Regenerate chat title", + "operationId": "regenerate-chat-title", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Chat ID", + "name": "chat", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Chat" + } + } + }, + "security": [ + { + "CoderSessionToken": [] + } + ] + } + }, "/oauth2/authorize": { "get": { "tags": ["Enterprise"], @@ -13280,6 +13873,132 @@ } } }, + "codersdk.Chat": { + "type": "object", + "properties": { + "agent_id": { + "type": "string", + "format": "uuid" + }, + "archived": { + "type": "boolean" + }, + "build_id": { + "type": "string", + "format": "uuid" + }, + "children": { + "description": "Children holds child (subagent) chats nested under this root\nchat. Always initialized to an empty slice so the JSON field\nis present as []. Child chats cannot create their own\nsubagents, so nesting depth is capped at 1 and this slice is\nalways empty for child chats.", + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Chat" + } + }, + "client_type": { + "$ref": "#/definitions/codersdk.ChatClientType" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "diff_status": { + "$ref": "#/definitions/codersdk.ChatDiffStatus" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatFileMetadata" + } + }, + "has_unread": { + "description": "HasUnread is true when assistant messages exist beyond\nthe owner's read cursor, which updates on stream\nconnect and disconnect.", + "type": "boolean" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "last_error": { + "$ref": "#/definitions/codersdk.ChatError" + }, + "last_injected_context": { + "description": "LastInjectedContext holds the most recently persisted\ninjected context parts (AGENTS.md files and skills). It\nis updated only when context changes, on first workspace\nattach or agent change.", + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatMessagePart" + } + }, + "last_model_config_id": { + "type": "string", + "format": "uuid" + }, + "mcp_server_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "organization_id": { + "type": "string", + "format": "uuid" + }, + "owner_id": { + "type": "string", + "format": "uuid" + }, + "parent_chat_id": { + "type": "string", + "format": "uuid" + }, + "pin_order": { + "type": "integer" + }, + "plan_mode": { + "$ref": "#/definitions/codersdk.ChatPlanMode" + }, + "root_chat_id": { + "type": "string", + "format": "uuid" + }, + "status": { + "$ref": "#/definitions/codersdk.ChatStatus" + }, + "title": { + "type": "string" + }, + "updated_at": { + "type": "string", + "format": "date-time" + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + }, + "workspace_id": { + "type": "string", + "format": "uuid" + } + } + }, + "codersdk.ChatBusyBehavior": { + "type": "string", + "enum": ["queue", "interrupt"], + "x-enum-varnames": ["ChatBusyBehaviorQueue", "ChatBusyBehaviorInterrupt"] + }, + "codersdk.ChatClientType": { + "type": "string", + "enum": ["ui", "api"], + "x-enum-varnames": ["ChatClientTypeUI", "ChatClientTypeAPI"] + }, "codersdk.ChatConfig": { "type": "object", "properties": { @@ -13291,6 +14010,549 @@ } } }, + "codersdk.ChatDiffContents": { + "type": "object", + "properties": { + "branch": { + "type": "string" + }, + "chat_id": { + "type": "string", + "format": "uuid" + }, + "diff": { + "type": "string" + }, + "provider": { + "type": "string" + }, + "pull_request_url": { + "type": "string" + }, + "remote_origin": { + "type": "string" + } + } + }, + "codersdk.ChatDiffStatus": { + "type": "object", + "properties": { + "additions": { + "type": "integer" + }, + "approved": { + "type": "boolean" + }, + "author_avatar_url": { + "type": "string" + }, + "author_login": { + "type": "string" + }, + "base_branch": { + "type": "string" + }, + "changed_files": { + "type": "integer" + }, + "changes_requested": { + "type": "boolean" + }, + "chat_id": { + "type": "string", + "format": "uuid" + }, + "commits": { + "type": "integer" + }, + "deletions": { + "type": "integer" + }, + "head_branch": { + "type": "string" + }, + "pr_number": { + "type": "integer" + }, + "pull_request_draft": { + "type": "boolean" + }, + "pull_request_state": { + "type": "string" + }, + "pull_request_title": { + "type": "string" + }, + "refreshed_at": { + "type": "string", + "format": "date-time" + }, + "reviewer_count": { + "type": "integer" + }, + "stale_at": { + "type": "string", + "format": "date-time" + }, + "url": { + "type": "string" + } + } + }, + "codersdk.ChatError": { + "type": "object", + "properties": { + "detail": { + "description": "Detail is optional provider-specific context shown alongside the\nnormalized error message when available.", + "type": "string" + }, + "kind": { + "description": "Kind classifies the error for consistent client rendering.", + "type": "string" + }, + "message": { + "description": "Message is the normalized, user-facing error message.", + "type": "string" + }, + "provider": { + "description": "Provider identifies the upstream model provider when known.", + "type": "string" + }, + "retryable": { + "description": "Retryable reports whether the underlying error is transient.", + "type": "boolean" + }, + "status_code": { + "description": "StatusCode is the best-effort upstream HTTP status code.", + "type": "integer" + } + } + }, + "codersdk.ChatFileMetadata": { + "type": "object", + "properties": { + "created_at": { + "type": "string", + "format": "date-time" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "mime_type": { + "type": "string" + }, + "name": { + "type": "string" + }, + "organization_id": { + "type": "string", + "format": "uuid" + }, + "owner_id": { + "type": "string", + "format": "uuid" + } + } + }, + "codersdk.ChatInputPart": { + "type": "object", + "properties": { + "content": { + "description": "The code content from the diff that was commented on.", + "type": "string" + }, + "end_line": { + "type": "integer" + }, + "file_id": { + "type": "string", + "format": "uuid" + }, + "file_name": { + "description": "The following fields are only set when Type is\nChatInputPartTypeFileReference.", + "type": "string" + }, + "start_line": { + "type": "integer" + }, + "text": { + "type": "string" + }, + "type": { + "$ref": "#/definitions/codersdk.ChatInputPartType" + } + } + }, + "codersdk.ChatInputPartType": { + "type": "string", + "enum": ["text", "file", "file-reference"], + "x-enum-varnames": [ + "ChatInputPartTypeText", + "ChatInputPartTypeFile", + "ChatInputPartTypeFileReference" + ] + }, + "codersdk.ChatMessage": { + "type": "object", + "properties": { + "chat_id": { + "type": "string", + "format": "uuid" + }, + "content": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatMessagePart" + } + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "created_by": { + "type": "string", + "format": "uuid" + }, + "id": { + "type": "integer" + }, + "model_config_id": { + "type": "string", + "format": "uuid" + }, + "role": { + "$ref": "#/definitions/codersdk.ChatMessageRole" + }, + "usage": { + "$ref": "#/definitions/codersdk.ChatMessageUsage" + } + } + }, + "codersdk.ChatMessagePart": { + "type": "object", + "properties": { + "args": { + "type": "array", + "items": { + "type": "integer" + } + }, + "args_delta": { + "type": "string" + }, + "content": { + "description": "The code content from the diff that was commented on.", + "type": "string" + }, + "context_file_agent_id": { + "description": "ContextFileAgentID is the workspace agent that provided\nthis context file. Used to detect when the agent changes\n(e.g. workspace rebuilt) so instruction files can be\nre-persisted with fresh content.", + "format": "uuid", + "allOf": [ + { + "$ref": "#/definitions/uuid.NullUUID" + } + ] + }, + "context_file_content": { + "description": "ContextFileContent holds the file content sent to the LLM.\nInternal only: stripped before API responses to keep\npayloads small. The backend reads it when building the\nprompt via partsToMessageParts.", + "type": "string" + }, + "context_file_directory": { + "description": "ContextFileDirectory is the working directory of the\nworkspace agent. Internal only: same purpose as\nContextFileOS.", + "type": "string" + }, + "context_file_os": { + "description": "ContextFileOS is the operating system of the workspace\nagent. Internal only: used during prompt expansion so\nthe LLM knows the OS even on turns where InsertSystem\nis not called.", + "type": "string" + }, + "context_file_path": { + "description": "ContextFilePath is the absolute path of a file loaded into\nthe LLM context (e.g. an AGENTS.md instruction file).", + "type": "string" + }, + "context_file_skill_meta_file": { + "description": "ContextFileSkillMetaFile is the basename of the skill\nmeta file (e.g. \"SKILL.md\") at the time of persistence.\nInternal only: restored on subsequent turns so the\nread_skill tool uses the correct filename even when the\nagent configured a non-default value.", + "type": "string" + }, + "context_file_truncated": { + "description": "ContextFileTruncated indicates the file exceeded the 64KiB\ninstruction file limit and was truncated.", + "type": "boolean" + }, + "created_at": { + "description": "CreatedAt records when this part was produced. Present on\ntool-call and tool-result parts so the frontend can compute\ntool execution duration.", + "type": "string", + "format": "date-time" + }, + "data": { + "type": "array", + "items": { + "type": "integer" + } + }, + "end_line": { + "type": "integer" + }, + "file_id": { + "format": "uuid", + "allOf": [ + { + "$ref": "#/definitions/uuid.NullUUID" + } + ] + }, + "file_name": { + "type": "string" + }, + "is_error": { + "type": "boolean" + }, + "is_media": { + "type": "boolean" + }, + "mcp_server_config_id": { + "format": "uuid", + "allOf": [ + { + "$ref": "#/definitions/uuid.NullUUID" + } + ] + }, + "media_type": { + "type": "string" + }, + "name": { + "type": "string" + }, + "provider_executed": { + "description": "ProviderExecuted indicates the tool call was executed by\nthe provider (e.g. Anthropic computer use).", + "type": "boolean" + }, + "provider_metadata": { + "description": "ProviderMetadata holds provider-specific response metadata\n(e.g. Anthropic cache control hints) as raw JSON. Internal\nonly: stripped by db2sdk before API responses.", + "type": "array", + "items": { + "type": "integer" + } + }, + "result": { + "type": "array", + "items": { + "type": "integer" + } + }, + "result_delta": { + "type": "string" + }, + "signature": { + "type": "string" + }, + "skill_description": { + "description": "SkillDescription is the short description from the skill's\nSKILL.md frontmatter.", + "type": "string" + }, + "skill_dir": { + "description": "SkillDir is the absolute path to the skill directory inside\nthe workspace filesystem. Internal only: used by\nread_skill/read_skill_file tools to locate skill files.", + "type": "string" + }, + "skill_name": { + "description": "SkillName is the kebab-case name of a discovered skill\nfrom the workspace's .agents/skills/ directory.", + "type": "string" + }, + "source_id": { + "type": "string" + }, + "start_line": { + "type": "integer" + }, + "text": { + "type": "string" + }, + "title": { + "type": "string" + }, + "tool_call_id": { + "type": "string" + }, + "tool_name": { + "type": "string" + }, + "type": { + "$ref": "#/definitions/codersdk.ChatMessagePartType" + }, + "url": { + "type": "string" + } + } + }, + "codersdk.ChatMessagePartType": { + "type": "string", + "enum": [ + "text", + "reasoning", + "tool-call", + "tool-result", + "source", + "file", + "file-reference", + "context-file", + "skill" + ], + "x-enum-varnames": [ + "ChatMessagePartTypeText", + "ChatMessagePartTypeReasoning", + "ChatMessagePartTypeToolCall", + "ChatMessagePartTypeToolResult", + "ChatMessagePartTypeSource", + "ChatMessagePartTypeFile", + "ChatMessagePartTypeFileReference", + "ChatMessagePartTypeContextFile", + "ChatMessagePartTypeSkill" + ] + }, + "codersdk.ChatMessageRole": { + "type": "string", + "enum": ["system", "user", "assistant", "tool"], + "x-enum-varnames": [ + "ChatMessageRoleSystem", + "ChatMessageRoleUser", + "ChatMessageRoleAssistant", + "ChatMessageRoleTool" + ] + }, + "codersdk.ChatMessageUsage": { + "type": "object", + "properties": { + "cache_creation_tokens": { + "type": "integer" + }, + "cache_read_tokens": { + "type": "integer" + }, + "context_limit": { + "type": "integer" + }, + "input_tokens": { + "type": "integer" + }, + "output_tokens": { + "type": "integer" + }, + "reasoning_tokens": { + "type": "integer" + }, + "total_tokens": { + "type": "integer" + } + } + }, + "codersdk.ChatMessagesResponse": { + "type": "object", + "properties": { + "has_more": { + "type": "boolean" + }, + "messages": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatMessage" + } + }, + "queued_messages": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatQueuedMessage" + } + } + } + }, + "codersdk.ChatModel": { + "type": "object", + "properties": { + "display_name": { + "type": "string" + }, + "id": { + "type": "string" + }, + "model": { + "type": "string" + }, + "provider": { + "type": "string" + } + } + }, + "codersdk.ChatModelProvider": { + "type": "object", + "properties": { + "available": { + "type": "boolean" + }, + "models": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatModel" + } + }, + "provider": { + "type": "string" + }, + "unavailable_reason": { + "$ref": "#/definitions/codersdk.ChatModelProviderUnavailableReason" + } + } + }, + "codersdk.ChatModelProviderUnavailableReason": { + "type": "string", + "enum": ["missing_api_key", "fetch_failed", "user_api_key_required"], + "x-enum-varnames": [ + "ChatModelProviderUnavailableMissingAPIKey", + "ChatModelProviderUnavailableFetchFailed", + "ChatModelProviderUnavailableReasonUserAPIKeyRequired" + ] + }, + "codersdk.ChatModelsResponse": { + "type": "object", + "properties": { + "providers": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatModelProvider" + } + } + } + }, + "codersdk.ChatPlanMode": { + "type": "string", + "enum": ["plan"], + "x-enum-varnames": ["ChatPlanModePlan"] + }, + "codersdk.ChatQueuedMessage": { + "type": "object", + "properties": { + "chat_id": { + "type": "string", + "format": "uuid" + }, + "content": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatMessagePart" + } + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "id": { + "type": "integer" + }, + "model_config_id": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.ChatRetentionDaysResponse": { "type": "object", "properties": { @@ -13299,6 +14561,198 @@ } } }, + "codersdk.ChatStatus": { + "type": "string", + "enum": [ + "waiting", + "pending", + "running", + "paused", + "completed", + "error", + "requires_action" + ], + "x-enum-varnames": [ + "ChatStatusWaiting", + "ChatStatusPending", + "ChatStatusRunning", + "ChatStatusPaused", + "ChatStatusCompleted", + "ChatStatusError", + "ChatStatusRequiresAction" + ] + }, + "codersdk.ChatStreamActionRequired": { + "type": "object", + "properties": { + "tool_calls": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatStreamToolCall" + } + } + } + }, + "codersdk.ChatStreamEvent": { + "type": "object", + "properties": { + "action_required": { + "$ref": "#/definitions/codersdk.ChatStreamActionRequired" + }, + "chat_id": { + "type": "string", + "format": "uuid" + }, + "error": { + "$ref": "#/definitions/codersdk.ChatError" + }, + "message": { + "$ref": "#/definitions/codersdk.ChatMessage" + }, + "message_part": { + "$ref": "#/definitions/codersdk.ChatStreamMessagePart" + }, + "queued_messages": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatQueuedMessage" + } + }, + "retry": { + "$ref": "#/definitions/codersdk.ChatStreamRetry" + }, + "status": { + "$ref": "#/definitions/codersdk.ChatStreamStatus" + }, + "type": { + "$ref": "#/definitions/codersdk.ChatStreamEventType" + } + } + }, + "codersdk.ChatStreamEventType": { + "type": "string", + "enum": [ + "message_part", + "message", + "status", + "error", + "queue_update", + "retry", + "action_required" + ], + "x-enum-varnames": [ + "ChatStreamEventTypeMessagePart", + "ChatStreamEventTypeMessage", + "ChatStreamEventTypeStatus", + "ChatStreamEventTypeError", + "ChatStreamEventTypeQueueUpdate", + "ChatStreamEventTypeRetry", + "ChatStreamEventTypeActionRequired" + ] + }, + "codersdk.ChatStreamMessagePart": { + "type": "object", + "properties": { + "part": { + "$ref": "#/definitions/codersdk.ChatMessagePart" + }, + "role": { + "$ref": "#/definitions/codersdk.ChatMessageRole" + } + } + }, + "codersdk.ChatStreamRetry": { + "type": "object", + "properties": { + "attempt": { + "description": "Attempt is the 1-indexed retry attempt number.", + "type": "integer" + }, + "delay_ms": { + "description": "DelayMs is the backoff delay in milliseconds before the retry.", + "type": "integer" + }, + "error": { + "description": "Error is the normalized error message from the failed attempt.", + "type": "string" + }, + "kind": { + "description": "Kind classifies the retry reason for consistent client rendering.", + "type": "string" + }, + "provider": { + "description": "Provider identifies the upstream model provider when known.", + "type": "string" + }, + "retrying_at": { + "description": "RetryingAt is the timestamp when the retry will be attempted.", + "type": "string", + "format": "date-time" + }, + "status_code": { + "description": "StatusCode is the best-effort upstream HTTP status code.", + "type": "integer" + } + } + }, + "codersdk.ChatStreamStatus": { + "type": "object", + "properties": { + "status": { + "$ref": "#/definitions/codersdk.ChatStatus" + } + } + }, + "codersdk.ChatStreamToolCall": { + "type": "object", + "properties": { + "args": { + "type": "string" + }, + "tool_call_id": { + "type": "string" + }, + "tool_name": { + "type": "string" + } + } + }, + "codersdk.ChatWatchEvent": { + "type": "object", + "properties": { + "chat": { + "$ref": "#/definitions/codersdk.Chat" + }, + "kind": { + "$ref": "#/definitions/codersdk.ChatWatchEventKind" + }, + "tool_calls": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatStreamToolCall" + } + } + } + }, + "codersdk.ChatWatchEventKind": { + "type": "string", + "enum": [ + "status_change", + "title_change", + "created", + "deleted", + "diff_status_change", + "action_required" + ], + "x-enum-varnames": [ + "ChatWatchEventKindStatusChange", + "ChatWatchEventKindTitleChange", + "ChatWatchEventKindCreated", + "ChatWatchEventKindDeleted", + "ChatWatchEventKindDiffStatusChange", + "ChatWatchEventKindActionRequired" + ] + }, "codersdk.ConnectionLatency": { "type": "object", "properties": { @@ -13465,6 +14919,116 @@ } } }, + "codersdk.CreateChatMessageRequest": { + "type": "object", + "properties": { + "busy_behavior": { + "enum": ["queue", "interrupt"], + "allOf": [ + { + "$ref": "#/definitions/codersdk.ChatBusyBehavior" + } + ] + }, + "content": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatInputPart" + } + }, + "mcp_server_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "model_config_id": { + "type": "string", + "format": "uuid" + }, + "plan_mode": { + "description": "PlanMode switches the chat's persistent plan mode.\nnil: no change, ptr to \"plan\": enable, ptr to \"\": clear.", + "allOf": [ + { + "$ref": "#/definitions/codersdk.ChatPlanMode" + } + ] + } + } + }, + "codersdk.CreateChatMessageResponse": { + "type": "object", + "properties": { + "message": { + "$ref": "#/definitions/codersdk.ChatMessage" + }, + "queued": { + "type": "boolean" + }, + "queued_message": { + "$ref": "#/definitions/codersdk.ChatQueuedMessage" + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "codersdk.CreateChatRequest": { + "type": "object", + "properties": { + "client_type": { + "$ref": "#/definitions/codersdk.ChatClientType" + }, + "content": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatInputPart" + } + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "mcp_server_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "model_config_id": { + "type": "string", + "format": "uuid" + }, + "organization_id": { + "type": "string", + "format": "uuid" + }, + "plan_mode": { + "$ref": "#/definitions/codersdk.ChatPlanMode" + }, + "system_prompt": { + "type": "string" + }, + "unsafe_dynamic_tools": { + "description": "UnsafeDynamicTools declares client-executed tools that the\nLLM can invoke. This API is highly experimental and highly\nsubject to change.", + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.DynamicTool" + } + }, + "workspace_id": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.CreateFirstUserOnboardingInfo": { "type": "object", "properties": { @@ -14678,6 +16242,49 @@ } } }, + "codersdk.DynamicTool": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "input_schema": { + "description": "InputSchema's JSON key \"input_schema\" uses snake_case for\nSDK consistency, deviating from the camelCase \"inputSchema\"\nconvention used by MCP.", + "type": "array", + "items": { + "type": "integer" + } + }, + "name": { + "type": "string" + } + } + }, + "codersdk.EditChatMessageRequest": { + "type": "object", + "properties": { + "content": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ChatInputPart" + } + } + } + }, + "codersdk.EditChatMessageResponse": { + "type": "object", + "properties": { + "message": { + "$ref": "#/definitions/codersdk.ChatMessage" + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, "codersdk.Entitlement": { "type": "string", "enum": ["entitled", "grace_period", "not_entitled"], @@ -19640,6 +21247,39 @@ } } }, + "codersdk.UpdateChatRequest": { + "type": "object", + "properties": { + "archived": { + "type": "boolean" + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "pin_order": { + "description": "PinOrder controls the chat's pinned state and position.\n- nil: no change to pin state.\n- 0: unpin the chat.\n- \u003e0 (chat is unpinned): pin the chat, appending it to\n the end of the pinned list. The specific value is\n ignored; the server assigns the next available position.\n- \u003e0 (chat is already pinned): move the chat to the\n requested position, shifting neighbors as needed. The\n value is clamped to [1, pinned_count].", + "type": "integer" + }, + "plan_mode": { + "description": "PlanMode switches the chat's persistent plan mode.\nnil: no change, ptr to \"plan\": enable, ptr to \"\": clear.", + "allOf": [ + { + "$ref": "#/definitions/codersdk.ChatPlanMode" + } + ] + }, + "title": { + "type": "string" + }, + "workspace_id": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.UpdateChatRetentionDaysRequest": { "type": "object", "properties": { @@ -19989,6 +21629,15 @@ } } }, + "codersdk.UploadChatFileResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.UploadResponse": { "type": "object", "properties": { @@ -20905,6 +22554,35 @@ "WorkspaceAgentDevcontainerStatusError" ] }, + "codersdk.WorkspaceAgentGitServerMessage": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "repositories": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.WorkspaceAgentRepoChanges" + } + }, + "scanned_at": { + "type": "string", + "format": "date-time" + }, + "type": { + "$ref": "#/definitions/codersdk.WorkspaceAgentGitServerMessageType" + } + } + }, + "codersdk.WorkspaceAgentGitServerMessageType": { + "type": "string", + "enum": ["changes", "error"], + "x-enum-varnames": [ + "WorkspaceAgentGitServerMessageTypeChanges", + "WorkspaceAgentGitServerMessageTypeError" + ] + }, "codersdk.WorkspaceAgentHealth": { "type": "object", "properties": { @@ -21104,6 +22782,26 @@ } } }, + "codersdk.WorkspaceAgentRepoChanges": { + "type": "object", + "properties": { + "branch": { + "type": "string" + }, + "remote_origin": { + "type": "string" + }, + "removed": { + "type": "boolean" + }, + "repo_root": { + "type": "string" + }, + "unified_diff": { + "type": "string" + } + } + }, "codersdk.WorkspaceAgentScript": { "type": "object", "properties": { diff --git a/coderd/exp_chats.go b/coderd/exp_chats.go index 2069081bd1..33cd0e7183 100644 --- a/coderd/exp_chats.go +++ b/coderd/exp_chats.go @@ -161,6 +161,15 @@ func publishChatConfigEvent(logger slog.Logger, ps dbpubsub.Pubsub, kind pubsub. } // EXPERIMENTAL: this endpoint is experimental and is subject to change. +// +// @Summary Watch chat events for a user via WebSockets +// @ID watch-chat-events-for-a-user-via-websockets +// @Security CoderSessionToken +// @Tags Chats +// @Produce json +// @Success 200 {object} codersdk.ChatWatchEvent +// @Router /experimental/chats/watch [get] +// @Description Experimental: this endpoint is subject to change. func (api *API) watchChats(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() apiKey := httpmw.APIKey(r) @@ -297,6 +306,17 @@ func (api *API) chatsByWorkspace(rw http.ResponseWriter, r *http.Request) { } // EXPERIMENTAL: this endpoint is experimental and is subject to change. +// +// @Summary List chats +// @ID list-chats +// @Security CoderSessionToken +// @Tags Chats +// @Produce json +// @Param q query string false "Search query" +// @Param label query string false "Filter by label as key:value. Repeat for multiple (AND logic)." +// @Success 200 {array} codersdk.Chat +// @Router /experimental/chats [get] +// @Description Experimental: this endpoint is subject to change. func (api *API) listChats(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() apiKey := httpmw.APIKey(r) @@ -903,6 +923,17 @@ func (api *API) validateUserChatModelConfigAvailable( } // EXPERIMENTAL: this endpoint is experimental and is subject to change. +// +// @Summary Create chat +// @ID create-chat +// @Security CoderSessionToken +// @Tags Chats +// @Accept json +// @Produce json +// @Param request body codersdk.CreateChatRequest true "Create chat request" +// @Success 201 {object} codersdk.Chat +// @Router /experimental/chats [post] +// @Description Experimental: this endpoint is subject to change. func (api *API) postChats(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() apiKey := httpmw.APIKey(r) @@ -1184,6 +1215,15 @@ func (api *API) postChats(rw http.ResponseWriter, r *http.Request) { } // EXPERIMENTAL: this endpoint is experimental and is subject to change. +// +// @Summary List chat models +// @ID list-chat-models +// @Security CoderSessionToken +// @Tags Chats +// @Produce json +// @Success 200 {object} codersdk.ChatModelsResponse +// @Router /experimental/chats/models [get] +// @Description Experimental: this endpoint is subject to change. func (api *API) listChatModels(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() apiKey := httpmw.APIKey(r) @@ -1873,6 +1913,16 @@ func (api *API) deleteChatUsageLimitGroupOverride(rw http.ResponseWriter, r *htt // EXPERIMENTAL: this endpoint is experimental and is subject to change. // +// @Summary Get chat by ID +// @ID get-chat-by-id +// @Security CoderSessionToken +// @Tags Chats +// @Produce json +// @Param chat path string true "Chat ID" format(uuid) +// @Success 200 {object} codersdk.Chat +// @Router /experimental/chats/{chat} [get] +// @Description Experimental: this endpoint is subject to change. +// //nolint:revive // HTTP handler writes to ResponseWriter. func (api *API) getChat(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() @@ -1937,6 +1987,19 @@ func (api *API) getChat(rw http.ResponseWriter, r *http.Request) { // EXPERIMENTAL: this endpoint is experimental and is subject to change. // +// @Summary List chat messages +// @ID list-chat-messages +// @Security CoderSessionToken +// @Tags Chats +// @Produce json +// @Param chat path string true "Chat ID" format(uuid) +// @Param before_id query int false "Return messages with id < before_id" +// @Param after_id query int false "Return messages with id > after_id" +// @Param limit query int false "Page size, 1 to 200. Defaults to 50." +// @Success 200 {object} codersdk.ChatMessagesResponse +// @Router /experimental/chats/{chat}/messages [get] +// @Description Experimental: this endpoint is subject to change. +// //nolint:revive // HTTP handler writes to ResponseWriter. func (api *API) getChatMessages(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() @@ -2080,6 +2143,16 @@ func (api *API) authorizeChatWorkspaceExec( // EXPERIMENTAL: this endpoint is experimental and is subject to change. // +// @Summary Watch chat workspace git state via WebSockets +// @ID watch-chat-workspace-git-state-via-websockets +// @Security CoderSessionToken +// @Tags Chats +// @Produce json +// @Param chat path string true "Chat ID" format(uuid) +// @Success 200 {object} codersdk.WorkspaceAgentGitServerMessage +// @Router /experimental/chats/{chat}/stream/git [get] +// @Description Experimental: this endpoint is subject to change. +// //nolint:revive // HTTP handler writes to ResponseWriter. func (api *API) watchChatGit(rw http.ResponseWriter, r *http.Request) { var ( @@ -2225,6 +2298,17 @@ proxyLoop: // EXPERIMENTAL: this endpoint is experimental and is subject to change. // +// @Summary Connect to chat workspace desktop via WebSockets +// @ID connect-to-chat-workspace-desktop-via-websockets +// @Security CoderSessionToken +// @Tags Chats +// @Produce application/octet-stream +// @Param chat path string true "Chat ID" format(uuid) +// @Success 101 +// @Router /experimental/chats/{chat}/stream/desktop [get] +// @Description Raw binary WebSocket stream of the chat workspace desktop. +// @Description Experimental: this endpoint is subject to change. +// //nolint:revive // HTTP handler writes to ResponseWriter. func (api *API) watchChatDesktop(rw http.ResponseWriter, r *http.Request) { var ( @@ -2404,6 +2488,17 @@ func (api *API) applyChatTitleUpdate( // patchChat updates a chat resource. Supports updating labels, // workspace binding, archiving, pinning, and pinned-chat ordering. +// +// @Summary Update chat +// @ID update-chat +// @Security CoderSessionToken +// @Tags Chats +// @Accept json +// @Param chat path string true "Chat ID" format(uuid) +// @Param request body codersdk.UpdateChatRequest true "Update chat request" +// @Success 204 +// @Router /experimental/chats/{chat} [patch] +// @Description Experimental: this endpoint is subject to change. func (api *API) patchChat(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() chat := httpmw.ChatParam(r) @@ -2702,6 +2797,18 @@ func (api *API) writeChildUnarchiveGuard( } // EXPERIMENTAL: this endpoint is experimental and is subject to change. +// +// @Summary Send chat message +// @ID send-chat-message +// @Security CoderSessionToken +// @Tags Chats +// @Accept json +// @Produce json +// @Param chat path string true "Chat ID" format(uuid) +// @Param request body codersdk.CreateChatMessageRequest true "Create chat message request" +// @Success 200 {object} codersdk.CreateChatMessageResponse +// @Router /experimental/chats/{chat}/messages [post] +// @Description Experimental: this endpoint is subject to change. func (api *API) postChatMessages(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() apiKey := httpmw.APIKey(r) @@ -2874,6 +2981,19 @@ func (api *API) postChatMessages(rw http.ResponseWriter, r *http.Request) { } // EXPERIMENTAL: this endpoint is experimental and is subject to change. +// +// @Summary Edit chat message +// @ID edit-chat-message +// @Security CoderSessionToken +// @Tags Chats +// @Accept json +// @Produce json +// @Param chat path string true "Chat ID" format(uuid) +// @Param message path int true "Message ID" +// @Param request body codersdk.EditChatMessageRequest true "Edit chat message request" +// @Success 200 {object} codersdk.EditChatMessageResponse +// @Router /experimental/chats/{chat}/messages/{message} [patch] +// @Description Experimental: this endpoint is subject to change. func (api *API) patchChatMessage(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() apiKey := httpmw.APIKey(r) @@ -3102,6 +3222,16 @@ func (api *API) markChatAsRead(ctx context.Context, chatID uuid.UUID) { } // EXPERIMENTAL: this endpoint is experimental and is subject to change. +// +// @Summary Stream chat events via WebSockets +// @ID stream-chat-events-via-websockets +// @Security CoderSessionToken +// @Tags Chats +// @Produce json +// @Param chat path string true "Chat ID" format(uuid) +// @Success 200 {object} codersdk.ChatStreamEvent +// @Router /experimental/chats/{chat}/stream [get] +// @Description Experimental: this endpoint is subject to change. func (api *API) streamChat(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() chat := httpmw.ChatParam(r) @@ -3237,6 +3367,16 @@ func (api *API) streamChat(rw http.ResponseWriter, r *http.Request) { } // EXPERIMENTAL: this endpoint is experimental and is subject to change. +// +// @Summary Interrupt chat +// @ID interrupt-chat +// @Security CoderSessionToken +// @Tags Chats +// @Param chat path string true "Chat ID" format(uuid) +// @Produce json +// @Success 200 {object} codersdk.Chat +// @Router /experimental/chats/{chat}/interrupt [post] +// @Description Experimental: this endpoint is subject to change. func (api *API) interruptChat(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() chat := httpmw.ChatParam(r) @@ -3270,6 +3410,16 @@ func (api *API) interruptChat(rw http.ResponseWriter, r *http.Request) { // EXPERIMENTAL: this endpoint is experimental and is subject to change. // +// @Summary Regenerate chat title +// @ID regenerate-chat-title +// @Security CoderSessionToken +// @Tags Chats +// @Produce json +// @Param chat path string true "Chat ID" format(uuid) +// @Success 200 {object} codersdk.Chat +// @Router /experimental/chats/{chat}/title/regenerate [post] +// @Description Experimental: this endpoint is subject to change. +// //nolint:revive // HTTP handler writes to ResponseWriter. func (api *API) regenerateChatTitle(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() @@ -3356,6 +3506,16 @@ func (api *API) proposeChatTitle(rw http.ResponseWriter, r *http.Request) { // EXPERIMENTAL: this endpoint is experimental and is subject to change. // +// @Summary Get chat diff contents +// @ID get-chat-diff-contents +// @Security CoderSessionToken +// @Tags Chats +// @Produce json +// @Param chat path string true "Chat ID" format(uuid) +// @Success 200 {object} codersdk.ChatDiffContents +// @Router /experimental/chats/{chat}/diff [get] +// @Description Experimental: this endpoint is subject to change. +// //nolint:revive // HTTP handler writes to ResponseWriter. func (api *API) getChatDiffContents(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() @@ -5509,6 +5669,18 @@ func (api *API) deleteUserChatCompactionThreshold(rw http.ResponseWriter, r *htt rw.WriteHeader(http.StatusNoContent) } +// EXPERIMENTAL: this endpoint is experimental and is subject to change. +// +// @Summary Upload chat file +// @ID upload-chat-file +// @Security CoderSessionToken +// @Tags Chats +// @Accept image/png,image/jpeg,image/gif,image/webp,text/plain,text/markdown,text/csv,application/json,application/pdf +// @Produce json +// @Param organization query string true "Organization ID" format(uuid) +// @Success 201 {object} codersdk.UploadChatFileResponse +// @Router /experimental/chats/files [post] +// @Description Experimental: this endpoint is subject to change. func (api *API) postChatFile(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() apiKey := httpmw.APIKey(r) @@ -5637,6 +5809,17 @@ func (api *API) postChatFile(rw http.ResponseWriter, r *http.Request) { }) } +// EXPERIMENTAL: this endpoint is experimental and is subject to change. +// +// @Summary Get chat file +// @ID get-chat-file +// @Security CoderSessionToken +// @Tags Chats +// @Produce image/png,image/jpeg,image/gif,image/webp,text/plain,text/markdown,text/csv,application/json,application/pdf +// @Param file path string true "File ID" format(uuid) +// @Success 200 +// @Router /experimental/chats/files/{file} [get] +// @Description Experimental: this endpoint is subject to change. func (api *API) chatFileByID(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() diff --git a/codersdk/chats.go b/codersdk/chats.go index cc372f72fd..5169f467f6 100644 --- a/codersdk/chats.go +++ b/codersdk/chats.go @@ -124,7 +124,7 @@ type Chat struct { HasUnread bool `json:"has_unread"` // LastInjectedContext holds the most recently persisted // injected context parts (AGENTS.md files and skills). It - // is updated only when context changes — first workspace + // is updated only when context changes, on first workspace // attach or agent change. LastInjectedContext []ChatMessagePart `json:"last_injected_context,omitempty"` Warnings []string `json:"warnings,omitempty"` diff --git a/docs/ai-coder/agents/chats-api.md b/docs/ai-coder/agents/chats-api.md deleted file mode 100644 index d85a395b33..0000000000 --- a/docs/ai-coder/agents/chats-api.md +++ /dev/null @@ -1,406 +0,0 @@ -# Chats API - -> [!NOTE] -> The Chats API is in beta. -> Endpoints live under `/api/experimental/chats` and may change without notice. - -The Chats API lets you create and interact with Coder Agents -programmatically. You can start a chat, send follow-up messages, and stream -the agent's response — all without using the Coder dashboard. - -## Authentication - -All endpoints require a valid session token: - -```sh -curl -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \ - https://coder.example.com/api/experimental/chats -``` - -## Quick start - -Create a chat with a single text prompt: - -```sh -curl -X POST https://coder.example.com/api/experimental/chats \ - -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "organization_id": "", - "content": [ - {"type": "text", "text": "hello world"} - ] - }' -``` - -The response is the newly created `Chat` object: - -```json -{ - "id": "a1b2c3d4-...", - "organization_id": "...", - "owner_id": "...", - "workspace_id": null, - "build_id": null, - "agent_id": null, - "parent_chat_id": null, - "root_chat_id": null, - "last_model_config_id": "...", - "title": "hello world", - "status": "waiting", - "diff_status": null, - "created_at": "2025-07-17T00:00:00Z", - "updated_at": "2025-07-17T00:00:00Z", - "archived": false, - "pin_order": 0, - "mcp_server_ids": [], - "labels": {}, - "has_unread": false, - "client_type": "api" -} -``` - -If a chat later ends in error, the same `Chat` shape includes a structured -`last_error` object. For brevity, unchanged nullable IDs are omitted here: - -```json -{ - "id": "a1b2c3d4-...", - "title": "hello world", - "status": "error", - "last_error": { - "message": "Azure OpenAI is rate limiting requests.", - "kind": "rate_limit", - "provider": "azure", - "retryable": true, - "status_code": 429, - "detail": "Retry after 30 seconds." - }, - "created_at": "2025-07-17T00:00:00Z", - "updated_at": "2025-07-17T00:00:30Z", - "archived": false, - "pin_order": 0, - "mcp_server_ids": [], - "labels": {}, - "has_unread": false, - "client_type": "api" -} -``` - -The agent begins processing the prompt asynchronously. Use the -[stream endpoint](#stream-updates) to follow its progress. - -## Core workflow - -A typical integration follows three steps: - -1. **Create a chat** — `POST /api/experimental/chats` with your prompt. -2. **Stream updates** — Open a WebSocket to - `GET /api/experimental/chats/{chat}/stream` to receive real-time events - as the agent works. -3. **Send follow-ups** — `POST /api/experimental/chats/{chat}/messages` to - add messages to the conversation. Messages are queued if the agent is - busy. - -## Endpoints - -### Create a chat - -`POST /api/experimental/chats` - -| Field | Type | Required | Description | -|-------------------|---------------------|----------|-------------------------------------------------| -| `content` | `ChatInputPart[]` | yes | The user's prompt as one or more content parts. | -| `organization_id` | `uuid` | yes | The organization this chat belongs to. | -| `workspace_id` | `uuid` | no | Pin the chat to a specific workspace. | -| `model_config_id` | `uuid` | no | Override the default model configuration. | -| `mcp_server_ids` | `uuid[]` | no | Attach MCP servers to this chat. | -| `labels` | `map[string]string` | no | Key-value labels for the chat (max 50). | -| `client_type` | `string` | no | `"ui"` or `"api"`. Defaults to `"api"`. | - -Each `ChatInputPart` has a `type` field. The simplest form is a text part: - -```json -{"type": "text", "text": "Fix the failing tests in the auth service"} -``` - -Other part types include `file` (an uploaded image referenced by its -`file_id`) and `file-reference` (a pointer to a file with optional line -range). - -**Response**: `201 Created` with a `Chat` object. - -### Send a message - -`POST /api/experimental/chats/{chat}/messages` - -| Field | Type | Required | Description | -|-------------------|-------------------|----------|-------------------------------------| -| `content` | `ChatInputPart[]` | yes | The follow-up message content. | -| `model_config_id` | `uuid` | no | Override the model for this turn. | -| `mcp_server_ids` | `uuid[]` | no | Override MCP servers for this turn. | - -If the agent is currently processing, the message is queued automatically. -The response indicates whether the message was delivered immediately or -queued: - -```json -{ - "queued": false, - "message": { "id": 42, "chat_id": "...", "role": "user", "created_at": "...", "content": [...] } -} -``` - -When `queued` is `true`, `message` is absent and `queued_message` is -returned instead. - -### Edit a message - -`PATCH /api/experimental/chats/{chat}/messages/{message}` - -Edits a previously sent user message. The agent re-processes from the -edited message onward, truncating any messages that followed it. - -| Field | Type | Required | Description | -|-----------|-------------------|----------|----------------------------------| -| `content` | `ChatInputPart[]` | yes | The replacement message content. | - -The response is an `EditChatMessageResponse` with the edited `message` -and an optional `warnings` array. When file references in the edited -content cannot be linked (e.g. the per-chat file cap is reached), the -edit still succeeds and the `warnings` array describes which files -were not linked. - -### Stream updates - -`GET /api/experimental/chats/{chat}/stream` - -Opens a **one-way WebSocket** connection. The server sends events; clients -must not write to the socket (doing so closes the connection). - -| Query parameter | Type | Required | Description | -|-----------------|---------|----------|-------------------------------------------| -| `after_id` | `int64` | no | Only return events after this message ID. | - -Each WebSocket message is a JSON envelope with an outer `type` -(`"ping"`, `"data"`, or `"error"`) and an optional `data` field. For -`"data"` envelopes the payload is a **JSON array** of event objects: - -```json -{ - "type": "data", - "data": [ - {"type": "status", "chat_id": "...", "status": {"status": "running"}}, - {"type": "message_part", "chat_id": "...", "message_part": {"...":"..."}} - ] -} -``` - -Ignore `"ping"` envelopes (keepalives sent every ~15 s). On first -connect the server sends an initial snapshot of the chat state before -switching to live events. Use `after_id` when reconnecting to skip -messages the client already has. - -Connecting to the stream also updates the caller's read cursor for -unread tracking. On disconnect the cursor is advanced to the latest -message. - -Event types inside each batch: - -| Type | Description | -|----------------|--------------------------------------------------------------| -| `message_part` | A chunk of the agent's response (text, tool call, etc.). | -| `message` | A complete message has been persisted. | -| `status` | The chat status changed (e.g. `running`, `waiting`). | -| `error` | An error occurred during processing. | -| `retry` | The server is retrying a failed LLM call (includes backoff). | -| `queue_update` | The queued message list changed. | - -### Watch all chats - -`GET /api/experimental/chats/watch` - -Opens a **one-way WebSocket** that pushes events for all chats owned by -the authenticated user. Use this to drive a sidebar or notification -indicator without polling. - -Each event is a JSON object with `kind` and `chat` fields: - -| Kind | Description | -|----------------------|--------------------------------------| -| `created` | A new chat was created. | -| `status_change` | A chat's status changed. | -| `title_change` | A chat's title was updated. | -| `diff_status_change` | A chat's diff/PR status changed. | -| `action_required` | A chat is waiting for a tool result. | -| `deleted` | A chat was deleted. | - -### List chats - -`GET /api/experimental/chats` - -Returns all chats owned by the authenticated user. The `files` field is -populated on `POST /chats` and `GET /chats/{id}`. Other endpoints that -return a `Chat` object omit it. - -| Query parameter | Type | Required | Description | -|-----------------|----------|----------|------------------------------------------------------------------| -| `q` | `string` | no | Search query string. | -| `label` | `string` | no | Filter by label as `key:value`. Repeat for multiple (AND logic). | - -### Get a chat - -`GET /api/experimental/chats/{chat}` - -Returns the `Chat` object (metadata only, no messages). The response -includes a `files` field (`ChatFileMetadata[]`) containing metadata for -files that have been successfully linked to the chat. File linking is -best-effort; if linking fails, the file remains in message content but -will be absent from this field. - -When file linking is skipped (e.g. the per-chat file cap is reached), -`POST /chats` includes a `warnings` array on the `Chat` response and -`POST /chats/{chat}/messages` includes a `warnings` array on the -`CreateChatMessageResponse`. The `warnings` field is `omitempty` and -absent when all files are linked successfully. - -### Get chat messages - -`GET /api/experimental/chats/{chat}/messages` - -Returns messages for a chat in descending ID order (newest first). - -| Query parameter | Type | Required | Description | -|-----------------|---------|----------|---------------------------------------------| -| `before_id` | `int64` | no | Only return messages with `id < before_id`. | -| `after_id` | `int64` | no | Only return messages with `id > after_id`. | -| `limit` | `int32` | no | Page size, 1 to 200. Defaults to 50. | - -Results are returned in descending ID order (newest first), except when -only `after_id` is set: that shape is intended for polling and returns -ASCENDING ID order so a client can advance its cursor to the largest -returned ID without gaps. When both cursors are set they must satisfy -`after_id < before_id`; otherwise the server returns `400 Bad Request`. - -`queued_messages` is only populated on the initial load (no -cursor). Pass either cursor to page through history or to poll -for new messages without receiving the queued snapshot on every -request. The `has_more` flag indicates more rows exist beyond -this page in the same direction. - -### List models - -`GET /api/experimental/chats/models` - -Returns available models. Use this to discover valid values for -`model_config_id`. - -### Update a chat - -`PATCH /api/experimental/chats/{chat}` - -Updates chat metadata. All fields are optional; omitted fields are left -unchanged. - -| Field | Type | Description | -|-------------|---------------------|-------------------------------------------------------------------------------------| -| `title` | `string` | Set a new title. | -| `archived` | `bool` | `true` to archive, `false` to unarchive. Archiving clears `pin_order`. | -| `pin_order` | `int32` | `0` to unpin; `>0` on an unpinned chat to pin it; `>0` on a pinned chat to reorder. | -| `labels` | `map[string]string` | Replace all labels. Use `null`/omit to leave unchanged, `{}` to clear. | - -**Response**: `204 No Content`. - -### Regenerate title - -`POST /api/experimental/chats/{chat}/title/regenerate` - -Regenerates the chat title using conversation context. Returns the -updated `Chat` object. - -### Interrupt - -`POST /api/experimental/chats/{chat}/interrupt` - -Stops the agent's current processing loop and returns the chat to -`waiting` status. - -### Manage queued messages - -When a message is queued because the agent is busy, you can manage the -queue: - -`DELETE /api/experimental/chats/{chat}/queue/{queuedMessage}` - -Removes a queued message before it is processed. - -`POST /api/experimental/chats/{chat}/queue/{queuedMessage}/promote` - -Promotes a queued message to be processed next. - -### Get diff contents - -`GET /api/experimental/chats/{chat}/diff` - -Returns the current diff/PR status for a chat, including additions, -deletions, changed files, and pull request metadata when available. - -## File uploads - -Attach images to a chat by uploading them first: - -```sh -curl -X POST "https://coder.example.com/api/experimental/chats/files?organization=$ORG_ID" \ - -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \ - -H "Content-Type: image/png" \ - --data-binary @screenshot.png -``` - -The response contains an `id` you can reference as `file_id` in a -`ChatInputPart` with `"type": "file"`. To retrieve a previously uploaded -file, use `GET /api/experimental/chats/files/{file}`. - -Supported formats: PNG, JPEG, GIF, WebP (up to 10 MB). The server -validates actual file content regardless of the declared `Content-Type`. - -Files referenced in messages are automatically linked to the chat and -appear in the `files` field on subsequent -`GET /api/experimental/chats/{chat}` responses. - -## Chat statuses - -| Status | Meaning | -|-------------------|------------------------------------------------------------------------------| -| `waiting` | Idle. Newly created, finished successfully, or interrupted. | -| `pending` | Queued for processing. | -| `running` | Agent is actively working. | -| `error` | Agent encountered an error. | -| `requires_action` | Agent invoked a client-provided tool and needs the result before continuing. | - -## Configuration - -Deployment-wide chat settings are read and written under -`/api/experimental/chats/config/*`. Reading config requires authentication; writing requires -deployment-admin privileges. - -### Auto-archive window - -Chats whose newest non-deleted message is older than -`auto_archive_days` are automatically archived by a background job. -Pinned chats and chats belonging to a still-active thread are -exempt. `0` disables the feature, which is the default. - -```sh -# Read -curl -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \ - https://coder.example.com/api/experimental/chats/config/auto-archive-days -# { "auto_archive_days": 0 } - -# Update -curl -X PUT -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"auto_archive_days": 60}' \ - https://coder.example.com/api/experimental/chats/config/auto-archive-days -``` - -Accepted range: `0` to `3650` (~10 years). diff --git a/docs/ai-coder/agents/getting-started.md b/docs/ai-coder/agents/getting-started.md index e797b83883..1e27844c78 100644 --- a/docs/ai-coder/agents/getting-started.md +++ b/docs/ai-coder/agents/getting-started.md @@ -236,7 +236,7 @@ multiplier, not a replacement for developer judgment. ### Use the API for programmatic automation -The [Chats API](./chats-api.md) enables programmatic access to Coder Agents. +The [Chats API](../../reference/api/chats.md) enables programmatic access to Coder Agents. This is useful for building automations such as: - Triggering Coder Agents from CI/CD pipelines when builds fail. @@ -270,7 +270,7 @@ narrowly scoped. > [!NOTE] > The Chats API is in beta and may change without notice. -> See [Chats API](./chats-api.md) for the full endpoint reference. +> See [Chats API](../../reference/api/chats.md) for the full endpoint reference. ### Add workspace context with AGENTS.md @@ -322,4 +322,4 @@ Your input directly influences product direction during Beta. - [Template Optimization](./platform-controls/template-optimization.md) — create agent-friendly templates with network boundaries and scoped credentials. -- [Chats API](./chats-api.md) — build programmatic integrations. +- [Chats API](../../reference/api/chats.md): build programmatic integrations. diff --git a/docs/ai-coder/best-practices.md b/docs/ai-coder/best-practices.md index 8cfebeda81..5208c9c342 100644 --- a/docs/ai-coder/best-practices.md +++ b/docs/ai-coder/best-practices.md @@ -13,7 +13,7 @@ Below are common scenarios where AI coding agents provide the most impact, along | **Automating actions in the IDE** | Supplement tedious development with agents | Small refactors, generating unit tests, writing inline documentation, code search and navigation | [IDE Agents](./ide-agents.md) in Workspaces | | **Developer-led investigation and setup** | Developers delegate research and initial implementation to AI, then take over in their preferred IDE to complete the work | Bug triage and analysis, exploring technical approaches, understanding legacy code, creating starter implementations | [Coder Agents](./agents/index.md), to a full IDE with [Workspaces](../user-guides/workspace-access/index.md) | | **Prototyping & Business Applications** | User-friendly interface for engineers and non-technical users to build and prototype within new or existing codebases | Creating dashboards, building simple web apps, data analysis workflows, proof-of-concept development | [Coder Agents](./agents/index.md) | -| **Full background jobs & long-running agents** | Agents that run independently without user interaction for extended periods of time | Automated code reviews, scheduled data processing, continuous integration tasks, monitoring and alerting | [Coder Agents API](./agents/chats-api.md) | +| **Full background jobs & long-running agents** | Agents that run independently without user interaction for extended periods of time | Automated code reviews, scheduled data processing, continuous integration tasks, monitoring and alerting | [Coder Agents API](../reference/api/chats.md) | | **External agents and chat clients** | External AI agents and chat clients that need access to Coder workspaces for development environments and code sandboxing | ChatGPT, Claude Desktop, custom enterprise agents running tests, performing development tasks, code analysis | [MCP Server](./mcp-server.md) | ## Provide Agents with Proper Context diff --git a/docs/manifest.json b/docs/manifest.json index d6c13411df..67f17b0ad9 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1063,12 +1063,6 @@ "path": "./ai-coder/agents/extending-agents.md", "state": ["beta"] }, - { - "title": "Chats API", - "description": "Programmatic access to Coder Agents via the Chats API", - "path": "./ai-coder/agents/chats-api.md", - "state": ["beta"] - }, { "title": "Tasks to Chats API Migration", "description": "Guide for migrating from the Tasks API to the Chats API", @@ -1300,6 +1294,12 @@ "title": "Create a GitHub to Coder Tasks Workflow", "description": "How to setup Coder Tasks to run in GitHub", "path": "./ai-coder/github-to-tasks.md" + }, + { + "title": "Tasks to Chats API Migration", + "description": "Guide for migrating from the Tasks API to the Chats API", + "path": "./ai-coder/agents/tasks-to-chats-migration.md", + "state": ["beta"] } ] } @@ -1502,7 +1502,8 @@ }, { "title": "Chats", - "path": "./reference/api/chats.md" + "path": "./reference/api/chats.md", + "state": ["early access"] }, { "title": "Debug", diff --git a/docs/reference/api/chats.md b/docs/reference/api/chats.md index 026b4a31ff..ffdab13336 100644 --- a/docs/reference/api/chats.md +++ b/docs/reference/api/chats.md @@ -1 +1,2733 @@ # Chats + +## List chats + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/experimental/chats \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /experimental/chats` + +Experimental: this endpoint is subject to change. + +### Parameters + +| Name | In | Type | Required | Description | +|---------|-------|--------|----------|----------------------------------------------------------------| +| `q` | query | string | false | Search query | +| `label` | query | string | false | Filter by label as key:value. Repeat for multiple (AND logic). | + +### Example responses + +> 200 Response + +```json +[ + { + "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", + "archived": true, + "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", + "children": [ + {} + ], + "client_type": "ui", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" + } +] +``` + +### Responses + +| Status | Meaning | Description | Schema | +|--------|---------------------------------------------------------|-------------|---------------------------------------------------| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Chat](schemas.md#codersdkchat) | + +

Response Schema

+ +Status Code **200** + +| Name | Type | Required | Restrictions | Description | +|-----------------------------------|------------------------------------------------------------------------|----------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `[array item]` | array | false | | | +| `» agent_id` | string(uuid) | false | | | +| `» archived` | boolean | false | | | +| `» build_id` | string(uuid) | false | | | +| `» children` | [codersdk.Chat](schemas.md#codersdkchat) | 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](schemas.md#codersdkchatclienttype) | false | | | +| `» created_at` | string(date-time) | false | | | +| `» diff_status` | [codersdk.ChatDiffStatus](schemas.md#codersdkchatdiffstatus) | false | | | +| `»» additions` | integer | false | | | +| `»» approved` | boolean | false | | | +| `»» author_avatar_url` | string | false | | | +| `»» author_login` | string | false | | | +| `»» base_branch` | string | false | | | +| `»» changed_files` | integer | false | | | +| `»» changes_requested` | boolean | false | | | +| `»» chat_id` | string(uuid) | false | | | +| `»» commits` | integer | false | | | +| `»» deletions` | integer | false | | | +| `»» head_branch` | string | false | | | +| `»» pr_number` | integer | false | | | +| `»» pull_request_draft` | boolean | false | | | +| `»» pull_request_state` | string | false | | | +| `»» pull_request_title` | string | false | | | +| `»» refreshed_at` | string(date-time) | false | | | +| `»» reviewer_count` | integer | false | | | +| `»» stale_at` | string(date-time) | false | | | +| `»» url` | string | false | | | +| `» files` | array | false | | | +| `»» created_at` | string(date-time) | false | | | +| `»» id` | string(uuid) | false | | | +| `»» mime_type` | string | false | | | +| `»» name` | string | false | | | +| `»» organization_id` | string(uuid) | false | | | +| `»» owner_id` | string(uuid) | false | | | +| `» has_unread` | boolean | false | | Has unread is true when assistant messages exist beyond the owner's read cursor, which updates on stream connect and disconnect. | +| `» id` | string(uuid) | false | | | +| `» labels` | object | false | | | +| `»» [any property]` | string | false | | | +| `» last_error` | [codersdk.ChatError](schemas.md#codersdkchaterror) | false | | | +| `»» detail` | string | false | | Detail is optional provider-specific context shown alongside the normalized error message when available. | +| `»» kind` | string | 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_injected_context` | array | false | | Last injected context holds the most recently persisted injected context parts (AGENTS.md files and skills). It is updated only when context changes, on first workspace attach or agent change. | +| `»» args` | array | false | | | +| `»» args_delta` | string | false | | | +| `»» content` | string | false | | The code content from the diff that was commented on. | +| `»» context_file_agent_id` | [uuid.NullUUID](schemas.md#uuidnulluuid) | 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. | +| `»»» uuid` | string | false | | | +| `»»» valid` | boolean | false | | Valid is true if UUID is not NULL | +| `»» 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 records when this part was produced. Present on tool-call and tool-result parts so the frontend can compute tool execution duration. | +| `»» data` | array | false | | | +| `»» end_line` | integer | false | | | +| `»» file_id` | [uuid.NullUUID](schemas.md#uuidnulluuid) | false | | | +| `»»» uuid` | string | false | | | +| `»»» valid` | boolean | false | | Valid is true if UUID is not NULL | +| `»» file_name` | string | false | | | +| `»» is_error` | boolean | false | | | +| `»» is_media` | boolean | false | | | +| `»» mcp_server_config_id` | [uuid.NullUUID](schemas.md#uuidnulluuid) | false | | | +| `»»» uuid` | string | false | | | +| `»»» valid` | boolean | false | | Valid is true if UUID is not NULL | +| `»» media_type` | string | false | | | +| `»» name` | string | false | | | +| `»» provider_executed` | boolean | false | | Provider executed indicates the tool call was executed by the provider (e.g. Anthropic computer use). | +| `»» provider_metadata` | array | false | | Provider metadata holds provider-specific response metadata (e.g. Anthropic cache control hints) as raw JSON. Internal only: stripped by db2sdk before API responses. | +| `»» result` | array | false | | | +| `»» result_delta` | string | false | | | +| `»» signature` | string | 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](schemas.md#codersdkchatmessageparttype) | false | | | +| `»» url` | string | false | | | +| `» last_model_config_id` | string(uuid) | false | | | +| `» mcp_server_ids` | array | false | | | +| `» organization_id` | string(uuid) | false | | | +| `» owner_id` | string(uuid) | false | | | +| `» parent_chat_id` | string(uuid) | false | | | +| `» pin_order` | integer | false | | | +| `» plan_mode` | [codersdk.ChatPlanMode](schemas.md#codersdkchatplanmode) | false | | | +| `» root_chat_id` | string(uuid) | false | | | +| `» status` | [codersdk.ChatStatus](schemas.md#codersdkchatstatus) | false | | | +| `» title` | string | false | | | +| `» updated_at` | string(date-time) | false | | | +| `» warnings` | array | false | | | +| `» workspace_id` | string(uuid) | false | | | + +#### Enumerated Values + +| Property | Value(s) | +|---------------|--------------------------------------------------------------------------------------------------------------| +| `client_type` | `api`, `ui` | +| `type` | `context-file`, `file`, `file-reference`, `reasoning`, `skill`, `source`, `text`, `tool-call`, `tool-result` | +| `plan_mode` | `plan` | +| `status` | `completed`, `error`, `paused`, `pending`, `requires_action`, `running`, `waiting` | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Create chat + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/experimental/chats \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`POST /experimental/chats` + +Experimental: this endpoint is subject to change. + +> Body parameter + +```json +{ + "client_type": "ui", + "content": [ + { + "content": "string", + "end_line": 0, + "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767", + "file_name": "string", + "start_line": 0, + "text": "string", + "type": "text" + } + ], + "labels": { + "property1": "string", + "property2": "string" + }, + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "plan_mode": "plan", + "system_prompt": "string", + "unsafe_dynamic_tools": [ + { + "description": "string", + "input_schema": [ + 0 + ], + "name": "string" + } + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +|--------|------|--------------------------------------------------------------------|----------|---------------------| +| `body` | body | [codersdk.CreateChatRequest](schemas.md#codersdkcreatechatrequest) | true | Create chat request | + +### Example responses + +> 201 Response + +```json +{ + "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", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" + } + ], + "client_type": "ui", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +|--------|--------------------------------------------------------------|-------------|------------------------------------------| +| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.Chat](schemas.md#codersdkchat) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Upload chat file + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/experimental/chats/files?organization=497f6eca-6276-4993-bfeb-53cbbbba6f08 \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`POST /experimental/chats/files` + +Experimental: this endpoint is subject to change. + +### Parameters + +| Name | In | Type | Required | Description | +|----------------|-------|--------------|----------|-----------------| +| `organization` | query | string(uuid) | true | Organization ID | + +### Example responses + +> 201 Response + +```json +{ + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +|--------|--------------------------------------------------------------|-------------|------------------------------------------------------------------------------| +| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.UploadChatFileResponse](schemas.md#codersdkuploadchatfileresponse) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get chat file + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/experimental/chats/files/{file} \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /experimental/chats/files/{file}` + +Experimental: this endpoint is subject to change. + +### Parameters + +| Name | In | Type | Required | Description | +|--------|------|--------------|----------|-------------| +| `file` | path | string(uuid) | true | File ID | + +### Responses + +| Status | Meaning | Description | Schema | +|--------|---------------------------------------------------------|-------------|--------| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## List chat models + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/experimental/chats/models \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /experimental/chats/models` + +Experimental: this endpoint is subject to change. + +### Example responses + +> 200 Response + +```json +{ + "providers": [ + { + "available": true, + "models": [ + { + "display_name": "string", + "id": "string", + "model": "string", + "provider": "string" + } + ], + "provider": "string", + "unavailable_reason": "missing_api_key" + } + ] +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +|--------|---------------------------------------------------------|-------------|----------------------------------------------------------------------| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.ChatModelsResponse](schemas.md#codersdkchatmodelsresponse) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Watch chat events for a user via WebSockets + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/experimental/chats/watch \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /experimental/chats/watch` + +Experimental: this endpoint is subject to change. + +### Example responses + +> 200 Response + +```json +{ + "chat": { + "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", + "archived": true, + "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", + "children": [ + {} + ], + "client_type": "ui", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" + }, + "kind": "status_change", + "tool_calls": [ + { + "args": "string", + "tool_call_id": "string", + "tool_name": "string" + } + ] +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +|--------|---------------------------------------------------------|-------------|--------------------------------------------------------------| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.ChatWatchEvent](schemas.md#codersdkchatwatchevent) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get chat by ID + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/experimental/chats/{chat} \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /experimental/chats/{chat}` + +Experimental: this endpoint is subject to change. + +### Parameters + +| Name | In | Type | Required | Description | +|--------|------|--------------|----------|-------------| +| `chat` | path | string(uuid) | true | Chat ID | + +### Example responses + +> 200 Response + +```json +{ + "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", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" + } + ], + "client_type": "ui", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +|--------|---------------------------------------------------------|-------------|------------------------------------------| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Chat](schemas.md#codersdkchat) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Update chat + +### Code samples + +```shell +# Example request using curl +curl -X PATCH http://coder-server:8080/experimental/chats/{chat} \ + -H 'Content-Type: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`PATCH /experimental/chats/{chat}` + +Experimental: this endpoint is subject to change. + +> Body parameter + +```json +{ + "archived": true, + "labels": { + "property1": "string", + "property2": "string" + }, + "pin_order": 0, + "plan_mode": "plan", + "title": "string", + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +|--------|------|--------------------------------------------------------------------|----------|---------------------| +| `chat` | path | string(uuid) | true | Chat ID | +| `body` | body | [codersdk.UpdateChatRequest](schemas.md#codersdkupdatechatrequest) | true | Update chat request | + +### Responses + +| Status | Meaning | Description | Schema | +|--------|-----------------------------------------------------------------|-------------|--------| +| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get chat diff contents + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/experimental/chats/{chat}/diff \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /experimental/chats/{chat}/diff` + +Experimental: this endpoint is subject to change. + +### Parameters + +| Name | In | Type | Required | Description | +|--------|------|--------------|----------|-------------| +| `chat` | path | string(uuid) | true | Chat ID | + +### Example responses + +> 200 Response + +```json +{ + "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](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.ChatDiffContents](schemas.md#codersdkchatdiffcontents) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Interrupt chat + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/experimental/chats/{chat}/interrupt \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`POST /experimental/chats/{chat}/interrupt` + +Experimental: this endpoint is subject to change. + +### Parameters + +| Name | In | Type | Required | Description | +|--------|------|--------------|----------|-------------| +| `chat` | path | string(uuid) | true | Chat ID | + +### Example responses + +> 200 Response + +```json +{ + "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", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" + } + ], + "client_type": "ui", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +|--------|---------------------------------------------------------|-------------|------------------------------------------| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Chat](schemas.md#codersdkchat) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## List chat messages + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/experimental/chats/{chat}/messages \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /experimental/chats/{chat}/messages` + +Experimental: this endpoint is subject to change. + +### Parameters + +| Name | In | Type | Required | Description | +|-------------|-------|--------------|----------|--------------------------------------| +| `chat` | path | string(uuid) | true | Chat ID | +| `before_id` | query | integer | false | Return messages with id < before_id | +| `after_id` | query | integer | false | Return messages with id > after_id | +| `limit` | query | integer | false | Page size, 1 to 200. Defaults to 50. | + +### Example responses + +> 200 Response + +```json +{ + "has_more": true, + "messages": [ + { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "role": "system", + "usage": { + "cache_creation_tokens": 0, + "cache_read_tokens": 0, + "context_limit": 0, + "input_tokens": 0, + "output_tokens": 0, + "reasoning_tokens": 0, + "total_tokens": 0 + } + } + ], + "queued_messages": [ + { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205" + } + ] +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +|--------|---------------------------------------------------------|-------------|--------------------------------------------------------------------------| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.ChatMessagesResponse](schemas.md#codersdkchatmessagesresponse) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Send chat message + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/experimental/chats/{chat}/messages \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`POST /experimental/chats/{chat}/messages` + +Experimental: this endpoint is subject to change. + +> Body parameter + +```json +{ + "busy_behavior": "queue", + "content": [ + { + "content": "string", + "end_line": 0, + "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767", + "file_name": "string", + "start_line": 0, + "text": "string", + "type": "text" + } + ], + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "plan_mode": "plan" +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +|--------|------|----------------------------------------------------------------------------------|----------|-----------------------------| +| `chat` | path | string(uuid) | true | Chat ID | +| `body` | body | [codersdk.CreateChatMessageRequest](schemas.md#codersdkcreatechatmessagerequest) | true | Create chat message request | + +### Example responses + +> 200 Response + +```json +{ + "message": { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "role": "system", + "usage": { + "cache_creation_tokens": 0, + "cache_read_tokens": 0, + "context_limit": 0, + "input_tokens": 0, + "output_tokens": 0, + "reasoning_tokens": 0, + "total_tokens": 0 + } + }, + "queued": true, + "queued_message": { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205" + }, + "warnings": [ + "string" + ] +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +|--------|---------------------------------------------------------|-------------|------------------------------------------------------------------------------------| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.CreateChatMessageResponse](schemas.md#codersdkcreatechatmessageresponse) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Edit chat message + +### Code samples + +```shell +# Example request using curl +curl -X PATCH http://coder-server:8080/experimental/chats/{chat}/messages/{message} \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`PATCH /experimental/chats/{chat}/messages/{message}` + +Experimental: this endpoint is subject to change. + +> Body parameter + +```json +{ + "content": [ + { + "content": "string", + "end_line": 0, + "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767", + "file_name": "string", + "start_line": 0, + "text": "string", + "type": "text" + } + ] +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +|-----------|------|------------------------------------------------------------------------------|----------|---------------------------| +| `chat` | path | string(uuid) | true | Chat ID | +| `message` | path | integer | true | Message ID | +| `body` | body | [codersdk.EditChatMessageRequest](schemas.md#codersdkeditchatmessagerequest) | true | Edit chat message request | + +### Example responses + +> 200 Response + +```json +{ + "message": { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "role": "system", + "usage": { + "cache_creation_tokens": 0, + "cache_read_tokens": 0, + "context_limit": 0, + "input_tokens": 0, + "output_tokens": 0, + "reasoning_tokens": 0, + "total_tokens": 0 + } + }, + "warnings": [ + "string" + ] +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +|--------|---------------------------------------------------------|-------------|--------------------------------------------------------------------------------| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.EditChatMessageResponse](schemas.md#codersdkeditchatmessageresponse) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Stream chat events via WebSockets + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/experimental/chats/{chat}/stream \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /experimental/chats/{chat}/stream` + +Experimental: this endpoint is subject to change. + +### Parameters + +| Name | In | Type | Required | Description | +|--------|------|--------------|----------|-------------| +| `chat` | path | string(uuid) | true | Chat ID | + +### Example responses + +> 200 Response + +```json +{ + "action_required": { + "tool_calls": [ + { + "args": "string", + "tool_call_id": "string", + "tool_name": "string" + } + ] + }, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "message": { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "role": "system", + "usage": { + "cache_creation_tokens": 0, + "cache_read_tokens": 0, + "context_limit": 0, + "input_tokens": 0, + "output_tokens": 0, + "reasoning_tokens": 0, + "total_tokens": 0 + } + }, + "message_part": { + "part": { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + }, + "role": "system" + }, + "queued_messages": [ + { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205" + } + ], + "retry": { + "attempt": 0, + "delay_ms": 0, + "error": "string", + "kind": "string", + "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](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.ChatStreamEvent](schemas.md#codersdkchatstreamevent) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Connect to chat workspace desktop via WebSockets + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/experimental/chats/{chat}/stream/desktop \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /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](https://tools.ietf.org/html/rfc7231#section-6.2.2) | Switching Protocols | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Watch chat workspace git state via WebSockets + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/experimental/chats/{chat}/stream/git \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /experimental/chats/{chat}/stream/git` + +Experimental: this endpoint is subject to change. + +### Parameters + +| Name | In | Type | Required | Description | +|--------|------|--------------|----------|-------------| +| `chat` | path | string(uuid) | true | Chat ID | + +### Example responses + +> 200 Response + +```json +{ + "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](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.WorkspaceAgentGitServerMessage](schemas.md#codersdkworkspaceagentgitservermessage) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Regenerate chat title + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/experimental/chats/{chat}/title/regenerate \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`POST /experimental/chats/{chat}/title/regenerate` + +Experimental: this endpoint is subject to change. + +### Parameters + +| Name | In | Type | Required | Description | +|--------|------|--------------|----------|-------------| +| `chat` | path | string(uuid) | true | Chat ID | + +### Example responses + +> 200 Response + +```json +{ + "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", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" + } + ], + "client_type": "ui", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +|--------|---------------------------------------------------------|-------------|------------------------------------------| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Chat](schemas.md#codersdkchat) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). diff --git a/docs/reference/api/schemas.md b/docs/reference/api/schemas.md index 2f6c6f4a91..3fdf9e8311 100644 --- a/docs/reference/api/schemas.md +++ b/docs/reference/api/schemas.md @@ -2079,6 +2079,326 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | `one_time_passcode` | string | true | | | | `password` | string | true | | | +## codersdk.Chat + +```json +{ + "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", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" + } + ], + "client_type": "ui", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|-------------------------|-----------------------------------------------------------------|----------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `agent_id` | string | false | | | +| `archived` | boolean | false | | | +| `build_id` | string | false | | | +| `children` | array of [codersdk.Chat](#codersdkchat) | 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](#codersdkchatclienttype) | false | | | +| `created_at` | string | false | | | +| `diff_status` | [codersdk.ChatDiffStatus](#codersdkchatdiffstatus) | false | | | +| `files` | array of [codersdk.ChatFileMetadata](#codersdkchatfilemetadata) | false | | | +| `has_unread` | boolean | false | | Has unread is true when assistant messages exist beyond the owner's read cursor, which updates on stream connect and disconnect. | +| `id` | string | false | | | +| `labels` | object | false | | | +| » `[any property]` | string | false | | | +| `last_error` | [codersdk.ChatError](#codersdkchaterror) | false | | | +| `last_injected_context` | array of [codersdk.ChatMessagePart](#codersdkchatmessagepart) | false | | Last injected context holds the most recently persisted injected context parts (AGENTS.md files and skills). It is updated only when context changes, on first workspace attach or agent change. | +| `last_model_config_id` | string | false | | | +| `mcp_server_ids` | array of string | false | | | +| `organization_id` | string | false | | | +| `owner_id` | string | false | | | +| `parent_chat_id` | string | false | | | +| `pin_order` | integer | false | | | +| `plan_mode` | [codersdk.ChatPlanMode](#codersdkchatplanmode) | false | | | +| `root_chat_id` | string | false | | | +| `status` | [codersdk.ChatStatus](#codersdkchatstatus) | false | | | +| `title` | string | false | | | +| `updated_at` | string | false | | | +| `warnings` | array of string | false | | | +| `workspace_id` | string | false | | | + +## codersdk.ChatBusyBehavior + +```json +"queue" +``` + +### Properties + +#### Enumerated Values + +| Value(s) | +|----------------------| +| `interrupt`, `queue` | + +## codersdk.ChatClientType + +```json +"ui" +``` + +### Properties + +#### Enumerated Values + +| Value(s) | +|-------------| +| `api`, `ui` | + ## codersdk.ChatConfig ```json @@ -2095,6 +2415,753 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | `acquire_batch_size` | integer | false | | | | `debug_logging_enabled` | boolean | false | | | +## codersdk.ChatDiffContents + +```json +{ + "branch": "string", + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "diff": "string", + "provider": "string", + "pull_request_url": "string", + "remote_origin": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|--------------------|--------|----------|--------------|-------------| +| `branch` | string | false | | | +| `chat_id` | string | false | | | +| `diff` | string | false | | | +| `provider` | string | false | | | +| `pull_request_url` | string | false | | | +| `remote_origin` | string | false | | | + +## codersdk.ChatDiffStatus + +```json +{ + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|----------------------|---------|----------|--------------|-------------| +| `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 | false | | | +| `commits` | integer | false | | | +| `deletions` | integer | false | | | +| `head_branch` | string | false | | | +| `pr_number` | integer | false | | | +| `pull_request_draft` | boolean | false | | | +| `pull_request_state` | string | false | | | +| `pull_request_title` | string | false | | | +| `refreshed_at` | string | false | | | +| `reviewer_count` | integer | false | | | +| `stale_at` | string | false | | | +| `url` | string | false | | | + +## codersdk.ChatError + +```json +{ + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|---------------|---------|----------|--------------|-----------------------------------------------------------------------------------------------------------| +| `detail` | string | false | | Detail is optional provider-specific context shown alongside the normalized error message when available. | +| `kind` | string | 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. | + +## codersdk.ChatFileMetadata + +```json +{ + "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" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|-------------------|--------|----------|--------------|-------------| +| `created_at` | string | false | | | +| `id` | string | false | | | +| `mime_type` | string | false | | | +| `name` | string | false | | | +| `organization_id` | string | false | | | +| `owner_id` | string | false | | | + +## codersdk.ChatInputPart + +```json +{ + "content": "string", + "end_line": 0, + "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767", + "file_name": "string", + "start_line": 0, + "text": "string", + "type": "text" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|--------------|----------------------------------------------------------|----------|--------------|--------------------------------------------------------------------------------| +| `content` | string | false | | The code content from the diff that was commented on. | +| `end_line` | integer | false | | | +| `file_id` | string | false | | | +| `file_name` | string | false | | The following fields are only set when Type is ChatInputPartTypeFileReference. | +| `start_line` | integer | false | | | +| `text` | string | false | | | +| `type` | [codersdk.ChatInputPartType](#codersdkchatinputparttype) | false | | | + +## codersdk.ChatInputPartType + +```json +"text" +``` + +### Properties + +#### Enumerated Values + +| Value(s) | +|----------------------------------| +| `file`, `file-reference`, `text` | + +## codersdk.ChatMessage + +```json +{ + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "role": "system", + "usage": { + "cache_creation_tokens": 0, + "cache_read_tokens": 0, + "context_limit": 0, + "input_tokens": 0, + "output_tokens": 0, + "reasoning_tokens": 0, + "total_tokens": 0 + } +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|-------------------|---------------------------------------------------------------|----------|--------------|-------------| +| `chat_id` | string | false | | | +| `content` | array of [codersdk.ChatMessagePart](#codersdkchatmessagepart) | false | | | +| `created_at` | string | false | | | +| `created_by` | string | false | | | +| `id` | integer | false | | | +| `model_config_id` | string | false | | | +| `role` | [codersdk.ChatMessageRole](#codersdkchatmessagerole) | false | | | +| `usage` | [codersdk.ChatMessageUsage](#codersdkchatmessageusage) | false | | | + +## codersdk.ChatMessagePart + +```json +{ + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|--------------------------------|--------------------------------------------------------------|----------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `args` | array of integer | false | | | +| `args_delta` | string | false | | | +| `content` | string | false | | The code content from the diff that was commented on. | +| `context_file_agent_id` | [uuid.NullUUID](#uuidnulluuid) | 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 | false | | Created at records when this part was produced. Present on tool-call and tool-result parts so the frontend can compute tool execution duration. | +| `data` | array of integer | false | | | +| `end_line` | integer | false | | | +| `file_id` | [uuid.NullUUID](#uuidnulluuid) | false | | | +| `file_name` | string | false | | | +| `is_error` | boolean | false | | | +| `is_media` | boolean | false | | | +| `mcp_server_config_id` | [uuid.NullUUID](#uuidnulluuid) | false | | | +| `media_type` | string | false | | | +| `name` | string | false | | | +| `provider_executed` | boolean | false | | Provider executed indicates the tool call was executed by the provider (e.g. Anthropic computer use). | +| `provider_metadata` | array of integer | false | | Provider metadata holds provider-specific response metadata (e.g. Anthropic cache control hints) as raw JSON. Internal only: stripped by db2sdk before API responses. | +| `result` | array of integer | false | | | +| `result_delta` | string | false | | | +| `signature` | string | 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](#codersdkchatmessageparttype) | false | | | +| `url` | string | false | | | + +## codersdk.ChatMessagePartType + +```json +"text" +``` + +### Properties + +#### Enumerated Values + +| Value(s) | +|--------------------------------------------------------------------------------------------------------------| +| `context-file`, `file`, `file-reference`, `reasoning`, `skill`, `source`, `text`, `tool-call`, `tool-result` | + +## codersdk.ChatMessageRole + +```json +"system" +``` + +### Properties + +#### Enumerated Values + +| Value(s) | +|---------------------------------------| +| `assistant`, `system`, `tool`, `user` | + +## codersdk.ChatMessageUsage + +```json +{ + "cache_creation_tokens": 0, + "cache_read_tokens": 0, + "context_limit": 0, + "input_tokens": 0, + "output_tokens": 0, + "reasoning_tokens": 0, + "total_tokens": 0 +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|-------------------------|---------|----------|--------------|-------------| +| `cache_creation_tokens` | integer | false | | | +| `cache_read_tokens` | integer | false | | | +| `context_limit` | integer | false | | | +| `input_tokens` | integer | false | | | +| `output_tokens` | integer | false | | | +| `reasoning_tokens` | integer | false | | | +| `total_tokens` | integer | false | | | + +## codersdk.ChatMessagesResponse + +```json +{ + "has_more": true, + "messages": [ + { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "role": "system", + "usage": { + "cache_creation_tokens": 0, + "cache_read_tokens": 0, + "context_limit": 0, + "input_tokens": 0, + "output_tokens": 0, + "reasoning_tokens": 0, + "total_tokens": 0 + } + } + ], + "queued_messages": [ + { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205" + } + ] +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|-------------------|-------------------------------------------------------------------|----------|--------------|-------------| +| `has_more` | boolean | false | | | +| `messages` | array of [codersdk.ChatMessage](#codersdkchatmessage) | false | | | +| `queued_messages` | array of [codersdk.ChatQueuedMessage](#codersdkchatqueuedmessage) | false | | | + +## codersdk.ChatModel + +```json +{ + "display_name": "string", + "id": "string", + "model": "string", + "provider": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|----------------|--------|----------|--------------|-------------| +| `display_name` | string | false | | | +| `id` | string | false | | | +| `model` | string | false | | | +| `provider` | string | false | | | + +## codersdk.ChatModelProvider + +```json +{ + "available": true, + "models": [ + { + "display_name": "string", + "id": "string", + "model": "string", + "provider": "string" + } + ], + "provider": "string", + "unavailable_reason": "missing_api_key" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|----------------------|--------------------------------------------------------------------------------------------|----------|--------------|-------------| +| `available` | boolean | false | | | +| `models` | array of [codersdk.ChatModel](#codersdkchatmodel) | false | | | +| `provider` | string | false | | | +| `unavailable_reason` | [codersdk.ChatModelProviderUnavailableReason](#codersdkchatmodelproviderunavailablereason) | false | | | + +## codersdk.ChatModelProviderUnavailableReason + +```json +"missing_api_key" +``` + +### Properties + +#### Enumerated Values + +| Value(s) | +|------------------------------------------------------------| +| `fetch_failed`, `missing_api_key`, `user_api_key_required` | + +## codersdk.ChatModelsResponse + +```json +{ + "providers": [ + { + "available": true, + "models": [ + { + "display_name": "string", + "id": "string", + "model": "string", + "provider": "string" + } + ], + "provider": "string", + "unavailable_reason": "missing_api_key" + } + ] +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|-------------|-------------------------------------------------------------------|----------|--------------|-------------| +| `providers` | array of [codersdk.ChatModelProvider](#codersdkchatmodelprovider) | false | | | + +## codersdk.ChatPlanMode + +```json +"plan" +``` + +### Properties + +#### Enumerated Values + +| Value(s) | +|----------| +| `plan` | + +## codersdk.ChatQueuedMessage + +```json +{ + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|-------------------|---------------------------------------------------------------|----------|--------------|-------------| +| `chat_id` | string | false | | | +| `content` | array of [codersdk.ChatMessagePart](#codersdkchatmessagepart) | false | | | +| `created_at` | string | false | | | +| `id` | integer | false | | | +| `model_config_id` | string | false | | | + ## codersdk.ChatRetentionDaysResponse ```json @@ -2109,6 +3176,597 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in |------------------|---------|----------|--------------|-------------| | `retention_days` | integer | false | | | +## codersdk.ChatStatus + +```json +"waiting" +``` + +### Properties + +#### Enumerated Values + +| Value(s) | +|------------------------------------------------------------------------------------| +| `completed`, `error`, `paused`, `pending`, `requires_action`, `running`, `waiting` | + +## codersdk.ChatStreamActionRequired + +```json +{ + "tool_calls": [ + { + "args": "string", + "tool_call_id": "string", + "tool_name": "string" + } + ] +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|--------------|---------------------------------------------------------------------|----------|--------------|-------------| +| `tool_calls` | array of [codersdk.ChatStreamToolCall](#codersdkchatstreamtoolcall) | false | | | + +## codersdk.ChatStreamEvent + +```json +{ + "action_required": { + "tool_calls": [ + { + "args": "string", + "tool_call_id": "string", + "tool_name": "string" + } + ] + }, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "message": { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "role": "system", + "usage": { + "cache_creation_tokens": 0, + "cache_read_tokens": 0, + "context_limit": 0, + "input_tokens": 0, + "output_tokens": 0, + "reasoning_tokens": 0, + "total_tokens": 0 + } + }, + "message_part": { + "part": { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + }, + "role": "system" + }, + "queued_messages": [ + { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205" + } + ], + "retry": { + "attempt": 0, + "delay_ms": 0, + "error": "string", + "kind": "string", + "provider": "string", + "retrying_at": "2019-08-24T14:15:22Z", + "status_code": 0 + }, + "status": { + "status": "waiting" + }, + "type": "message_part" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|-------------------|------------------------------------------------------------------------|----------|--------------|-------------| +| `action_required` | [codersdk.ChatStreamActionRequired](#codersdkchatstreamactionrequired) | false | | | +| `chat_id` | string | false | | | +| `error` | [codersdk.ChatError](#codersdkchaterror) | false | | | +| `message` | [codersdk.ChatMessage](#codersdkchatmessage) | false | | | +| `message_part` | [codersdk.ChatStreamMessagePart](#codersdkchatstreammessagepart) | false | | | +| `queued_messages` | array of [codersdk.ChatQueuedMessage](#codersdkchatqueuedmessage) | false | | | +| `retry` | [codersdk.ChatStreamRetry](#codersdkchatstreamretry) | false | | | +| `status` | [codersdk.ChatStreamStatus](#codersdkchatstreamstatus) | false | | | +| `type` | [codersdk.ChatStreamEventType](#codersdkchatstreameventtype) | false | | | + +## codersdk.ChatStreamEventType + +```json +"message_part" +``` + +### Properties + +#### Enumerated Values + +| Value(s) | +|------------------------------------------------------------------------------------------| +| `action_required`, `error`, `message`, `message_part`, `queue_update`, `retry`, `status` | + +## codersdk.ChatStreamMessagePart + +```json +{ + "part": { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + }, + "role": "system" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|--------|------------------------------------------------------|----------|--------------|-------------| +| `part` | [codersdk.ChatMessagePart](#codersdkchatmessagepart) | false | | | +| `role` | [codersdk.ChatMessageRole](#codersdkchatmessagerole) | false | | | + +## codersdk.ChatStreamRetry + +```json +{ + "attempt": 0, + "delay_ms": 0, + "error": "string", + "kind": "string", + "provider": "string", + "retrying_at": "2019-08-24T14:15:22Z", + "status_code": 0 +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|---------------|---------|----------|--------------|-------------------------------------------------------------------| +| `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` | string | false | | Kind classifies the retry reason for consistent client rendering. | +| `provider` | string | false | | Provider identifies the upstream model provider when known. | +| `retrying_at` | string | 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. | + +## codersdk.ChatStreamStatus + +```json +{ + "status": "waiting" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|----------|--------------------------------------------|----------|--------------|-------------| +| `status` | [codersdk.ChatStatus](#codersdkchatstatus) | false | | | + +## codersdk.ChatStreamToolCall + +```json +{ + "args": "string", + "tool_call_id": "string", + "tool_name": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|----------------|--------|----------|--------------|-------------| +| `args` | string | false | | | +| `tool_call_id` | string | false | | | +| `tool_name` | string | false | | | + +## codersdk.ChatWatchEvent + +```json +{ + "chat": { + "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", + "archived": true, + "build_id": "bfb1f3fa-bf7b-43a5-9e0b-26cc050e44cb", + "children": [ + {} + ], + "client_type": "ui", + "created_at": "2019-08-24T14:15:22Z", + "diff_status": { + "additions": 0, + "approved": true, + "author_avatar_url": "string", + "author_login": "string", + "base_branch": "string", + "changed_files": 0, + "changes_requested": true, + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "commits": 0, + "deletions": 0, + "head_branch": "string", + "pr_number": 0, + "pull_request_draft": true, + "pull_request_state": "string", + "pull_request_title": "string", + "refreshed_at": "2019-08-24T14:15:22Z", + "reviewer_count": 0, + "stale_at": "2019-08-24T14:15:22Z", + "url": "string" + }, + "files": [ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "mime_type": "string", + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05" + } + ], + "has_unread": true, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "labels": { + "property1": "string", + "property2": "string" + }, + "last_error": { + "detail": "string", + "kind": "string", + "message": "string", + "provider": "string", + "retryable": true, + "status_code": 0 + }, + "last_injected_context": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "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" + } + ], + "last_model_config_id": "30ebb95f-c255-4759-9429-89aa4ec1554c", + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "parent_chat_id": "c3609ee6-3b11-4a93-b9ae-e4fabcc99359", + "pin_order": 0, + "plan_mode": "plan", + "root_chat_id": "2898031c-fdce-4e3e-8c53-4481dd42fcd7", + "status": "waiting", + "title": "string", + "updated_at": "2019-08-24T14:15:22Z", + "warnings": [ + "string" + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" + }, + "kind": "status_change", + "tool_calls": [ + { + "args": "string", + "tool_call_id": "string", + "tool_name": "string" + } + ] +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|--------------|---------------------------------------------------------------------|----------|--------------|-------------| +| `chat` | [codersdk.Chat](#codersdkchat) | false | | | +| `kind` | [codersdk.ChatWatchEventKind](#codersdkchatwatcheventkind) | false | | | +| `tool_calls` | array of [codersdk.ChatStreamToolCall](#codersdkchatstreamtoolcall) | false | | | + +## codersdk.ChatWatchEventKind + +```json +"status_change" +``` + +### Properties + +#### Enumerated Values + +| Value(s) | +|------------------------------------------------------------------------------------------------| +| `action_required`, `created`, `deleted`, `diff_status_change`, `status_change`, `title_change` | + ## codersdk.ConnectionLatency ```json @@ -2366,6 +4024,259 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | `password` | string | true | | | | `to_type` | [codersdk.LoginType](#codersdklogintype) | true | | To type is the login type to convert to. | +## codersdk.CreateChatMessageRequest + +```json +{ + "busy_behavior": "queue", + "content": [ + { + "content": "string", + "end_line": 0, + "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767", + "file_name": "string", + "start_line": 0, + "text": "string", + "type": "text" + } + ], + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "plan_mode": "plan" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|-------------------|-----------------------------------------------------------|----------|--------------|--------------------------------------------------------------------------------------------------------------| +| `busy_behavior` | [codersdk.ChatBusyBehavior](#codersdkchatbusybehavior) | false | | | +| `content` | array of [codersdk.ChatInputPart](#codersdkchatinputpart) | false | | | +| `mcp_server_ids` | array of string | false | | | +| `model_config_id` | string | false | | | +| `plan_mode` | [codersdk.ChatPlanMode](#codersdkchatplanmode) | false | | Plan mode switches the chat's persistent plan mode. nil: no change, ptr to "plan": enable, ptr to "": clear. | + +#### Enumerated Values + +| Property | Value(s) | +|-----------------|----------------------| +| `busy_behavior` | `interrupt`, `queue` | + +## codersdk.CreateChatMessageResponse + +```json +{ + "message": { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "role": "system", + "usage": { + "cache_creation_tokens": 0, + "cache_read_tokens": 0, + "context_limit": 0, + "input_tokens": 0, + "output_tokens": 0, + "reasoning_tokens": 0, + "total_tokens": 0 + } + }, + "queued": true, + "queued_message": { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205" + }, + "warnings": [ + "string" + ] +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|------------------|----------------------------------------------------------|----------|--------------|-------------| +| `message` | [codersdk.ChatMessage](#codersdkchatmessage) | false | | | +| `queued` | boolean | false | | | +| `queued_message` | [codersdk.ChatQueuedMessage](#codersdkchatqueuedmessage) | false | | | +| `warnings` | array of string | false | | | + +## codersdk.CreateChatRequest + +```json +{ + "client_type": "ui", + "content": [ + { + "content": "string", + "end_line": 0, + "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767", + "file_name": "string", + "start_line": 0, + "text": "string", + "type": "text" + } + ], + "labels": { + "property1": "string", + "property2": "string" + }, + "mcp_server_ids": [ + "497f6eca-6276-4993-bfeb-53cbbbba6f08" + ], + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "plan_mode": "plan", + "system_prompt": "string", + "unsafe_dynamic_tools": [ + { + "description": "string", + "input_schema": [ + 0 + ], + "name": "string" + } + ], + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|------------------------|-----------------------------------------------------------|----------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| `client_type` | [codersdk.ChatClientType](#codersdkchatclienttype) | false | | | +| `content` | array of [codersdk.ChatInputPart](#codersdkchatinputpart) | false | | | +| `labels` | object | false | | | +| » `[any property]` | string | false | | | +| `mcp_server_ids` | array of string | false | | | +| `model_config_id` | string | false | | | +| `organization_id` | string | false | | | +| `plan_mode` | [codersdk.ChatPlanMode](#codersdkchatplanmode) | false | | | +| `system_prompt` | string | false | | | +| `unsafe_dynamic_tools` | array of [codersdk.DynamicTool](#codersdkdynamictool) | false | | Unsafe dynamic tools declares client-executed tools that the LLM can invoke. This API is highly experimental and highly subject to change. | +| `workspace_id` | string | false | | | + ## codersdk.CreateFirstUserOnboardingInfo ```json @@ -4578,6 +6489,141 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `parameters` | array of [codersdk.PreviewParameter](#codersdkpreviewparameter) | false | | | | `secret_requirements` | array of [codersdk.SecretRequirementStatus](#codersdksecretrequirementstatus) | false | | | +## codersdk.DynamicTool + +```json +{ + "description": "string", + "input_schema": [ + 0 + ], + "name": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|----------------|------------------|----------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `description` | string | false | | | +| `input_schema` | array of integer | false | | Input schema JSON key "input_schema" uses snake_case for SDK consistency, deviating from the camelCase "inputSchema" convention used by MCP. | +| `name` | string | false | | | + +## codersdk.EditChatMessageRequest + +```json +{ + "content": [ + { + "content": "string", + "end_line": 0, + "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767", + "file_name": "string", + "start_line": 0, + "text": "string", + "type": "text" + } + ] +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|-----------|-----------------------------------------------------------|----------|--------------|-------------| +| `content` | array of [codersdk.ChatInputPart](#codersdkchatinputpart) | false | | | + +## codersdk.EditChatMessageResponse + +```json +{ + "message": { + "chat_id": "efc9fe20-a1e5-4a8c-9c48-f1b30c1e4f86", + "content": [ + { + "args": [ + 0 + ], + "args_delta": "string", + "content": "string", + "context_file_agent_id": { + "uuid": "string", + "valid": true + }, + "context_file_content": "string", + "context_file_directory": "string", + "context_file_os": "string", + "context_file_path": "string", + "context_file_skill_meta_file": "string", + "context_file_truncated": true, + "created_at": "2019-08-24T14:15:22Z", + "data": [ + 0 + ], + "end_line": 0, + "file_id": { + "uuid": "string", + "valid": true + }, + "file_name": "string", + "is_error": true, + "is_media": true, + "mcp_server_config_id": { + "uuid": "string", + "valid": true + }, + "media_type": "string", + "name": "string", + "provider_executed": true, + "provider_metadata": [ + 0 + ], + "result": [ + 0 + ], + "result_delta": "string", + "signature": "string", + "skill_description": "string", + "skill_dir": "string", + "skill_name": "string", + "source_id": "string", + "start_line": 0, + "text": "string", + "title": "string", + "tool_call_id": "string", + "tool_name": "string", + "type": "text", + "url": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", + "id": 0, + "model_config_id": "f5fb4d91-62ca-4377-9ee6-5d43ba00d205", + "role": "system", + "usage": { + "cache_creation_tokens": 0, + "cache_read_tokens": 0, + "context_limit": 0, + "input_tokens": 0, + "output_tokens": 0, + "reasoning_tokens": 0, + "total_tokens": 0 + } + }, + "warnings": [ + "string" + ] +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|------------|----------------------------------------------|----------|--------------|-------------| +| `message` | [codersdk.ChatMessage](#codersdkchatmessage) | false | | | +| `warnings` | array of string | false | | | + ## codersdk.Entitlement ```json @@ -10488,6 +12534,34 @@ Restarts will only happen on weekdays in this list on weeks which line up with W | `logo_url` | string | false | | | | `service_banner` | [codersdk.BannerConfig](#codersdkbannerconfig) | false | | Deprecated: ServiceBanner has been replaced by AnnouncementBanners. | +## codersdk.UpdateChatRequest + +```json +{ + "archived": true, + "labels": { + "property1": "string", + "property2": "string" + }, + "pin_order": 0, + "plan_mode": "plan", + "title": "string", + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|--------------------|------------------------------------------------|----------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `archived` | boolean | false | | | +| `labels` | object | false | | | +| » `[any property]` | string | false | | | +| `pin_order` | integer | false | | Pin order controls the chat's pinned state and position. - nil: no change to pin state. - 0: unpin the chat. - >0 (chat is unpinned): pin the chat, appending it to the end of the pinned list. The specific value is ignored; the server assigns the next available position. - >0 (chat is already pinned): move the chat to the requested position, shifting neighbors as needed. The value is clamped to [1, pinned_count]. | +| `plan_mode` | [codersdk.ChatPlanMode](#codersdkchatplanmode) | false | | Plan mode switches the chat's persistent plan mode. nil: no change, ptr to "plan": enable, ptr to "": clear. | +| `title` | string | false | | | +| `workspace_id` | string | false | | | + ## codersdk.UpdateChatRetentionDaysRequest ```json @@ -10911,6 +12985,20 @@ If the schedule is empty, the user will be updated to use the default schedule.| |----------|---------|----------|--------------|-------------| | `ttl_ms` | integer | false | | | +## codersdk.UploadChatFileResponse + +```json +{ + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|------|--------|----------|--------------|-------------| +| `id` | string | false | | | + ## codersdk.UploadResponse ```json @@ -12185,6 +14273,48 @@ If the schedule is empty, the user will be updated to use the default schedule.| |-------------------------------------------------------------------| | `deleting`, `error`, `running`, `starting`, `stopped`, `stopping` | +## codersdk.WorkspaceAgentGitServerMessage + +```json +{ + "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" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|----------------|--------------------------------------------------------------------------------------------|----------|--------------|-------------| +| `message` | string | false | | | +| `repositories` | array of [codersdk.WorkspaceAgentRepoChanges](#codersdkworkspaceagentrepochanges) | false | | | +| `scanned_at` | string | false | | | +| `type` | [codersdk.WorkspaceAgentGitServerMessageType](#codersdkworkspaceagentgitservermessagetype) | false | | | + +## codersdk.WorkspaceAgentGitServerMessageType + +```json +"changes" +``` + +### Properties + +#### Enumerated Values + +| Value(s) | +|--------------------| +| `changes`, `error` | + ## codersdk.WorkspaceAgentHealth ```json @@ -12464,6 +14594,28 @@ If the schedule is empty, the user will be updated to use the default schedule.| |----------|-------------------------------------------------------------------------------|----------|--------------|-------------| | `shares` | array of [codersdk.WorkspaceAgentPortShare](#codersdkworkspaceagentportshare) | false | | | +## codersdk.WorkspaceAgentRepoChanges + +```json +{ + "branch": "string", + "remote_origin": "string", + "removed": true, + "repo_root": "string", + "unified_diff": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|-----------------|---------|----------|--------------|-------------| +| `branch` | string | false | | | +| `remote_origin` | string | false | | | +| `removed` | boolean | false | | | +| `repo_root` | string | false | | | +| `unified_diff` | string | false | | | + ## codersdk.WorkspaceAgentScript ```json diff --git a/scripts/apidocgen/postprocess/main.go b/scripts/apidocgen/postprocess/main.go index 3c0fc11fcc..d923c39860 100644 --- a/scripts/apidocgen/postprocess/main.go +++ b/scripts/apidocgen/postprocess/main.go @@ -209,12 +209,25 @@ func writeDocs(sections [][]byte) error { continue } + // Preserve existing state and description on children, keyed by + // title, so that callouts like `state: ["experimental"]` survive + // regeneration. Generated routes always overwrite Title and Path. + existingByTitle := make(map[string]route, len(child.Children)) + for _, existing := range child.Children { + existingByTitle[existing.Title] = existing + } + var children []route for _, mdf := range mdFiles { docRoute := route{ Title: mdf.title, Path: mdf.path, } + if existing, ok := existingByTitle[mdf.title]; ok { + docRoute.State = existing.State + docRoute.Description = existing.Description + docRoute.IconPath = existing.IconPath + } children = append(children, docRoute) } diff --git a/site/src/api/typesGenerated.ts b/site/src/api/typesGenerated.ts index 00f9617ab0..a4824cabdc 100644 --- a/site/src/api/typesGenerated.ts +++ b/site/src/api/typesGenerated.ts @@ -1304,7 +1304,7 @@ export interface Chat { /** * LastInjectedContext holds the most recently persisted * injected context parts (AGENTS.md files and skills). It - * is updated only when context changes — first workspace + * is updated only when context changes, on first workspace * attach or agent change. */ readonly last_injected_context?: readonly ChatMessagePart[];