Coder Workspaces API
The Workspaces API from Coder — 20 operation(s) for workspaces.
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 Workspaces 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: Workspaces
paths:
/api/experimental/watch-all-workspacebuilds:
get:
operationId: watch-all-workspace-builds
summary: Watch all workspace builds
tags:
- Workspaces
security:
- CoderSessionToken: []
responses:
'101':
description: Switching Protocols
/api/v2/organizations/{organization}/members/{user}/workspaces:
post:
operationId: create-user-workspace-by-organization
summary: Create user workspace by organization
tags:
- Workspaces
security:
- CoderSessionToken: []
description: 'Create a new workspace using a template. The request must
specify either the Template ID or the Template Version ID,
not both. If the Template ID is specified, the active version
of the template will be used.'
parameters:
- name: organization
in: path
required: true
description: Organization ID
schema:
type: string
- name: user
in: path
required: true
description: Username, UUID, or me
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.CreateWorkspaceRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Workspace'
/api/v2/organizations/{organization}/members/{user}/workspaces/available-users:
get:
operationId: get-users-available-for-workspace-creation
summary: Get users available for workspace creation
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: organization
in: path
required: true
description: Organization ID
schema:
type: string
- name: user
in: path
required: true
description: User ID, name, or me
schema:
type: string
- name: q
in: query
required: false
description: Search query
schema:
type: string
- name: limit
in: query
required: false
description: Limit results
schema:
type: integer
- name: offset
in: query
required: false
description: Offset for pagination
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/codersdk.MinimalUser'
/api/v2/users/{user}/workspace/{workspacename}:
get:
operationId: get-workspace-metadata-by-user-and-workspace-name
summary: Get workspace metadata by user and workspace name
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: user
in: path
required: true
description: User ID, name, or me
schema:
type: string
- name: workspacename
in: path
required: true
description: Workspace name
schema:
type: string
- name: include_deleted
in: query
required: false
description: Return data instead of HTTP 404 if the workspace is deleted
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Workspace'
/api/v2/users/{user}/workspaces:
post:
operationId: create-user-workspace
summary: Create user workspace
tags:
- Workspaces
security:
- CoderSessionToken: []
description: 'Create a new workspace using a template. The request must
specify either the Template ID or the Template Version ID,
not both. If the Template ID is specified, the active version
of the template will be used.'
parameters:
- name: user
in: path
required: true
description: Username, UUID, or me
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.CreateWorkspaceRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Workspace'
/api/v2/workspaces:
get:
operationId: list-workspaces
summary: List workspaces
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: q
in: query
required: false
description: 'Search query in the format `key:value`. Available keys are: owner, template, name, status, has-agent, dormant, last_used_after, last_used_before, has-ai-task, has_external_agent, healthy.'
schema:
type: string
- name: limit
in: query
required: false
description: Page limit
schema:
type: integer
- name: offset
in: query
required: false
description: Page offset
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.WorkspacesResponse'
/api/v2/workspaces/{workspace}:
get:
operationId: get-workspace-metadata-by-id
summary: Get workspace metadata by ID
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
- name: include_deleted
in: query
required: false
description: Return data instead of HTTP 404 if the workspace is deleted
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Workspace'
patch:
operationId: update-workspace-metadata-by-id
summary: Update workspace metadata by ID
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.UpdateWorkspaceRequest'
responses:
'204':
description: No Content
/api/v2/workspaces/{workspace}/acl:
get:
operationId: get-workspace-acls
summary: Get workspace ACLs
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.WorkspaceACL'
delete:
operationId: completely-clears-the-workspaces-user-and-group-acls
summary: Completely clears the workspace's user and group ACLs.
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
responses:
'204':
description: No Content
patch:
operationId: update-workspace-acl
summary: Update workspace ACL
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.UpdateWorkspaceACL'
responses:
'204':
description: No Content
/api/v2/workspaces/{workspace}/agent-connection-watch:
get:
operationId: workspace-agent-connection-watch
summary: Workspace Agent Connection Watch
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
responses:
'101':
description: Switching Protocols
content:
application/json:
schema:
$ref: '#/components/schemas/workspacesdk.ConnectionWatchEvent'
/api/v2/workspaces/{workspace}/autostart:
put:
operationId: update-workspace-autostart-schedule-by-id
summary: Update workspace autostart schedule by ID
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.UpdateWorkspaceAutostartRequest'
responses:
'204':
description: No Content
/api/v2/workspaces/{workspace}/autoupdates:
put:
operationId: update-workspace-automatic-updates-by-id
summary: Update workspace automatic updates by ID
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.UpdateWorkspaceAutomaticUpdatesRequest'
responses:
'204':
description: No Content
/api/v2/workspaces/{workspace}/dormant:
put:
operationId: update-workspace-dormancy-status-by-id
summary: Update workspace dormancy status by id.
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.UpdateWorkspaceDormancy'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Workspace'
/api/v2/workspaces/{workspace}/extend:
put:
operationId: extend-workspace-deadline-by-id
summary: Extend workspace deadline by ID
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.PutExtendWorkspaceRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Response'
/api/v2/workspaces/{workspace}/favorite:
put:
operationId: favorite-workspace-by-id
summary: Favorite workspace by ID.
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
responses:
'204':
description: No Content
delete:
operationId: unfavorite-workspace-by-id
summary: Unfavorite workspace by ID.
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
responses:
'204':
description: No Content
/api/v2/workspaces/{workspace}/resolve-autostart:
get:
operationId: resolve-workspace-autostart-by-id
summary: Resolve workspace autostart by id.
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.ResolveAutostartResponse'
/api/v2/workspaces/{workspace}/timings:
get:
operationId: get-workspace-timings-by-id
summary: Get workspace timings by ID
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.WorkspaceBuildTimings'
/api/v2/workspaces/{workspace}/ttl:
put:
operationId: update-workspace-ttl-by-id
summary: Update workspace TTL by ID
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.UpdateWorkspaceTTLRequest'
responses:
'204':
description: No Content
/api/v2/workspaces/{workspace}/usage:
post:
operationId: post-workspace-usage-by-id
summary: Post Workspace Usage by ID
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.PostWorkspaceUsageRequest'
responses:
'204':
description: No Content
/api/v2/workspaces/{workspace}/watch:
get:
operationId: watch-workspace-by-id
summary: Watch workspace by ID
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
responses:
'200':
description: OK
content:
text/event-stream:
schema:
$ref: '#/components/schemas/codersdk.Response'
/api/v2/workspaces/{workspace}/watch-ws:
get:
operationId: watch-workspace-by-id-via-websockets
summary: Watch workspace by ID via WebSockets
tags:
- Workspaces
security:
- CoderSessionToken: []
parameters:
- name: workspace
in: path
required: true
description: Workspace ID
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.ServerSentEvent'
components:
schemas:
codersdk.CreateWorkspaceRequest:
type: object
description: 'CreateWorkspaceRequest provides options for creating a new workspace. Only one of TemplateID or TemplateVersionID can be specified, not both. If TemplateID is specified, the active version of the template will be used. Workspace names: - Must start with a letter or number - Can only contain letters, numbers, and hyphens - Cannot contain spaces or special characters - Cannot be named `new` or `create` - Must be unique within your workspaces - Maximum length of 32 characters'
properties:
automatic_updates:
$ref: '#/components/schemas/codersdk.AutomaticUpdates'
autostart_schedule:
type: string
name:
type: string
rich_parameter_values:
type: array
description: 'RichParameterValues allows for additional parameters to be provided
during the initial provision.'
items:
$ref: '#/components/schemas/codersdk.WorkspaceBuildParameter'
template_id:
type: string
format: uuid
description: TemplateID specifies which template should be used for creating the workspace.
template_version_id:
type: string
format: uuid
description: TemplateVersionID can be used to specify a specific version of a template for creating the workspace.
template_version_preset_id:
type: string
format: uuid
ttl_ms:
type: integer
required:
- name
codersdk.TimingStage:
type: string
enum:
- init
- plan
- graph
- apply
- start
- stop
- cron
- connect
codersdk.SharedWorkspaceActorType:
type: string
enum:
- group
- user
codersdk.UpdateWorkspaceDormancy:
type: object
properties:
dormant:
type: boolean
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.WorkspaceHealth:
type: object
properties:
failing_agents:
type: array
description: FailingAgents lists the IDs of the agents that are failing, if any.
items:
type: string
format: uuid
healthy:
type: boolean
description: Healthy is true if the workspace is healthy.
example: false
codersdk.DisplayApp:
type: string
enum:
- vscode
- vscode_insiders
- web_terminal
- port_forwarding_helper
- ssh_helper
codersdk.ResolveAutostartResponse:
type: object
properties:
parameter_mismatch:
type: boolean
codersdk.ReducedUser:
type: object
properties:
avatar_url:
type: string
format: uri
created_at:
type: string
format: date-time
email:
type: string
format: email
id:
type: string
format: uuid
is_service_account:
type: boolean
last_seen_at:
type: string
format: date-time
login_type:
$ref: '#/components/schemas/codersdk.LoginType'
name:
type: string
status:
enum:
- active
- suspended
allOf:
- $ref: '#/components/schemas/codersdk.UserStatus'
theme_preference:
type: string
description: 'Deprecated: this value should be retrieved from
`codersdk.UserPreferenceSettings` instead.'
updated_at:
type: string
format: date-time
username:
type: string
required:
- created_at
- email
- id
- username
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.UserStatus:
type: string
enum:
- active
- dormant
- suspended
workspacesdk.WatchError:
type: object
properties:
code:
$ref: '#/components/schemas/workspacesdk.WatchErrorCode'
details:
type: string
message:
type: string
retryable:
type: boolean
workspacesdk.AgentUpdate:
type: object
properties:
id:
type: string
format: uuid
lifecycle:
$ref: '#/components/schemas/codersdk.WorkspaceAgentLifecycle'
uuid.NullUUID:
type: object
properties:
uuid:
type: string
valid:
type: boolean
description: Valid is true if UUID is not NULL
codersdk.UpdateWorkspaceAutomaticUpdatesRequest:
type: object
properties:
automatic_updates:
$ref: '#/components/schemas/codersdk.AutomaticUpdates'
codersdk.GroupSource:
type: string
enum:
- user
- oidc
codersdk.PutExtendWorkspaceRequest:
type: object
properties:
deadline:
type: string
format: date-time
required:
- deadline
codersdk.WorkspaceRole:
type: string
enum:
- admin
- use
- ''
codersdk.ServerSentEvent:
type: object
properties:
data: {}
type:
$ref: '#/components/schemas/codersdk.ServerSentEventType'
codersdk.ProvisionerJobStatus:
type: string
enum:
- pending
- running
- succeeded
- canceling
- canceled
- failed
- unknown
codersdk.WorkspaceBuildTimings:
type: object
properties:
agent_connection_timings:
type: array
items:
$ref: '#/components/schemas/codersdk.AgentConnectionTiming'
agent_script_timings:
type: array
description: 'TODO: Consolidate agent-related timing metrics into a single struct when
updating the API version'
items:
$ref: '#/components/schemas/codersdk.AgentScriptTiming'
provisioner_timings:
type: array
items:
$ref: '#/components/schemas/codersdk.ProvisionerTiming'
codersdk.WorkspaceBuildParameter:
type: object
properties:
name:
type: string
value:
type: string
workspacesdk.WatchErrorCode:
type: integer
enum:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
x-enum-comments:
_: Ensure that zero value is not a valid code
codersdk.DERPRegion:
type: object
properties:
latency_ms:
type: number
preferred:
type: boolean
codersdk.UpdateWorkspaceTTLRequest:
type: object
properties:
ttl_ms:
type: integer
codersdk.WorkspaceAgentScriptStatus:
type: string
enum:
- ok
- exit_failure
- timed_out
- pipes_left_open
codersdk.AgentScriptTiming:
type: object
properties:
display_name:
type: string
ended_at:
type: string
format: date-time
exit_code:
type: integer
stage:
$ref: '#/components/schemas/codersdk.TimingStage'
started_at:
type: string
format: date-time
status:
type: string
workspace_agent_id:
type: string
workspace_agent_name:
type: string
codersdk.ProvisionerJobType:
type: string
enum:
- template_version_import
- workspace_build
- template_version_dry_run
codersdk.WorkspaceAgentStartupScriptBehavior:
type: string
enum:
- blocking
- non-blocking
codersdk.WorkspaceUser:
type: object
properties:
avatar_url:
type: string
format: uri
id:
type: string
format: uuid
name:
type: string
role:
enum:
- admin
- use
allOf:
- $ref: '#/components/schemas/codersdk.WorkspaceRole'
username:
type: string
required:
- id
- username
codersdk.WorkspacesResponse:
type: object
properties:
count:
type: integer
workspaces:
type: array
items:
$ref: '#/components/schemas/codersdk.Workspace'
codersdk.MinimalUser:
type: object
properties:
avatar_url:
type: string
format: uri
id:
type: string
format: uuid
name:
type: string
username:
type: string
required:
- id
- username
codersdk.UpdateWorkspaceAutostartRequest:
type: object
properties:
schedule:
type: string
description: 'Schedule is expected to be of the form `CRON_TZ=<IANA Timezone> <min> <hour> * * <dow>`
Example: `CRON_TZ=US/Central 30 9 * * 1-5` represents 0930 in the timezone US/Central
on weekdays (Mon-Fri). `CRON_TZ` defaults to UTC if not present.'
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
form
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coder/refs/heads/main/openapi/coder-workspaces-api-openapi.yml