Coder Tasks API
The Tasks API from Coder — 9 operation(s) for tasks.
OpenAPI Specification
openapi: 3.0.3
info:
description: Coderd is the service created by running coder server. It is a thin API that connects workspaces, provisioners and users. coderd stores its state in Postgres and is the only service that communicates with Postgres.
title: Coder Agents Tasks API
termsOfService: https://coder.com/legal/terms-of-service
contact:
name: API Support
url: https://coder.com
email: support@coder.com
license:
name: AGPL-3.0
url: https://github.com/coder/coder/blob/main/LICENSE
version: '2.0'
servers:
- url: https://{coderHost}/api/v2
description: Coder instance
variables:
coderHost:
default: coder.example.com
description: Your Coder deployment hostname
security:
- CoderSessionToken: []
tags:
- name: Tasks
paths:
/api/v2/tasks:
get:
operationId: list-ai-tasks
summary: List AI tasks
tags:
- Tasks
security:
- CoderSessionToken: []
parameters:
- name: q
in: query
required: false
description: 'Search query for filtering tasks. Supports: owner:<username/uuid/me>, organization:<org-name/uuid>, status:<status>'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.TasksListResponse'
/api/v2/tasks/{user}:
post:
operationId: create-a-new-ai-task
summary: Create a new AI task
tags:
- Tasks
security:
- CoderSessionToken: []
parameters:
- name: user
in: path
required: true
description: Username, user ID, or 'me' for the authenticated user
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.CreateTaskRequest'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Task'
/api/v2/tasks/{user}/{task}:
get:
operationId: get-ai-task-by-id-or-name
summary: Get AI task by ID or name
tags:
- Tasks
security:
- CoderSessionToken: []
parameters:
- name: user
in: path
required: true
description: Username, user ID, or 'me' for the authenticated user
schema:
type: string
- name: task
in: path
required: true
description: Task ID, or task name
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Task'
delete:
operationId: delete-ai-task
summary: Delete AI task
tags:
- Tasks
security:
- CoderSessionToken: []
parameters:
- name: user
in: path
required: true
description: Username, user ID, or 'me' for the authenticated user
schema:
type: string
- name: task
in: path
required: true
description: Task ID, or task name
schema:
type: string
responses:
'202':
description: Accepted
/api/v2/tasks/{user}/{task}/input:
patch:
operationId: update-ai-task-input
summary: Update AI task input
tags:
- Tasks
security:
- CoderSessionToken: []
parameters:
- name: user
in: path
required: true
description: Username, user ID, or 'me' for the authenticated user
schema:
type: string
- name: task
in: path
required: true
description: Task ID, or task name
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.UpdateTaskInputRequest'
responses:
'204':
description: No Content
/api/v2/tasks/{user}/{task}/logs:
get:
operationId: get-ai-task-logs
summary: Get AI task logs
tags:
- Tasks
security:
- CoderSessionToken: []
parameters:
- name: user
in: path
required: true
description: Username, user ID, or 'me' for the authenticated user
schema:
type: string
- name: task
in: path
required: true
description: Task ID, or task name
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.TaskLogsResponse'
/api/v2/tasks/{user}/{task}/pause:
post:
operationId: pause-task
summary: Pause task
tags:
- Tasks
security:
- CoderSessionToken: []
parameters:
- name: user
in: path
required: true
description: Username, user ID, or 'me' for the authenticated user
schema:
type: string
- name: task
in: path
required: true
description: Task ID
schema:
type: string
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.PauseTaskResponse'
/api/v2/tasks/{user}/{task}/resume:
post:
operationId: resume-task
summary: Resume task
tags:
- Tasks
security:
- CoderSessionToken: []
parameters:
- name: user
in: path
required: true
description: Username, user ID, or 'me' for the authenticated user
schema:
type: string
- name: task
in: path
required: true
description: Task ID
schema:
type: string
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.ResumeTaskResponse'
/api/v2/tasks/{user}/{task}/send:
post:
operationId: send-input-to-ai-task
summary: Send input to AI task
tags:
- Tasks
security:
- CoderSessionToken: []
parameters:
- name: user
in: path
required: true
description: Username, user ID, or 'me' for the authenticated user
schema:
type: string
- name: task
in: path
required: true
description: Task ID, or task name
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.TaskSendRequest'
responses:
'204':
description: No Content
/api/v2/workspaceagents/me/tasks/{task}/log-snapshot:
post:
operationId: upload-task-log-snapshot
summary: Upload task log snapshot
tags:
- Tasks
security:
- CoderSessionToken: []
parameters:
- name: task
in: path
required: true
description: Task ID
schema:
type: string
- name: format
in: query
required: true
description: Snapshot format
schema:
type: string
enum:
- agentapi
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'204':
description: No Content
components:
schemas:
codersdk.BuildReason:
type: string
enum:
- initiator
- autostart
- autostop
- dormancy
- dashboard
- cli
- ssh_connection
- vscode_connection
- jetbrains_connection
- task_auto_pause
- task_manual_pause
- task_resume
codersdk.AgentSubsystem:
type: string
enum:
- envbox
- envbuilder
- exectrace
codersdk.TaskState:
type: string
enum:
- working
- idle
- complete
- failed
codersdk.DisplayApp:
type: string
enum:
- vscode
- vscode_insiders
- web_terminal
- port_forwarding_helper
- ssh_helper
codersdk.WorkspaceAgentHealth:
type: object
properties:
healthy:
type: boolean
description: Healthy is true if the agent is healthy.
example: false
reason:
type: string
description: Reason is a human-readable explanation of the agent's health. It is empty if Healthy is true.
example: agent has lost connection
codersdk.WorkspaceBuild:
type: object
properties:
build_number:
type: integer
created_at:
type: string
format: date-time
daily_cost:
type: integer
deadline:
type: string
format: date-time
has_ai_task:
type: boolean
description: 'Deprecated: This field has been deprecated in favor of Task WorkspaceID.'
has_external_agent:
type: boolean
id:
type: string
format: uuid
initiator_id:
type: string
format: uuid
initiator_name:
type: string
job:
$ref: '#/components/schemas/codersdk.ProvisionerJob'
matched_provisioners:
$ref: '#/components/schemas/codersdk.MatchedProvisioners'
max_deadline:
type: string
format: date-time
reason:
enum:
- initiator
- autostart
- autostop
allOf:
- $ref: '#/components/schemas/codersdk.BuildReason'
resources:
type: array
items:
$ref: '#/components/schemas/codersdk.WorkspaceResource'
status:
enum:
- pending
- starting
- running
- stopping
- stopped
- failed
- canceling
- canceled
- deleting
- deleted
allOf:
- $ref: '#/components/schemas/codersdk.WorkspaceStatus'
template_version_id:
type: string
format: uuid
template_version_name:
type: string
template_version_preset_id:
type: string
format: uuid
transition:
enum:
- start
- stop
- delete
allOf:
- $ref: '#/components/schemas/codersdk.WorkspaceTransition'
updated_at:
type: string
format: date-time
workspace_id:
type: string
format: uuid
workspace_name:
type: string
workspace_owner_avatar_url:
type: string
workspace_owner_id:
type: string
format: uuid
workspace_owner_name:
type: string
description: WorkspaceOwnerName is the username of the owner of the workspace.
codersdk.PauseTaskResponse:
type: object
properties:
workspace_build:
$ref: '#/components/schemas/codersdk.WorkspaceBuild'
uuid.NullUUID:
type: object
properties:
uuid:
type: string
valid:
type: boolean
description: Valid is true if UUID is not NULL
codersdk.UpdateTaskInputRequest:
type: object
properties:
input:
type: string
codersdk.ProvisionerJobStatus:
type: string
enum:
- pending
- running
- succeeded
- canceling
- canceled
- failed
- unknown
codersdk.DERPRegion:
type: object
properties:
latency_ms:
type: number
preferred:
type: boolean
codersdk.TaskLogsResponse:
type: object
properties:
logs:
type: array
items:
$ref: '#/components/schemas/codersdk.TaskLogEntry'
snapshot:
type: boolean
snapshot_at:
type: string
codersdk.ResumeTaskResponse:
type: object
properties:
workspace_build:
$ref: '#/components/schemas/codersdk.WorkspaceBuild'
codersdk.WorkspaceAgentScriptStatus:
type: string
enum:
- ok
- exit_failure
- timed_out
- pipes_left_open
codersdk.ProvisionerJobType:
type: string
enum:
- template_version_import
- workspace_build
- template_version_dry_run
codersdk.WorkspaceAgentStartupScriptBehavior:
type: string
enum:
- blocking
- non-blocking
codersdk.WorkspaceApp:
type: object
properties:
command:
type: string
display_name:
type: string
description: DisplayName is a friendly name for the app.
external:
type: boolean
description: 'External specifies whether the URL should be opened externally on
the client or not.'
group:
type: string
health:
$ref: '#/components/schemas/codersdk.WorkspaceAppHealth'
healthcheck:
description: Healthcheck specifies the configuration for checking app health.
allOf:
- $ref: '#/components/schemas/codersdk.Healthcheck'
hidden:
type: boolean
icon:
type: string
description: 'Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard.'
id:
type: string
format: uuid
open_in:
$ref: '#/components/schemas/codersdk.WorkspaceAppOpenIn'
sharing_level:
enum:
- owner
- authenticated
- organization
- public
allOf:
- $ref: '#/components/schemas/codersdk.WorkspaceAppSharingLevel'
slug:
type: string
description: Slug is a unique identifier within the agent.
statuses:
type: array
description: Statuses is a list of statuses for the app.
items:
$ref: '#/components/schemas/codersdk.WorkspaceAppStatus'
subdomain:
type: boolean
description: 'Subdomain denotes whether the app should be accessed via a path on the
`coder server` or via a hostname-based dev URL. If this is set to true
and there is no app wildcard configured on the server, the app will not
be accessible in the UI.'
subdomain_name:
type: string
description: SubdomainName is the application domain exposed on the `coder server`.
tooltip:
type: string
description: 'Tooltip is an optional markdown supported field that is displayed
when hovering over workspace apps in the UI.'
url:
type: string
description: 'URL is the address being proxied to inside the workspace.
If external is specified, this will be opened on the client.'
codersdk.WorkspaceAgentLifecycle:
type: string
enum:
- created
- starting
- start_timeout
- start_error
- ready
- shutting_down
- shutdown_timeout
- shutdown_error
- 'off'
codersdk.WorkspaceAppStatusState:
type: string
enum:
- working
- idle
- complete
- failure
codersdk.WorkspaceAppStatus:
type: object
properties:
agent_id:
type: string
format: uuid
app_id:
type: string
format: uuid
created_at:
type: string
format: date-time
icon:
type: string
description: 'Deprecated: This field is unused and will be removed in a future version.
Icon is an external URL to an icon that will be rendered in the UI.'
id:
type: string
format: uuid
message:
type: string
needs_user_attention:
type: boolean
description: 'Deprecated: This field is unused and will be removed in a future version.
NeedsUserAttention specifies whether the status needs user attention.'
state:
$ref: '#/components/schemas/codersdk.WorkspaceAppStatusState'
uri:
type: string
description: 'URI is the URI of the resource that the status is for.
e.g. https://github.com/org/repo/pull/123
e.g. file:///path/to/file'
workspace_id:
type: string
format: uuid
codersdk.WorkspaceResource:
type: object
properties:
agents:
type: array
items:
$ref: '#/components/schemas/codersdk.WorkspaceAgent'
created_at:
type: string
format: date-time
daily_cost:
type: integer
hide:
type: boolean
icon:
type: string
id:
type: string
format: uuid
job_id:
type: string
format: uuid
metadata:
type: array
items:
$ref: '#/components/schemas/codersdk.WorkspaceResourceMetadata'
name:
type: string
type:
type: string
workspace_transition:
enum:
- start
- stop
- delete
allOf:
- $ref: '#/components/schemas/codersdk.WorkspaceTransition'
codersdk.WorkspaceStatus:
type: string
enum:
- pending
- starting
- running
- stopping
- stopped
- failed
- canceling
- canceled
- deleting
- deleted
codersdk.TaskSendRequest:
type: object
properties:
input:
type: string
codersdk.WorkspaceAgent:
type: object
properties:
api_version:
type: string
apps:
type: array
items:
$ref: '#/components/schemas/codersdk.WorkspaceApp'
architecture:
type: string
connection_timeout_seconds:
type: integer
created_at:
type: string
format: date-time
directory:
type: string
disconnected_at:
type: string
format: date-time
display_apps:
type: array
items:
$ref: '#/components/schemas/codersdk.DisplayApp'
environment_variables:
type: object
additionalProperties:
type: string
expanded_directory:
type: string
first_connected_at:
type: string
format: date-time
health:
description: Health reports the health of the agent.
allOf:
- $ref: '#/components/schemas/codersdk.WorkspaceAgentHealth'
id:
type: string
format: uuid
instance_id:
type: string
last_connected_at:
type: string
format: date-time
latency:
type: object
description: DERPLatency is mapped by region name (e.g. "New York City", "Seattle").
additionalProperties:
$ref: '#/components/schemas/codersdk.DERPRegion'
lifecycle_state:
$ref: '#/components/schemas/codersdk.WorkspaceAgentLifecycle'
log_sources:
type: array
items:
$ref: '#/components/schemas/codersdk.WorkspaceAgentLogSource'
logs_length:
type: integer
logs_overflowed:
type: boolean
name:
type: string
operating_system:
type: string
parent_id:
format: uuid
allOf:
- $ref: '#/components/schemas/uuid.NullUUID'
ready_at:
type: string
format: date-time
resource_id:
type: string
format: uuid
scripts:
type: array
items:
$ref: '#/components/schemas/codersdk.WorkspaceAgentScript'
started_at:
type: string
format: date-time
startup_script_behavior:
description: 'StartupScriptBehavior is a legacy field that is deprecated in favor
of the `coder_script` resource. It''s only referenced by old clients.
Deprecated: Remove in the future!'
allOf:
- $ref: '#/components/schemas/codersdk.WorkspaceAgentStartupScriptBehavior'
status:
$ref: '#/components/schemas/codersdk.WorkspaceAgentStatus'
subsystems:
type: array
items:
$ref: '#/components/schemas/codersdk.AgentSubsystem'
troubleshooting_url:
type: string
updated_at:
type: string
format: date-time
version:
type: string
codersdk.WorkspaceAppHealth:
type: string
enum:
- disabled
- initializing
- healthy
- unhealthy
codersdk.ProvisionerJob:
type: object
properties:
available_workers:
type: array
items:
type: string
format: uuid
canceled_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
created_at:
type: string
format: date-time
error:
type: string
error_code:
enum:
- REQUIRED_TEMPLATE_VARIABLES
- INSUFFICIENT_QUOTA
allOf:
- $ref: '#/components/schemas/codersdk.JobErrorCode'
file_id:
type: string
format: uuid
id:
type: string
format: uuid
initiator_id:
type: string
format: uuid
input:
$ref: '#/components/schemas/codersdk.ProvisionerJobInput'
logs_overflowed:
type: boolean
metadata:
$ref: '#/components/schemas/codersdk.ProvisionerJobMetadata'
organization_id:
type: string
format: uuid
queue_position:
type: integer
queue_size:
type: integer
started_at:
type: string
format: date-time
status:
enum:
- pending
- running
- succeeded
- canceling
- canceled
- failed
allOf:
- $ref: '#/components/schemas/codersdk.ProvisionerJobStatus'
tags:
type: object
additionalProperties:
type: string
type:
$ref: '#/components/schemas/codersdk.ProvisionerJobType'
worker_id:
type: string
format: uuid
worker_name:
type: string
codersdk.JobErrorCode:
type: string
enum:
- REQUIRED_TEMPLATE_VARIABLES
- INSUFFICIENT_QUOTA
codersdk.WorkspaceAgentScript:
type: object
properties:
cron:
type: string
display_name:
type: string
exit_code:
type: integer
id:
type: string
format: uuid
log_path:
type: string
log_source_id:
type: string
format: uuid
run_on_start:
type: boolean
run_on_stop:
type: boolean
script:
type: string
start_blocks_login:
type: boolean
status:
$ref: '#/components/schemas/codersdk.WorkspaceAgentScriptStatus'
timeout:
type: integer
codersdk.WorkspaceResourceMetadata:
type: object
properties:
key:
type: string
sensitive:
type: boolean
value:
type: string
codersdk.ProvisionerJobInput:
type: object
properties:
error:
type: string
template_version_id:
type: string
format: uuid
workspace_build_id:
type: string
format: uuid
codersdk.WorkspaceAgentStatus:
type: string
enum:
- connecting
- connected
- disconnected
- timeout
codersdk.WorkspaceAppSharingLevel:
type: string
enum:
- owner
- authenticated
- organization
- public
codersdk.TaskLogEntry:
type: object
properties:
content:
type: string
id:
type: integer
time:
type: string
format: date-time
type:
$ref: '#/components/schemas/codersdk.TaskLogType'
codersdk.WorkspaceAppOpenIn:
type: string
enum:
- slim-window
- tab
codersdk.ProvisionerJobMetadata:
type: object
properties:
template_display_name:
type: string
template_icon:
type: string
template_id:
type: string
format: uuid
template_name:
type: string
template_version_name:
type: string
workspace_build_transition:
$ref: '#/components/schemas/codersdk.WorkspaceTransition'
workspace_id:
type: string
format: uuid
workspace_name:
type: string
codersdk.WorkspaceAgentLogSource:
type: object
properties:
created_at:
type: string
format: date-time
display_name:
type: string
icon:
type: string
id:
type: string
format: uuid
workspace_agent_id:
type: string
format: uuid
codersdk.MatchedProvisioners:
type: object
properties:
available:
type: integer
description: 'Available is the number of provisioner daemons that are available to
take jobs. This may be less than the count if some provisioners are
busy or have been stopped.'
count:
type: integer
description: 'Count is the number of provisioner daemons that matched the given
tags. If the count is 0, it means no provisioner daemons matched the
requested tags.'
most_recently_seen:
type: string
format: date-time
description: 'MostRecentlySeen is the most recently seen time of the set of matched
provisioners. If no provisioners matched, this field will be null.'
codersdk.TaskLogType:
type: string
enum:
- input
- output
codersdk.Healthcheck:
type: object
properties:
interval:
type: integer
description: Interval specifies the seconds between each health check.
threshold:
type: integer
description: Threshold specifies the number of consecutive failed health checks before returning "unhealthy".
url:
type: string
description: URL specifies the endpoint to check for the app health.
codersdk.TasksListResponse:
type: object
properties:
count:
type: integer
tasks:
type: array
items:
$ref: '#/components/schemas/codersdk.Task'
codersdk.TaskStateEntry:
type: object
properties:
message:
type: string
state:
$ref: '#/components/schemas/codersdk.TaskState'
timestamp:
type: string
format: date-time
uri:
type: string
codersdk.Task:
type: object
properties:
created_at:
type: string
format: date-time
current_state:
$ref: '#/components/schemas/codersdk.TaskStateEntry'
display_name:
type: string
id:
type: string
format: uuid
initial_prompt:
type: string
name:
type: string
organization_id:
type: string
format: uuid
owner_avatar_url:
type: string
owner_id:
type: string
format: uuid
owner_name:
type: string
status:
enum:
- pending
- initializing
- active
- paused
- unknown
- error
allOf:
- $ref: '#/components/schemas/codersdk.TaskStatus'
template_display_name:
type: string
template_icon:
type: string
template_id:
type: string
format: uuid
template_name:
type: string
template_version_id:
type: string
format: uuid
updated_at:
type: string
format: date-time
workspace_agent_health:
$ref: '#/components/schemas/codersdk.WorkspaceAgentHealth'
workspace_agent_id:
format: uuid
allOf:
- $ref: '#/components/schemas/uuid.NullUUID'
workspace_agent_lifecycle:
$ref: '#/components/schemas/codersdk.WorkspaceAgentLifecycle'
workspace_app_id:
format: uuid
allOf:
- $ref: '#/components/schemas/uuid.NullUUID'
workspace_build_number:
type: integer
workspace_id:
format: uuid
allOf:
- $ref: '#/components/schemas/uuid.NullUUID'
workspace_name:
type: string
workspace_status:
enum:
- pending
- starting
- running
- stopping
- stopped
- failed
- canceling
- canceled
- deleting
- deleted
allOf:
- $ref: '#/components/schemas/codersdk.WorkspaceStatus'
codersdk.WorkspaceTransition:
type: string
enum:
- start
- stop
- delete
codersdk.TaskStatus:
type: string
enum:
- pending
- initializing
- active
- paused
- unknown
- error
codersdk.CreateTaskRequest:
type: object
properties:
display_name:
type: string
input:
type: string
name:
type: string
template_version_id:
type: string
format: uuid
template_version_preset_id:
type: string
format: uuid
securitySchemes:
CoderSessionToken:
type: apiKey
in: header
name: Coder-Session-Token
externalDocs: {}