2026-08-11 11:22:55 -04:00
---
# Code generated by make gen. DO NOT EDIT.
title : Workspaces
---
<!-- DO NOT EDIT | GENERATED CONTENT -->
2022-12-19 18:43:46 +01:00
2023-01-11 12:16:09 +01:00
## Create user workspace by organization
2022-12-19 18:43:46 +01:00
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2022-12-19 18:43:46 +01:00
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/organizations/{ organization} /members/{ user} /workspaces \
2023-02-09 15:02:03 +01:00
-H 'Content-Type: application/json' \
2022-12-19 18:43:46 +01:00
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`POST /api/v2/organizations/{organization}/members/{user}/workspaces`
2022-12-19 18:43:46 +01:00
2024-04-02 10:11:24 -05:00
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.
2023-02-09 15:02:03 +01:00
> Body parameter
```json
{
2025-01-03 18:12:59 +05:00
"automatic_updates" : "always" ,
"autostart_schedule" : "string" ,
"name" : "string" ,
"rich_parameter_values" : [
{
"name" : "string" ,
"value" : "string"
}
],
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
2025-04-14 15:34:50 +02:00
"template_version_preset_id" : "512a53a7-30da-446e-a1fc-713c630baff1" ,
2025-01-03 18:12:59 +05:00
"ttl_ms" : 0
2023-02-09 15:02:03 +01:00
}
```
2022-12-19 18:43:46 +01:00
### Parameters
2023-02-09 15:02:03 +01:00
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|----------------|------|------------------------------------------------------------------------------|----------|--------------------------|
2023-02-09 15:02:03 +01:00
| `organization` | path | string(uuid) | true | Organization ID |
| `user` | path | string | true | Username, UUID, or me |
| `body` | body | [codersdk.CreateWorkspaceRequest ](schemas.md#codersdkcreateworkspacerequest ) | true | Create workspace request |
2022-12-19 18:43:46 +01:00
### Example responses
2026-08-05 17:17:59 -05:00
> 201 Response
2022-12-19 18:43:46 +01:00
```json
{
2025-01-03 18:12:59 +05:00
"allow_renames" : true ,
"automatic_updates" : "always" ,
"autostart_schedule" : "string" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"deleting_at" : "2019-08-24T14:15:22Z" ,
"dormant_at" : "2019-08-24T14:15:22Z" ,
"favorite" : true ,
"health" : {
"failing_agents" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"healthy" : false
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-07-15 14:11:04 +01:00
"is_prebuild" : true ,
2025-01-03 18:12:59 +05:00
"last_used_at" : "2019-08-24T14:15:22Z" ,
2025-03-31 10:55:44 -04:00
"latest_app_status" : {
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_id" : "affd1d10-9538-4fc8-9e0b-4594a28c1335" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"message" : "string" ,
"needs_user_attention" : true ,
"state" : "working" ,
"uri" : "string" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
},
2025-01-03 18:12:59 +05:00
"latest_build" : {
"build_number" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"deadline" : "2019-08-24T14:15:22Z" ,
2025-08-19 10:41:33 +02:00
"has_external_agent" : true ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
"initiator_name" : "string" ,
"job" : {
2025-01-20 11:18:53 +02:00
"available_workers" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
2025-01-03 18:12:59 +05:00
"canceled_at" : "2019-08-24T14:15:22Z" ,
"completed_at" : "2019-08-24T14:15:22Z" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"error" : "string" ,
"error_code" : "REQUIRED_TEMPLATE_VARIABLES" ,
"file_id" : "8a0cfb4f-ddc9-436d-91bb-75133c583767" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-10-06 10:56:43 +02:00
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
2025-01-20 11:18:53 +02:00
"input" : {
"error" : "string" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"workspace_build_id" : "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
2025-07-30 19:09:53 -05:00
"logs_overflowed" : true ,
2025-02-06 16:19:20 +02:00
"metadata" : {
"template_display_name" : "string" ,
2025-02-10 10:00:34 -03:00
"template_icon" : "string" ,
2025-02-06 16:19:20 +02:00
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_version_name" : "string" ,
2026-04-10 09:50:11 -05:00
"workspace_build_transition" : "start" ,
2025-02-06 16:19:20 +02:00
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string"
},
2025-01-20 11:18:53 +02:00
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
2025-01-03 18:12:59 +05:00
"queue_position" : 0 ,
"queue_size" : 0 ,
"started_at" : "2019-08-24T14:15:22Z" ,
"status" : "pending" ,
"tags" : {
"property1" : "string" ,
"property2" : "string"
},
2025-01-20 11:18:53 +02:00
"type" : "template_version_import" ,
2025-05-19 16:05:39 +01:00
"worker_id" : "ae5fa6f7-c55b-40c1-b40a-b36ac467652b" ,
"worker_name" : "string"
2025-01-03 18:12:59 +05:00
},
"matched_provisioners" : {
"available" : 0 ,
"count" : 0 ,
"most_recently_seen" : "2019-08-24T14:15:22Z"
},
"max_deadline" : "2019-08-24T14:15:22Z" ,
"reason" : "initiator" ,
"resources" : [
{
"agents" : [
{
"api_version" : "string" ,
"apps" : [
{
"command" : "string" ,
"display_name" : "string" ,
"external" : true ,
2025-05-27 13:13:08 -06:00
"group" : "string" ,
2025-01-03 18:12:59 +05:00
"health" : "disabled" ,
"healthcheck" : {
"interval" : 0 ,
"threshold" : 0 ,
"url" : "string"
},
"hidden" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-01-07 18:08:03 +01:00
"open_in" : "slim-window" ,
2025-01-03 18:12:59 +05:00
"sharing_level" : "owner" ,
"slug" : "string" ,
2025-03-31 10:55:44 -04:00
"statuses" : [
{
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_id" : "affd1d10-9538-4fc8-9e0b-4594a28c1335" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"message" : "string" ,
"needs_user_attention" : true ,
"state" : "working" ,
"uri" : "string" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}
],
2025-01-03 18:12:59 +05:00
"subdomain" : true ,
"subdomain_name" : "string" ,
2025-09-10 11:01:54 -05:00
"tooltip" : "string" ,
2025-01-03 18:12:59 +05:00
"url" : "string"
}
],
"architecture" : "string" ,
"connection_timeout_seconds" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"directory" : "string" ,
"disconnected_at" : "2019-08-24T14:15:22Z" ,
"display_apps" : [
"vscode"
],
"environment_variables" : {
"property1" : "string" ,
"property2" : "string"
},
"expanded_directory" : "string" ,
"first_connected_at" : "2019-08-24T14:15:22Z" ,
"health" : {
"healthy" : false ,
"reason" : "agent has lost connection"
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"instance_id" : "string" ,
"last_connected_at" : "2019-08-24T14:15:22Z" ,
"latency" : {
"property1" : {
"latency_ms" : 0 ,
"preferred" : true
},
"property2" : {
"latency_ms" : 0 ,
"preferred" : true
}
},
"lifecycle_state" : "created" ,
"log_sources" : [
{
"created_at" : "2019-08-24T14:15:22Z" ,
"display_name" : "string" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"workspace_agent_id" : "7ad2e618-fea7-4c1a-b70a-f501566a72f1"
}
],
"logs_length" : 0 ,
"logs_overflowed" : true ,
2026-08-10 08:13:32 -05:00
"metadata" : [
{
"description" : {
"display_name" : "string" ,
"interval" : 0 ,
"key" : "string" ,
"script" : "string" ,
"timeout" : 0
},
"result" : {
"age" : 0 ,
"collected_at" : "2019-08-24T14:15:22Z" ,
"error" : "string" ,
"value" : "string"
}
}
],
2025-01-03 18:12:59 +05:00
"name" : "string" ,
"operating_system" : "string" ,
2026-08-27 09:13:33 -07:00
"parent_id" : "1c6ca187-e61f-4301-8dcb-0e9749e89eef" ,
2025-01-03 18:12:59 +05:00
"ready_at" : "2019-08-24T14:15:22Z" ,
"resource_id" : "4d5215ed-38bb-48ed-879a-fdb9ca58522f" ,
"scripts" : [
{
"cron" : "string" ,
"display_name" : "string" ,
2026-04-29 12:24:26 -08:00
"exit_code" : 0 ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"log_path" : "string" ,
"log_source_id" : "4197ab25-95cf-4b91-9c78-f7f2af5d353a" ,
"run_on_start" : true ,
"run_on_stop" : true ,
"script" : "string" ,
"start_blocks_login" : true ,
2026-04-29 12:24:26 -08:00
"status" : "ok" ,
2025-01-03 18:12:59 +05:00
"timeout" : 0
}
],
"started_at" : "2019-08-24T14:15:22Z" ,
"startup_script_behavior" : "blocking" ,
"status" : "connecting" ,
"subsystems" : [
"envbox"
],
"troubleshooting_url" : "string" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"version" : "string"
}
],
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"hide" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"job_id" : "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f" ,
"metadata" : [
{
"key" : "string" ,
"sensitive" : true ,
"value" : "string"
}
],
"name" : "string" ,
"type" : "string" ,
"workspace_transition" : "start"
}
],
"status" : "pending" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"template_version_name" : "string" ,
2025-04-14 15:34:50 +02:00
"template_version_preset_id" : "512a53a7-30da-446e-a1fc-713c630baff1" ,
2025-01-03 18:12:59 +05:00
"transition" : "start" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string" ,
"workspace_owner_avatar_url" : "string" ,
"workspace_owner_id" : "e7078695-5279-4c86-8774-3ac2367a2fc7" ,
2025-05-30 11:00:26 -03:00
"workspace_owner_name" : "string"
2025-01-03 18:12:59 +05:00
},
"name" : "string" ,
"next_start_at" : "2019-08-24T14:15:22Z" ,
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
"organization_name" : "string" ,
"outdated" : true ,
"owner_avatar_url" : "string" ,
"owner_id" : "8826ee2e-7933-4665-aef2-2393f84a0d05" ,
"owner_name" : "string" ,
2025-12-15 08:42:08 -08:00
"shared_with" : [
{
"actor_type" : "group" ,
"avatar_url" : "http://example.com" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"name" : "string" ,
"roles" : [
"admin"
]
}
],
2025-01-03 18:12:59 +05:00
"template_active_version_id" : "b0da9c29-67d8-4c87-888c-bafe356f7f3c" ,
"template_allow_user_cancel_workspace_jobs" : true ,
"template_display_name" : "string" ,
"template_icon" : "string" ,
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_require_active_version" : true ,
2025-05-19 16:59:15 -05:00
"template_use_classic_parameter_flow" : true ,
2025-01-03 18:12:59 +05:00
"ttl_ms" : 0 ,
"updated_at" : "2019-08-24T14:15:22Z"
2022-12-19 18:43:46 +01:00
}
```
### Responses
2026-08-05 17:17:59 -05:00
| Status | Meaning | Description | Schema |
|--------|--------------------------------------------------------------|-------------|----------------------------------------------------|
| 201 | [Created ](https://tools.ietf.org/html/rfc7231#section-6.3.2 ) | Created | [codersdk.Workspace ](schemas.md#codersdkworkspace ) |
2022-12-19 18:43:46 +01:00
2023-01-05 15:27:10 +01:00
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2022-12-19 18:43:46 +01:00
2026-02-19 10:04:53 -08:00
## Get users available for workspace creation
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2026-02-19 10:04:53 -08:00
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{ organization} /members/{ user} /workspaces/available-users \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/organizations/{organization}/members/{user}/workspaces/available-users`
2026-02-19 10:04:53 -08:00
### Parameters
| Name | In | Type | Required | Description |
|----------------|-------|--------------|----------|-----------------------|
| `organization` | path | string(uuid) | true | Organization ID |
| `user` | path | string | true | User ID, name, or me |
| `q` | query | string | false | Search query |
| `limit` | query | integer | false | Limit results |
| `offset` | query | integer | false | Offset for pagination |
### Example responses
> 200 Response
```json
[
{
"avatar_url" : "http://example.com" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"name" : "string" ,
"username" : "string"
}
]
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|-----------------------------------------------------------------|
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | array of [codersdk.MinimalUser ](schemas.md#codersdkminimaluser ) |
<h3 id="get-users-available-for-workspace-creation-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
|----------------|--------------|----------|--------------|-------------|
| `[array item]` | array | false | | |
| `» avatar_url` | string(uri) | false | | |
| `» id` | string(uuid) | true | | |
| `» name` | string | false | | |
| `» username` | string | true | | |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2023-01-11 14:08:04 +01:00
## Get workspace metadata by user and workspace name
2022-12-19 18:43:46 +01:00
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2022-12-19 18:43:46 +01:00
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/users/{ user} /workspace/{ workspacename} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/users/{user}/workspace/{workspacename}`
2022-12-19 18:43:46 +01:00
### Parameters
2022-12-22 15:53:14 +01:00
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------------|-------|---------|----------|-------------------------------------------------------------|
2023-01-11 14:08:04 +01:00
| `user` | path | string | true | User ID, name, or me |
2022-12-22 15:53:14 +01:00
| `workspacename` | path | string | true | Workspace name |
| `include_deleted` | query | boolean | false | Return data instead of HTTP 404 if the workspace is deleted |
2022-12-19 18:43:46 +01:00
### Example responses
> 200 Response
2024-07-30 10:44:02 -06:00
```json
{
2025-01-03 18:12:59 +05:00
"allow_renames" : true ,
"automatic_updates" : "always" ,
"autostart_schedule" : "string" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"deleting_at" : "2019-08-24T14:15:22Z" ,
"dormant_at" : "2019-08-24T14:15:22Z" ,
"favorite" : true ,
"health" : {
"failing_agents" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"healthy" : false
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-07-15 14:11:04 +01:00
"is_prebuild" : true ,
2025-01-03 18:12:59 +05:00
"last_used_at" : "2019-08-24T14:15:22Z" ,
2025-03-31 10:55:44 -04:00
"latest_app_status" : {
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_id" : "affd1d10-9538-4fc8-9e0b-4594a28c1335" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"message" : "string" ,
"needs_user_attention" : true ,
"state" : "working" ,
"uri" : "string" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
},
2025-01-03 18:12:59 +05:00
"latest_build" : {
"build_number" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"deadline" : "2019-08-24T14:15:22Z" ,
2025-08-19 10:41:33 +02:00
"has_external_agent" : true ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
"initiator_name" : "string" ,
"job" : {
2025-01-20 11:18:53 +02:00
"available_workers" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
2025-01-03 18:12:59 +05:00
"canceled_at" : "2019-08-24T14:15:22Z" ,
"completed_at" : "2019-08-24T14:15:22Z" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"error" : "string" ,
"error_code" : "REQUIRED_TEMPLATE_VARIABLES" ,
"file_id" : "8a0cfb4f-ddc9-436d-91bb-75133c583767" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-10-06 10:56:43 +02:00
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
2025-01-20 11:18:53 +02:00
"input" : {
"error" : "string" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"workspace_build_id" : "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
2025-07-30 19:09:53 -05:00
"logs_overflowed" : true ,
2025-02-06 16:19:20 +02:00
"metadata" : {
"template_display_name" : "string" ,
2025-02-10 10:00:34 -03:00
"template_icon" : "string" ,
2025-02-06 16:19:20 +02:00
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_version_name" : "string" ,
2026-04-10 09:50:11 -05:00
"workspace_build_transition" : "start" ,
2025-02-06 16:19:20 +02:00
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string"
},
2025-01-20 11:18:53 +02:00
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
2025-01-03 18:12:59 +05:00
"queue_position" : 0 ,
"queue_size" : 0 ,
"started_at" : "2019-08-24T14:15:22Z" ,
"status" : "pending" ,
"tags" : {
"property1" : "string" ,
"property2" : "string"
},
2025-01-20 11:18:53 +02:00
"type" : "template_version_import" ,
2025-05-19 16:05:39 +01:00
"worker_id" : "ae5fa6f7-c55b-40c1-b40a-b36ac467652b" ,
"worker_name" : "string"
2025-01-03 18:12:59 +05:00
},
"matched_provisioners" : {
"available" : 0 ,
"count" : 0 ,
"most_recently_seen" : "2019-08-24T14:15:22Z"
},
"max_deadline" : "2019-08-24T14:15:22Z" ,
"reason" : "initiator" ,
"resources" : [
{
"agents" : [
{
"api_version" : "string" ,
"apps" : [
{
"command" : "string" ,
"display_name" : "string" ,
"external" : true ,
2025-05-27 13:13:08 -06:00
"group" : "string" ,
2025-01-03 18:12:59 +05:00
"health" : "disabled" ,
"healthcheck" : {
"interval" : 0 ,
"threshold" : 0 ,
"url" : "string"
},
"hidden" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-01-07 18:08:03 +01:00
"open_in" : "slim-window" ,
2025-01-03 18:12:59 +05:00
"sharing_level" : "owner" ,
"slug" : "string" ,
2025-03-31 10:55:44 -04:00
"statuses" : [
{
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_id" : "affd1d10-9538-4fc8-9e0b-4594a28c1335" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"message" : "string" ,
"needs_user_attention" : true ,
"state" : "working" ,
"uri" : "string" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}
],
2025-01-03 18:12:59 +05:00
"subdomain" : true ,
"subdomain_name" : "string" ,
2025-09-10 11:01:54 -05:00
"tooltip" : "string" ,
2025-01-03 18:12:59 +05:00
"url" : "string"
}
],
"architecture" : "string" ,
"connection_timeout_seconds" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"directory" : "string" ,
"disconnected_at" : "2019-08-24T14:15:22Z" ,
"display_apps" : [
"vscode"
],
"environment_variables" : {
"property1" : "string" ,
"property2" : "string"
},
"expanded_directory" : "string" ,
"first_connected_at" : "2019-08-24T14:15:22Z" ,
"health" : {
"healthy" : false ,
"reason" : "agent has lost connection"
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"instance_id" : "string" ,
"last_connected_at" : "2019-08-24T14:15:22Z" ,
"latency" : {
"property1" : {
"latency_ms" : 0 ,
"preferred" : true
},
"property2" : {
"latency_ms" : 0 ,
"preferred" : true
}
},
"lifecycle_state" : "created" ,
"log_sources" : [
{
"created_at" : "2019-08-24T14:15:22Z" ,
"display_name" : "string" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"workspace_agent_id" : "7ad2e618-fea7-4c1a-b70a-f501566a72f1"
}
],
"logs_length" : 0 ,
"logs_overflowed" : true ,
2026-08-10 08:13:32 -05:00
"metadata" : [
{
"description" : {
"display_name" : "string" ,
"interval" : 0 ,
"key" : "string" ,
"script" : "string" ,
"timeout" : 0
},
"result" : {
"age" : 0 ,
"collected_at" : "2019-08-24T14:15:22Z" ,
"error" : "string" ,
"value" : "string"
}
}
],
2025-01-03 18:12:59 +05:00
"name" : "string" ,
"operating_system" : "string" ,
2026-08-27 09:13:33 -07:00
"parent_id" : "1c6ca187-e61f-4301-8dcb-0e9749e89eef" ,
2025-01-03 18:12:59 +05:00
"ready_at" : "2019-08-24T14:15:22Z" ,
"resource_id" : "4d5215ed-38bb-48ed-879a-fdb9ca58522f" ,
"scripts" : [
{
"cron" : "string" ,
"display_name" : "string" ,
2026-04-29 12:24:26 -08:00
"exit_code" : 0 ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"log_path" : "string" ,
"log_source_id" : "4197ab25-95cf-4b91-9c78-f7f2af5d353a" ,
"run_on_start" : true ,
"run_on_stop" : true ,
"script" : "string" ,
"start_blocks_login" : true ,
2026-04-29 12:24:26 -08:00
"status" : "ok" ,
2025-01-03 18:12:59 +05:00
"timeout" : 0
}
],
"started_at" : "2019-08-24T14:15:22Z" ,
"startup_script_behavior" : "blocking" ,
"status" : "connecting" ,
"subsystems" : [
"envbox"
],
"troubleshooting_url" : "string" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"version" : "string"
}
],
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"hide" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"job_id" : "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f" ,
"metadata" : [
{
"key" : "string" ,
"sensitive" : true ,
"value" : "string"
}
],
"name" : "string" ,
"type" : "string" ,
"workspace_transition" : "start"
}
],
"status" : "pending" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"template_version_name" : "string" ,
2025-04-14 15:34:50 +02:00
"template_version_preset_id" : "512a53a7-30da-446e-a1fc-713c630baff1" ,
2025-01-03 18:12:59 +05:00
"transition" : "start" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string" ,
"workspace_owner_avatar_url" : "string" ,
"workspace_owner_id" : "e7078695-5279-4c86-8774-3ac2367a2fc7" ,
2025-05-30 11:00:26 -03:00
"workspace_owner_name" : "string"
2025-01-03 18:12:59 +05:00
},
"name" : "string" ,
"next_start_at" : "2019-08-24T14:15:22Z" ,
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
"organization_name" : "string" ,
"outdated" : true ,
"owner_avatar_url" : "string" ,
"owner_id" : "8826ee2e-7933-4665-aef2-2393f84a0d05" ,
"owner_name" : "string" ,
2025-12-15 08:42:08 -08:00
"shared_with" : [
{
"actor_type" : "group" ,
"avatar_url" : "http://example.com" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"name" : "string" ,
"roles" : [
"admin"
]
}
],
2025-01-03 18:12:59 +05:00
"template_active_version_id" : "b0da9c29-67d8-4c87-888c-bafe356f7f3c" ,
"template_allow_user_cancel_workspace_jobs" : true ,
"template_display_name" : "string" ,
"template_icon" : "string" ,
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_require_active_version" : true ,
2025-05-19 16:59:15 -05:00
"template_use_classic_parameter_flow" : true ,
2025-01-03 18:12:59 +05:00
"ttl_ms" : 0 ,
"updated_at" : "2019-08-24T14:15:22Z"
2024-07-30 10:44:02 -06:00
}
```
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|----------------------------------------------------|
2024-07-30 10:44:02 -06:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.Workspace ](schemas.md#codersdkworkspace ) |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
## Create user workspace
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2024-07-30 10:44:02 -06:00
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/users/{ user} /workspaces \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`POST /api/v2/users/{user}/workspaces`
2024-07-30 10:44:02 -06:00
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.
> Body parameter
```json
{
2025-01-03 18:12:59 +05:00
"automatic_updates" : "always" ,
"autostart_schedule" : "string" ,
"name" : "string" ,
"rich_parameter_values" : [
{
"name" : "string" ,
"value" : "string"
}
],
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
2025-04-14 15:34:50 +02:00
"template_version_preset_id" : "512a53a7-30da-446e-a1fc-713c630baff1" ,
2025-01-03 18:12:59 +05:00
"ttl_ms" : 0
2024-07-30 10:44:02 -06:00
}
```
### Parameters
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|--------|------|------------------------------------------------------------------------------|----------|--------------------------|
2024-07-30 10:44:02 -06:00
| `user` | path | string | true | Username, UUID, or me |
| `body` | body | [codersdk.CreateWorkspaceRequest ](schemas.md#codersdkcreateworkspacerequest ) | true | Create workspace request |
### Example responses
2026-08-05 17:17:59 -05:00
> 201 Response
2024-07-30 10:44:02 -06:00
2022-12-19 18:43:46 +01:00
```json
{
2025-01-03 18:12:59 +05:00
"allow_renames" : true ,
"automatic_updates" : "always" ,
"autostart_schedule" : "string" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"deleting_at" : "2019-08-24T14:15:22Z" ,
"dormant_at" : "2019-08-24T14:15:22Z" ,
"favorite" : true ,
"health" : {
"failing_agents" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"healthy" : false
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-07-15 14:11:04 +01:00
"is_prebuild" : true ,
2025-01-03 18:12:59 +05:00
"last_used_at" : "2019-08-24T14:15:22Z" ,
2025-03-31 10:55:44 -04:00
"latest_app_status" : {
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_id" : "affd1d10-9538-4fc8-9e0b-4594a28c1335" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"message" : "string" ,
"needs_user_attention" : true ,
"state" : "working" ,
"uri" : "string" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
},
2025-01-03 18:12:59 +05:00
"latest_build" : {
"build_number" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"deadline" : "2019-08-24T14:15:22Z" ,
2025-08-19 10:41:33 +02:00
"has_external_agent" : true ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
"initiator_name" : "string" ,
"job" : {
2025-01-20 11:18:53 +02:00
"available_workers" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
2025-01-03 18:12:59 +05:00
"canceled_at" : "2019-08-24T14:15:22Z" ,
"completed_at" : "2019-08-24T14:15:22Z" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"error" : "string" ,
"error_code" : "REQUIRED_TEMPLATE_VARIABLES" ,
"file_id" : "8a0cfb4f-ddc9-436d-91bb-75133c583767" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-10-06 10:56:43 +02:00
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
2025-01-20 11:18:53 +02:00
"input" : {
"error" : "string" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"workspace_build_id" : "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
2025-07-30 19:09:53 -05:00
"logs_overflowed" : true ,
2025-02-06 16:19:20 +02:00
"metadata" : {
"template_display_name" : "string" ,
2025-02-10 10:00:34 -03:00
"template_icon" : "string" ,
2025-02-06 16:19:20 +02:00
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_version_name" : "string" ,
2026-04-10 09:50:11 -05:00
"workspace_build_transition" : "start" ,
2025-02-06 16:19:20 +02:00
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string"
},
2025-01-20 11:18:53 +02:00
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
2025-01-03 18:12:59 +05:00
"queue_position" : 0 ,
"queue_size" : 0 ,
"started_at" : "2019-08-24T14:15:22Z" ,
"status" : "pending" ,
"tags" : {
"property1" : "string" ,
"property2" : "string"
},
2025-01-20 11:18:53 +02:00
"type" : "template_version_import" ,
2025-05-19 16:05:39 +01:00
"worker_id" : "ae5fa6f7-c55b-40c1-b40a-b36ac467652b" ,
"worker_name" : "string"
2025-01-03 18:12:59 +05:00
},
"matched_provisioners" : {
"available" : 0 ,
"count" : 0 ,
"most_recently_seen" : "2019-08-24T14:15:22Z"
},
"max_deadline" : "2019-08-24T14:15:22Z" ,
"reason" : "initiator" ,
"resources" : [
{
"agents" : [
{
"api_version" : "string" ,
"apps" : [
{
"command" : "string" ,
"display_name" : "string" ,
"external" : true ,
2025-05-27 13:13:08 -06:00
"group" : "string" ,
2025-01-03 18:12:59 +05:00
"health" : "disabled" ,
"healthcheck" : {
"interval" : 0 ,
"threshold" : 0 ,
"url" : "string"
},
"hidden" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-01-07 18:08:03 +01:00
"open_in" : "slim-window" ,
2025-01-03 18:12:59 +05:00
"sharing_level" : "owner" ,
"slug" : "string" ,
2025-03-31 10:55:44 -04:00
"statuses" : [
{
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_id" : "affd1d10-9538-4fc8-9e0b-4594a28c1335" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"message" : "string" ,
"needs_user_attention" : true ,
"state" : "working" ,
"uri" : "string" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}
],
2025-01-03 18:12:59 +05:00
"subdomain" : true ,
"subdomain_name" : "string" ,
2025-09-10 11:01:54 -05:00
"tooltip" : "string" ,
2025-01-03 18:12:59 +05:00
"url" : "string"
}
],
"architecture" : "string" ,
"connection_timeout_seconds" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"directory" : "string" ,
"disconnected_at" : "2019-08-24T14:15:22Z" ,
"display_apps" : [
"vscode"
],
"environment_variables" : {
"property1" : "string" ,
"property2" : "string"
},
"expanded_directory" : "string" ,
"first_connected_at" : "2019-08-24T14:15:22Z" ,
"health" : {
"healthy" : false ,
"reason" : "agent has lost connection"
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"instance_id" : "string" ,
"last_connected_at" : "2019-08-24T14:15:22Z" ,
"latency" : {
"property1" : {
"latency_ms" : 0 ,
"preferred" : true
},
"property2" : {
"latency_ms" : 0 ,
"preferred" : true
}
},
"lifecycle_state" : "created" ,
"log_sources" : [
{
"created_at" : "2019-08-24T14:15:22Z" ,
"display_name" : "string" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"workspace_agent_id" : "7ad2e618-fea7-4c1a-b70a-f501566a72f1"
}
],
"logs_length" : 0 ,
"logs_overflowed" : true ,
2026-08-10 08:13:32 -05:00
"metadata" : [
{
"description" : {
"display_name" : "string" ,
"interval" : 0 ,
"key" : "string" ,
"script" : "string" ,
"timeout" : 0
},
"result" : {
"age" : 0 ,
"collected_at" : "2019-08-24T14:15:22Z" ,
"error" : "string" ,
"value" : "string"
}
}
],
2025-01-03 18:12:59 +05:00
"name" : "string" ,
"operating_system" : "string" ,
2026-08-27 09:13:33 -07:00
"parent_id" : "1c6ca187-e61f-4301-8dcb-0e9749e89eef" ,
2025-01-03 18:12:59 +05:00
"ready_at" : "2019-08-24T14:15:22Z" ,
"resource_id" : "4d5215ed-38bb-48ed-879a-fdb9ca58522f" ,
"scripts" : [
{
"cron" : "string" ,
"display_name" : "string" ,
2026-04-29 12:24:26 -08:00
"exit_code" : 0 ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"log_path" : "string" ,
"log_source_id" : "4197ab25-95cf-4b91-9c78-f7f2af5d353a" ,
"run_on_start" : true ,
"run_on_stop" : true ,
"script" : "string" ,
"start_blocks_login" : true ,
2026-04-29 12:24:26 -08:00
"status" : "ok" ,
2025-01-03 18:12:59 +05:00
"timeout" : 0
}
],
"started_at" : "2019-08-24T14:15:22Z" ,
"startup_script_behavior" : "blocking" ,
"status" : "connecting" ,
"subsystems" : [
"envbox"
],
"troubleshooting_url" : "string" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"version" : "string"
}
],
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"hide" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"job_id" : "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f" ,
"metadata" : [
{
"key" : "string" ,
"sensitive" : true ,
"value" : "string"
}
],
"name" : "string" ,
"type" : "string" ,
"workspace_transition" : "start"
}
],
"status" : "pending" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"template_version_name" : "string" ,
2025-04-14 15:34:50 +02:00
"template_version_preset_id" : "512a53a7-30da-446e-a1fc-713c630baff1" ,
2025-01-03 18:12:59 +05:00
"transition" : "start" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string" ,
"workspace_owner_avatar_url" : "string" ,
"workspace_owner_id" : "e7078695-5279-4c86-8774-3ac2367a2fc7" ,
2025-05-30 11:00:26 -03:00
"workspace_owner_name" : "string"
2025-01-03 18:12:59 +05:00
},
"name" : "string" ,
"next_start_at" : "2019-08-24T14:15:22Z" ,
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
"organization_name" : "string" ,
"outdated" : true ,
"owner_avatar_url" : "string" ,
"owner_id" : "8826ee2e-7933-4665-aef2-2393f84a0d05" ,
"owner_name" : "string" ,
2025-12-15 08:42:08 -08:00
"shared_with" : [
{
"actor_type" : "group" ,
"avatar_url" : "http://example.com" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"name" : "string" ,
"roles" : [
"admin"
]
}
],
2025-01-03 18:12:59 +05:00
"template_active_version_id" : "b0da9c29-67d8-4c87-888c-bafe356f7f3c" ,
"template_allow_user_cancel_workspace_jobs" : true ,
"template_display_name" : "string" ,
"template_icon" : "string" ,
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_require_active_version" : true ,
2025-05-19 16:59:15 -05:00
"template_use_classic_parameter_flow" : true ,
2025-01-03 18:12:59 +05:00
"ttl_ms" : 0 ,
"updated_at" : "2019-08-24T14:15:22Z"
2022-12-19 18:43:46 +01:00
}
```
### Responses
2026-08-05 17:17:59 -05:00
| Status | Meaning | Description | Schema |
|--------|--------------------------------------------------------------|-------------|----------------------------------------------------|
| 201 | [Created ](https://tools.ietf.org/html/rfc7231#section-6.3.2 ) | Created | [codersdk.Workspace ](schemas.md#codersdkworkspace ) |
2022-12-19 18:43:46 +01:00
2023-01-05 15:27:10 +01:00
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2022-12-19 18:43:46 +01:00
## List workspaces
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2022-12-19 18:43:46 +01:00
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaces \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/workspaces`
2022-12-19 18:43:46 +01:00
### Parameters
2026-09-11 03:48:56 +02:00
| Name | In | Type | Required | Description |
|----------|-------|---------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `q` | query | string | false | Search query in the format `key:value` . Available keys are: owner, template, name, status, has-agent, dormant, last_used_after, last_used_before, has_external_agent, healthy, include_agent_metadata (expands each agent with the named metadata keys rather than filtering; repeat the key for multiple items). |
| `limit` | query | integer | false | Page limit |
| `offset` | query | integer | false | Page offset |
2022-12-19 18:43:46 +01:00
### Example responses
> 200 Response
```json
{
2025-01-03 18:12:59 +05:00
"count" : 0 ,
"workspaces" : [
{
"allow_renames" : true ,
"automatic_updates" : "always" ,
"autostart_schedule" : "string" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"deleting_at" : "2019-08-24T14:15:22Z" ,
"dormant_at" : "2019-08-24T14:15:22Z" ,
"favorite" : true ,
"health" : {
"failing_agents" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"healthy" : false
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-07-15 14:11:04 +01:00
"is_prebuild" : true ,
2025-01-03 18:12:59 +05:00
"last_used_at" : "2019-08-24T14:15:22Z" ,
2025-03-31 10:55:44 -04:00
"latest_app_status" : {
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_id" : "affd1d10-9538-4fc8-9e0b-4594a28c1335" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"message" : "string" ,
"needs_user_attention" : true ,
"state" : "working" ,
"uri" : "string" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
},
2025-01-03 18:12:59 +05:00
"latest_build" : {
"build_number" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"deadline" : "2019-08-24T14:15:22Z" ,
2025-08-19 10:41:33 +02:00
"has_external_agent" : true ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
"initiator_name" : "string" ,
"job" : {
2025-01-20 11:18:53 +02:00
"available_workers" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
2025-01-03 18:12:59 +05:00
"canceled_at" : "2019-08-24T14:15:22Z" ,
"completed_at" : "2019-08-24T14:15:22Z" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"error" : "string" ,
"error_code" : "REQUIRED_TEMPLATE_VARIABLES" ,
"file_id" : "8a0cfb4f-ddc9-436d-91bb-75133c583767" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-10-06 10:56:43 +02:00
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
2025-01-20 11:18:53 +02:00
"input" : {
"error" : "string" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"workspace_build_id" : "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
2025-07-30 19:09:53 -05:00
"logs_overflowed" : true ,
2025-02-06 16:19:20 +02:00
"metadata" : {
"template_display_name" : "string" ,
2025-02-10 10:00:34 -03:00
"template_icon" : "string" ,
2025-02-06 16:19:20 +02:00
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_version_name" : "string" ,
2026-04-10 09:50:11 -05:00
"workspace_build_transition" : "start" ,
2025-02-06 16:19:20 +02:00
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string"
},
2025-01-20 11:18:53 +02:00
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
2025-01-03 18:12:59 +05:00
"queue_position" : 0 ,
"queue_size" : 0 ,
"started_at" : "2019-08-24T14:15:22Z" ,
"status" : "pending" ,
"tags" : {
"property1" : "string" ,
"property2" : "string"
},
2025-01-20 11:18:53 +02:00
"type" : "template_version_import" ,
2025-05-19 16:05:39 +01:00
"worker_id" : "ae5fa6f7-c55b-40c1-b40a-b36ac467652b" ,
"worker_name" : "string"
2025-01-03 18:12:59 +05:00
},
"matched_provisioners" : {
"available" : 0 ,
"count" : 0 ,
"most_recently_seen" : "2019-08-24T14:15:22Z"
},
"max_deadline" : "2019-08-24T14:15:22Z" ,
"reason" : "initiator" ,
"resources" : [
{
"agents" : [
{
"api_version" : "string" ,
"apps" : [
{
"command" : "string" ,
"display_name" : "string" ,
"external" : true ,
2025-05-27 13:13:08 -06:00
"group" : "string" ,
2025-01-03 18:12:59 +05:00
"health" : "disabled" ,
"healthcheck" : {},
"hidden" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-01-07 18:08:03 +01:00
"open_in" : "slim-window" ,
2025-01-03 18:12:59 +05:00
"sharing_level" : "owner" ,
"slug" : "string" ,
2025-03-31 10:55:44 -04:00
"statuses" : [],
2025-01-03 18:12:59 +05:00
"subdomain" : true ,
"subdomain_name" : "string" ,
2025-09-10 11:01:54 -05:00
"tooltip" : "string" ,
2025-01-03 18:12:59 +05:00
"url" : "string"
}
],
"architecture" : "string" ,
"connection_timeout_seconds" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"directory" : "string" ,
"disconnected_at" : "2019-08-24T14:15:22Z" ,
"display_apps" : [
"vscode"
],
"environment_variables" : {
"property1" : "string" ,
"property2" : "string"
},
"expanded_directory" : "string" ,
"first_connected_at" : "2019-08-24T14:15:22Z" ,
"health" : {
"healthy" : false ,
"reason" : "agent has lost connection"
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"instance_id" : "string" ,
"last_connected_at" : "2019-08-24T14:15:22Z" ,
"latency" : {
"property1" : {
"latency_ms" : 0 ,
"preferred" : true
},
"property2" : {
"latency_ms" : 0 ,
"preferred" : true
}
},
"lifecycle_state" : "created" ,
"log_sources" : [
{
"created_at" : "2019-08-24T14:15:22Z" ,
"display_name" : "string" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"workspace_agent_id" : "7ad2e618-fea7-4c1a-b70a-f501566a72f1"
}
],
"logs_length" : 0 ,
"logs_overflowed" : true ,
2026-08-10 08:13:32 -05:00
"metadata" : [
{
"description" : {},
"result" : {}
}
],
2025-01-03 18:12:59 +05:00
"name" : "string" ,
"operating_system" : "string" ,
2026-08-27 09:13:33 -07:00
"parent_id" : "1c6ca187-e61f-4301-8dcb-0e9749e89eef" ,
2025-01-03 18:12:59 +05:00
"ready_at" : "2019-08-24T14:15:22Z" ,
"resource_id" : "4d5215ed-38bb-48ed-879a-fdb9ca58522f" ,
"scripts" : [
{
"cron" : "string" ,
"display_name" : "string" ,
2026-04-29 12:24:26 -08:00
"exit_code" : 0 ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"log_path" : "string" ,
"log_source_id" : "4197ab25-95cf-4b91-9c78-f7f2af5d353a" ,
"run_on_start" : true ,
"run_on_stop" : true ,
"script" : "string" ,
"start_blocks_login" : true ,
2026-04-29 12:24:26 -08:00
"status" : "ok" ,
2025-01-03 18:12:59 +05:00
"timeout" : 0
}
],
"started_at" : "2019-08-24T14:15:22Z" ,
"startup_script_behavior" : "blocking" ,
"status" : "connecting" ,
"subsystems" : [
"envbox"
],
"troubleshooting_url" : "string" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"version" : "string"
}
],
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"hide" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"job_id" : "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f" ,
"metadata" : [
{
"key" : "string" ,
"sensitive" : true ,
"value" : "string"
}
],
"name" : "string" ,
"type" : "string" ,
"workspace_transition" : "start"
}
],
"status" : "pending" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"template_version_name" : "string" ,
2025-04-14 15:34:50 +02:00
"template_version_preset_id" : "512a53a7-30da-446e-a1fc-713c630baff1" ,
2025-01-03 18:12:59 +05:00
"transition" : "start" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string" ,
"workspace_owner_avatar_url" : "string" ,
"workspace_owner_id" : "e7078695-5279-4c86-8774-3ac2367a2fc7" ,
2025-05-30 11:00:26 -03:00
"workspace_owner_name" : "string"
2025-01-03 18:12:59 +05:00
},
"name" : "string" ,
"next_start_at" : "2019-08-24T14:15:22Z" ,
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
"organization_name" : "string" ,
"outdated" : true ,
"owner_avatar_url" : "string" ,
"owner_id" : "8826ee2e-7933-4665-aef2-2393f84a0d05" ,
"owner_name" : "string" ,
2025-12-15 08:42:08 -08:00
"shared_with" : [
{
"actor_type" : "group" ,
"avatar_url" : "http://example.com" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"name" : "string" ,
"roles" : [
"admin"
]
}
],
2025-01-03 18:12:59 +05:00
"template_active_version_id" : "b0da9c29-67d8-4c87-888c-bafe356f7f3c" ,
"template_allow_user_cancel_workspace_jobs" : true ,
"template_display_name" : "string" ,
"template_icon" : "string" ,
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_require_active_version" : true ,
2025-05-19 16:59:15 -05:00
"template_use_classic_parameter_flow" : true ,
2025-01-03 18:12:59 +05:00
"ttl_ms" : 0 ,
"updated_at" : "2019-08-24T14:15:22Z"
}
]
2022-12-19 18:43:46 +01:00
}
```
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|----------------------------------------------------------------------|
2022-12-19 18:43:46 +01:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.WorkspacesResponse ](schemas.md#codersdkworkspacesresponse ) |
2023-01-05 15:27:10 +01:00
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2022-12-19 18:43:46 +01:00
## Get workspace metadata by ID
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2022-12-19 18:43:46 +01:00
# Example request using curl
2023-01-13 12:27:21 +01:00
curl -X GET http://coder-server:8080/api/v2/workspaces/{ workspace} \
2022-12-19 18:43:46 +01:00
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/workspaces/{workspace}`
2022-12-19 18:43:46 +01:00
### Parameters
2022-12-22 15:53:14 +01:00
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------------|-------|--------------|----------|-------------------------------------------------------------|
2023-01-13 12:27:21 +01:00
| `workspace` | path | string(uuid) | true | Workspace ID |
2022-12-22 15:53:14 +01:00
| `include_deleted` | query | boolean | false | Return data instead of HTTP 404 if the workspace is deleted |
2022-12-19 18:43:46 +01:00
### Example responses
> 200 Response
```json
{
2025-01-03 18:12:59 +05:00
"allow_renames" : true ,
"automatic_updates" : "always" ,
"autostart_schedule" : "string" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"deleting_at" : "2019-08-24T14:15:22Z" ,
"dormant_at" : "2019-08-24T14:15:22Z" ,
"favorite" : true ,
"health" : {
"failing_agents" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"healthy" : false
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-07-15 14:11:04 +01:00
"is_prebuild" : true ,
2025-01-03 18:12:59 +05:00
"last_used_at" : "2019-08-24T14:15:22Z" ,
2025-03-31 10:55:44 -04:00
"latest_app_status" : {
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_id" : "affd1d10-9538-4fc8-9e0b-4594a28c1335" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"message" : "string" ,
"needs_user_attention" : true ,
"state" : "working" ,
"uri" : "string" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
},
2025-01-03 18:12:59 +05:00
"latest_build" : {
"build_number" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"deadline" : "2019-08-24T14:15:22Z" ,
2025-08-19 10:41:33 +02:00
"has_external_agent" : true ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
"initiator_name" : "string" ,
"job" : {
2025-01-20 11:18:53 +02:00
"available_workers" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
2025-01-03 18:12:59 +05:00
"canceled_at" : "2019-08-24T14:15:22Z" ,
"completed_at" : "2019-08-24T14:15:22Z" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"error" : "string" ,
"error_code" : "REQUIRED_TEMPLATE_VARIABLES" ,
"file_id" : "8a0cfb4f-ddc9-436d-91bb-75133c583767" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-10-06 10:56:43 +02:00
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
2025-01-20 11:18:53 +02:00
"input" : {
"error" : "string" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"workspace_build_id" : "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
2025-07-30 19:09:53 -05:00
"logs_overflowed" : true ,
2025-02-06 16:19:20 +02:00
"metadata" : {
"template_display_name" : "string" ,
2025-02-10 10:00:34 -03:00
"template_icon" : "string" ,
2025-02-06 16:19:20 +02:00
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_version_name" : "string" ,
2026-04-10 09:50:11 -05:00
"workspace_build_transition" : "start" ,
2025-02-06 16:19:20 +02:00
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string"
},
2025-01-20 11:18:53 +02:00
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
2025-01-03 18:12:59 +05:00
"queue_position" : 0 ,
"queue_size" : 0 ,
"started_at" : "2019-08-24T14:15:22Z" ,
"status" : "pending" ,
"tags" : {
"property1" : "string" ,
"property2" : "string"
},
2025-01-20 11:18:53 +02:00
"type" : "template_version_import" ,
2025-05-19 16:05:39 +01:00
"worker_id" : "ae5fa6f7-c55b-40c1-b40a-b36ac467652b" ,
"worker_name" : "string"
2025-01-03 18:12:59 +05:00
},
"matched_provisioners" : {
"available" : 0 ,
"count" : 0 ,
"most_recently_seen" : "2019-08-24T14:15:22Z"
},
"max_deadline" : "2019-08-24T14:15:22Z" ,
"reason" : "initiator" ,
"resources" : [
{
"agents" : [
{
"api_version" : "string" ,
"apps" : [
{
"command" : "string" ,
"display_name" : "string" ,
"external" : true ,
2025-05-27 13:13:08 -06:00
"group" : "string" ,
2025-01-03 18:12:59 +05:00
"health" : "disabled" ,
"healthcheck" : {
"interval" : 0 ,
"threshold" : 0 ,
"url" : "string"
},
"hidden" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-01-07 18:08:03 +01:00
"open_in" : "slim-window" ,
2025-01-03 18:12:59 +05:00
"sharing_level" : "owner" ,
"slug" : "string" ,
2025-03-31 10:55:44 -04:00
"statuses" : [
{
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_id" : "affd1d10-9538-4fc8-9e0b-4594a28c1335" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"message" : "string" ,
"needs_user_attention" : true ,
"state" : "working" ,
"uri" : "string" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}
],
2025-01-03 18:12:59 +05:00
"subdomain" : true ,
"subdomain_name" : "string" ,
2025-09-10 11:01:54 -05:00
"tooltip" : "string" ,
2025-01-03 18:12:59 +05:00
"url" : "string"
}
],
"architecture" : "string" ,
"connection_timeout_seconds" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"directory" : "string" ,
"disconnected_at" : "2019-08-24T14:15:22Z" ,
"display_apps" : [
"vscode"
],
"environment_variables" : {
"property1" : "string" ,
"property2" : "string"
},
"expanded_directory" : "string" ,
"first_connected_at" : "2019-08-24T14:15:22Z" ,
"health" : {
"healthy" : false ,
"reason" : "agent has lost connection"
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"instance_id" : "string" ,
"last_connected_at" : "2019-08-24T14:15:22Z" ,
"latency" : {
"property1" : {
"latency_ms" : 0 ,
"preferred" : true
},
"property2" : {
"latency_ms" : 0 ,
"preferred" : true
}
},
"lifecycle_state" : "created" ,
"log_sources" : [
{
"created_at" : "2019-08-24T14:15:22Z" ,
"display_name" : "string" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"workspace_agent_id" : "7ad2e618-fea7-4c1a-b70a-f501566a72f1"
}
],
"logs_length" : 0 ,
"logs_overflowed" : true ,
2026-08-10 08:13:32 -05:00
"metadata" : [
{
"description" : {
"display_name" : "string" ,
"interval" : 0 ,
"key" : "string" ,
"script" : "string" ,
"timeout" : 0
},
"result" : {
"age" : 0 ,
"collected_at" : "2019-08-24T14:15:22Z" ,
"error" : "string" ,
"value" : "string"
}
}
],
2025-01-03 18:12:59 +05:00
"name" : "string" ,
"operating_system" : "string" ,
2026-08-27 09:13:33 -07:00
"parent_id" : "1c6ca187-e61f-4301-8dcb-0e9749e89eef" ,
2025-01-03 18:12:59 +05:00
"ready_at" : "2019-08-24T14:15:22Z" ,
"resource_id" : "4d5215ed-38bb-48ed-879a-fdb9ca58522f" ,
"scripts" : [
{
"cron" : "string" ,
"display_name" : "string" ,
2026-04-29 12:24:26 -08:00
"exit_code" : 0 ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"log_path" : "string" ,
"log_source_id" : "4197ab25-95cf-4b91-9c78-f7f2af5d353a" ,
"run_on_start" : true ,
"run_on_stop" : true ,
"script" : "string" ,
"start_blocks_login" : true ,
2026-04-29 12:24:26 -08:00
"status" : "ok" ,
2025-01-03 18:12:59 +05:00
"timeout" : 0
}
],
"started_at" : "2019-08-24T14:15:22Z" ,
"startup_script_behavior" : "blocking" ,
"status" : "connecting" ,
"subsystems" : [
"envbox"
],
"troubleshooting_url" : "string" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"version" : "string"
}
],
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"hide" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"job_id" : "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f" ,
"metadata" : [
{
"key" : "string" ,
"sensitive" : true ,
"value" : "string"
}
],
"name" : "string" ,
"type" : "string" ,
"workspace_transition" : "start"
}
],
"status" : "pending" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"template_version_name" : "string" ,
2025-04-14 15:34:50 +02:00
"template_version_preset_id" : "512a53a7-30da-446e-a1fc-713c630baff1" ,
2025-01-03 18:12:59 +05:00
"transition" : "start" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string" ,
"workspace_owner_avatar_url" : "string" ,
"workspace_owner_id" : "e7078695-5279-4c86-8774-3ac2367a2fc7" ,
2025-05-30 11:00:26 -03:00
"workspace_owner_name" : "string"
2025-01-03 18:12:59 +05:00
},
"name" : "string" ,
"next_start_at" : "2019-08-24T14:15:22Z" ,
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
"organization_name" : "string" ,
"outdated" : true ,
"owner_avatar_url" : "string" ,
"owner_id" : "8826ee2e-7933-4665-aef2-2393f84a0d05" ,
"owner_name" : "string" ,
2025-12-15 08:42:08 -08:00
"shared_with" : [
{
"actor_type" : "group" ,
"avatar_url" : "http://example.com" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"name" : "string" ,
"roles" : [
"admin"
]
}
],
2025-01-03 18:12:59 +05:00
"template_active_version_id" : "b0da9c29-67d8-4c87-888c-bafe356f7f3c" ,
"template_allow_user_cancel_workspace_jobs" : true ,
"template_display_name" : "string" ,
"template_icon" : "string" ,
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_require_active_version" : true ,
2025-05-19 16:59:15 -05:00
"template_use_classic_parameter_flow" : true ,
2025-01-03 18:12:59 +05:00
"ttl_ms" : 0 ,
"updated_at" : "2019-08-24T14:15:22Z"
2022-12-19 18:43:46 +01:00
}
```
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|----------------------------------------------------|
2022-12-19 18:43:46 +01:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.Workspace ](schemas.md#codersdkworkspace ) |
2023-01-05 15:27:10 +01:00
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2022-12-19 18:43:46 +01:00
## Update workspace metadata by ID
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2022-12-19 18:43:46 +01:00
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/workspaces/{ workspace} \
-H 'Content-Type: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`PATCH /api/v2/workspaces/{workspace}`
2022-12-19 18:43:46 +01:00
> Body parameter
```json
{
2025-01-03 18:12:59 +05:00
"name" : "string"
2022-12-19 18:43:46 +01:00
}
```
### Parameters
2022-12-22 15:53:14 +01:00
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|------------------------------------------------------------------------------|----------|-------------------------|
2022-12-22 15:53:14 +01:00
| `workspace` | path | string(uuid) | true | Workspace ID |
| `body` | body | [codersdk.UpdateWorkspaceRequest ](schemas.md#codersdkupdateworkspacerequest ) | true | Metadata update request |
2022-12-19 18:43:46 +01:00
### Responses
2022-12-21 15:37:30 +01:00
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|-----------------------------------------------------------------|-------------|--------|
2022-12-21 15:37:30 +01:00
| 204 | [No Content ](https://tools.ietf.org/html/rfc7231#section-6.3.5 ) | No Content | |
2022-12-19 18:43:46 +01:00
2023-01-05 15:27:10 +01:00
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2022-12-19 18:43:46 +01:00
2025-08-25 06:11:18 -06:00
## Get workspace ACLs
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2025-08-25 06:11:18 -06:00
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaces/{ workspace} /acl \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/workspaces/{workspace}/acl`
2025-08-25 06:11:18 -06:00
### Parameters
| Name | In | Type | Required | Description |
|-------------|------|--------------|----------|--------------|
| `workspace` | path | string(uuid) | true | Workspace ID |
### Example responses
> 200 Response
```json
{
"group" : [
{
"avatar_url" : "http://example.com" ,
"display_name" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"members" : [
{
"avatar_url" : "http://example.com" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"email" : "user@example.com" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2026-03-17 15:36:20 -06:00
"is_service_account" : true ,
2025-08-25 06:11:18 -06:00
"last_seen_at" : "2019-08-24T14:15:22Z" ,
"login_type" : "" ,
"name" : "string" ,
"status" : "active" ,
"theme_preference" : "string" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"username" : "string"
}
],
"name" : "string" ,
"organization_display_name" : "string" ,
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
"organization_name" : "string" ,
"quota_allowance" : 0 ,
"role" : "admin" ,
"source" : "user" ,
"total_member_count" : 0
}
],
"users" : [
{
"avatar_url" : "http://example.com" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-10-22 16:18:31 +11:00
"name" : "string" ,
2025-08-25 06:11:18 -06:00
"role" : "admin" ,
"username" : "string"
}
]
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|----------------------------------------------------------|
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.WorkspaceACL ](schemas.md#codersdkworkspaceacl ) |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2025-09-12 12:21:01 -04:00
## Completely clears the workspace's user and group ACLs
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2025-09-12 12:21:01 -04:00
# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/workspaces/{ workspace} /acl \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`DELETE /api/v2/workspaces/{workspace}/acl`
2025-09-12 12:21:01 -04:00
### Parameters
| Name | In | Type | Required | Description |
|-------------|------|--------------|----------|--------------|
| `workspace` | path | string(uuid) | true | Workspace ID |
### 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 ).
2025-07-31 09:05:09 -06:00
## Update workspace ACL
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2025-07-31 09:05:09 -06:00
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/workspaces/{ workspace} /acl \
-H 'Content-Type: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`PATCH /api/v2/workspaces/{workspace}/acl`
2025-07-31 09:05:09 -06:00
> Body parameter
```json
{
"group_roles" : {
"property1" : "admin" ,
"property2" : "admin"
},
"user_roles" : {
"property1" : "admin" ,
"property2" : "admin"
}
}
```
### Parameters
| Name | In | Type | Required | Description |
|-------------|------|----------------------------------------------------------------------|----------|------------------------------|
| `workspace` | path | string(uuid) | true | Workspace ID |
| `body` | body | [codersdk.UpdateWorkspaceACL ](schemas.md#codersdkupdateworkspaceacl ) | true | Update workspace ACL 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 ).
2026-05-20 13:09:11 -04:00
## Workspace Agent Connection Watch
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2026-05-20 13:09:11 -04:00
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaces/{ workspace} /agent-connection-watch \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/workspaces/{workspace}/agent-connection-watch`
### Parameters
| Name | In | Type | Required | Description |
|-------------|------|--------------|----------|--------------|
| `workspace` | path | string(uuid) | true | Workspace ID |
### Example responses
> 101 Response
```json
{
"agent_update" : {
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"lifecycle" : "created"
},
"build_update" : {
"job_status" : "pending" ,
"transition" : "start"
},
"error" : {
"code" : 0 ,
"details" : "string" ,
"message" : "string" ,
"retryable" : true
}
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|--------------------------------------------------------------------------|---------------------|----------------------------------------------------------------------------------|
| 101 | [Switching Protocols ](https://tools.ietf.org/html/rfc7231#section-6.2.2 ) | Switching Protocols | [workspacesdk.ConnectionWatchEvent ](schemas.md#workspacesdkconnectionwatchevent ) |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2022-12-19 18:43:46 +01:00
## Update workspace autostart schedule by ID
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2022-12-19 18:43:46 +01:00
# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/workspaces/{ workspace} /autostart \
-H 'Content-Type: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`PUT /api/v2/workspaces/{workspace}/autostart`
2022-12-19 18:43:46 +01:00
> Body parameter
```json
{
2025-01-03 18:12:59 +05:00
"schedule" : "string"
2022-12-19 18:43:46 +01:00
}
```
### Parameters
2022-12-22 15:53:14 +01:00
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|------------------------------------------------------------------------------------------------|----------|-------------------------|
2022-12-22 15:53:14 +01:00
| `workspace` | path | string(uuid) | true | Workspace ID |
| `body` | body | [codersdk.UpdateWorkspaceAutostartRequest ](schemas.md#codersdkupdateworkspaceautostartrequest ) | true | Schedule update request |
2022-12-19 18:43:46 +01:00
### Responses
2022-12-21 15:37:30 +01:00
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|-----------------------------------------------------------------|-------------|--------|
2022-12-21 15:37:30 +01:00
| 204 | [No Content ](https://tools.ietf.org/html/rfc7231#section-6.3.5 ) | No Content | |
2022-12-19 18:43:46 +01:00
2023-01-05 15:27:10 +01:00
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2022-12-19 18:43:46 +01:00
2023-10-06 13:27:12 +04:00
## Update workspace automatic updates by ID
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2023-10-06 13:27:12 +04:00
# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/workspaces/{ workspace} /autoupdates \
-H 'Content-Type: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`PUT /api/v2/workspaces/{workspace}/autoupdates`
2023-10-06 13:27:12 +04:00
> Body parameter
```json
{
2025-01-03 18:12:59 +05:00
"automatic_updates" : "always"
2023-10-06 13:27:12 +04:00
}
```
### Parameters
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|--------------------------------------------------------------------------------------------------------------|----------|---------------------------|
2023-10-06 13:27:12 +04:00
| `workspace` | path | string(uuid) | true | Workspace ID |
| `body` | body | [codersdk.UpdateWorkspaceAutomaticUpdatesRequest ](schemas.md#codersdkupdateworkspaceautomaticupdatesrequest ) | true | Automatic updates request |
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|-----------------------------------------------------------------|-------------|--------|
2023-10-06 13:27:12 +04:00
| 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 ).
2025-01-03 18:12:59 +05:00
## Update workspace dormancy status by id
2022-12-19 18:43:46 +01:00
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2022-12-19 18:43:46 +01:00
# Example request using curl
2023-08-24 13:25:54 -05:00
curl -X PUT http://coder-server:8080/api/v2/workspaces/{ workspace} /dormant \
2022-12-19 18:43:46 +01:00
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`PUT /api/v2/workspaces/{workspace}/dormant`
2022-12-19 18:43:46 +01:00
> Body parameter
```json
{
2025-01-03 18:12:59 +05:00
"dormant" : true
2022-12-19 18:43:46 +01:00
}
```
### Parameters
2023-08-24 13:25:54 -05:00
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|--------------------------------------------------------------------------------|----------|------------------------------------|
2023-08-24 13:25:54 -05:00
| `workspace` | path | string(uuid) | true | Workspace ID |
| `body` | body | [codersdk.UpdateWorkspaceDormancy ](schemas.md#codersdkupdateworkspacedormancy ) | true | Make a workspace dormant or active |
2023-06-28 16:12:49 -05:00
### Example responses
> 200 Response
```json
{
2025-01-03 18:12:59 +05:00
"allow_renames" : true ,
"automatic_updates" : "always" ,
"autostart_schedule" : "string" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"deleting_at" : "2019-08-24T14:15:22Z" ,
"dormant_at" : "2019-08-24T14:15:22Z" ,
"favorite" : true ,
"health" : {
"failing_agents" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"healthy" : false
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-07-15 14:11:04 +01:00
"is_prebuild" : true ,
2025-01-03 18:12:59 +05:00
"last_used_at" : "2019-08-24T14:15:22Z" ,
2025-03-31 10:55:44 -04:00
"latest_app_status" : {
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_id" : "affd1d10-9538-4fc8-9e0b-4594a28c1335" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"message" : "string" ,
"needs_user_attention" : true ,
"state" : "working" ,
"uri" : "string" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
},
2025-01-03 18:12:59 +05:00
"latest_build" : {
"build_number" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"deadline" : "2019-08-24T14:15:22Z" ,
2025-08-19 10:41:33 +02:00
"has_external_agent" : true ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
"initiator_name" : "string" ,
"job" : {
2025-01-20 11:18:53 +02:00
"available_workers" : [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
2025-01-03 18:12:59 +05:00
"canceled_at" : "2019-08-24T14:15:22Z" ,
"completed_at" : "2019-08-24T14:15:22Z" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"error" : "string" ,
"error_code" : "REQUIRED_TEMPLATE_VARIABLES" ,
"file_id" : "8a0cfb4f-ddc9-436d-91bb-75133c583767" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-10-06 10:56:43 +02:00
"initiator_id" : "06588898-9a84-4b35-ba8f-f9cbd64946f3" ,
2025-01-20 11:18:53 +02:00
"input" : {
"error" : "string" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"workspace_build_id" : "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
2025-07-30 19:09:53 -05:00
"logs_overflowed" : true ,
2025-02-06 16:19:20 +02:00
"metadata" : {
"template_display_name" : "string" ,
2025-02-10 10:00:34 -03:00
"template_icon" : "string" ,
2025-02-06 16:19:20 +02:00
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_version_name" : "string" ,
2026-04-10 09:50:11 -05:00
"workspace_build_transition" : "start" ,
2025-02-06 16:19:20 +02:00
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string"
},
2025-01-20 11:18:53 +02:00
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
2025-01-03 18:12:59 +05:00
"queue_position" : 0 ,
"queue_size" : 0 ,
"started_at" : "2019-08-24T14:15:22Z" ,
"status" : "pending" ,
"tags" : {
"property1" : "string" ,
"property2" : "string"
},
2025-01-20 11:18:53 +02:00
"type" : "template_version_import" ,
2025-05-19 16:05:39 +01:00
"worker_id" : "ae5fa6f7-c55b-40c1-b40a-b36ac467652b" ,
"worker_name" : "string"
2025-01-03 18:12:59 +05:00
},
"matched_provisioners" : {
"available" : 0 ,
"count" : 0 ,
"most_recently_seen" : "2019-08-24T14:15:22Z"
},
"max_deadline" : "2019-08-24T14:15:22Z" ,
"reason" : "initiator" ,
"resources" : [
{
"agents" : [
{
"api_version" : "string" ,
"apps" : [
{
"command" : "string" ,
"display_name" : "string" ,
"external" : true ,
2025-05-27 13:13:08 -06:00
"group" : "string" ,
2025-01-03 18:12:59 +05:00
"health" : "disabled" ,
"healthcheck" : {
"interval" : 0 ,
"threshold" : 0 ,
"url" : "string"
},
"hidden" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
2025-01-07 18:08:03 +01:00
"open_in" : "slim-window" ,
2025-01-03 18:12:59 +05:00
"sharing_level" : "owner" ,
"slug" : "string" ,
2025-03-31 10:55:44 -04:00
"statuses" : [
{
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_id" : "affd1d10-9538-4fc8-9e0b-4594a28c1335" ,
"created_at" : "2019-08-24T14:15:22Z" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"message" : "string" ,
"needs_user_attention" : true ,
"state" : "working" ,
"uri" : "string" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}
],
2025-01-03 18:12:59 +05:00
"subdomain" : true ,
"subdomain_name" : "string" ,
2025-09-10 11:01:54 -05:00
"tooltip" : "string" ,
2025-01-03 18:12:59 +05:00
"url" : "string"
}
],
"architecture" : "string" ,
"connection_timeout_seconds" : 0 ,
"created_at" : "2019-08-24T14:15:22Z" ,
"directory" : "string" ,
"disconnected_at" : "2019-08-24T14:15:22Z" ,
"display_apps" : [
"vscode"
],
"environment_variables" : {
"property1" : "string" ,
"property2" : "string"
},
"expanded_directory" : "string" ,
"first_connected_at" : "2019-08-24T14:15:22Z" ,
"health" : {
"healthy" : false ,
"reason" : "agent has lost connection"
},
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"instance_id" : "string" ,
"last_connected_at" : "2019-08-24T14:15:22Z" ,
"latency" : {
"property1" : {
"latency_ms" : 0 ,
"preferred" : true
},
"property2" : {
"latency_ms" : 0 ,
"preferred" : true
}
},
"lifecycle_state" : "created" ,
"log_sources" : [
{
"created_at" : "2019-08-24T14:15:22Z" ,
"display_name" : "string" ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"workspace_agent_id" : "7ad2e618-fea7-4c1a-b70a-f501566a72f1"
}
],
"logs_length" : 0 ,
"logs_overflowed" : true ,
2026-08-10 08:13:32 -05:00
"metadata" : [
{
"description" : {
"display_name" : "string" ,
"interval" : 0 ,
"key" : "string" ,
"script" : "string" ,
"timeout" : 0
},
"result" : {
"age" : 0 ,
"collected_at" : "2019-08-24T14:15:22Z" ,
"error" : "string" ,
"value" : "string"
}
}
],
2025-01-03 18:12:59 +05:00
"name" : "string" ,
"operating_system" : "string" ,
2026-08-27 09:13:33 -07:00
"parent_id" : "1c6ca187-e61f-4301-8dcb-0e9749e89eef" ,
2025-01-03 18:12:59 +05:00
"ready_at" : "2019-08-24T14:15:22Z" ,
"resource_id" : "4d5215ed-38bb-48ed-879a-fdb9ca58522f" ,
"scripts" : [
{
"cron" : "string" ,
"display_name" : "string" ,
2026-04-29 12:24:26 -08:00
"exit_code" : 0 ,
2025-01-03 18:12:59 +05:00
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"log_path" : "string" ,
"log_source_id" : "4197ab25-95cf-4b91-9c78-f7f2af5d353a" ,
"run_on_start" : true ,
"run_on_stop" : true ,
"script" : "string" ,
"start_blocks_login" : true ,
2026-04-29 12:24:26 -08:00
"status" : "ok" ,
2025-01-03 18:12:59 +05:00
"timeout" : 0
}
],
"started_at" : "2019-08-24T14:15:22Z" ,
"startup_script_behavior" : "blocking" ,
"status" : "connecting" ,
"subsystems" : [
"envbox"
],
"troubleshooting_url" : "string" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"version" : "string"
}
],
"created_at" : "2019-08-24T14:15:22Z" ,
"daily_cost" : 0 ,
"hide" : true ,
"icon" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"job_id" : "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f" ,
"metadata" : [
{
"key" : "string" ,
"sensitive" : true ,
"value" : "string"
}
],
"name" : "string" ,
"type" : "string" ,
"workspace_transition" : "start"
}
],
"status" : "pending" ,
"template_version_id" : "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1" ,
"template_version_name" : "string" ,
2025-04-14 15:34:50 +02:00
"template_version_preset_id" : "512a53a7-30da-446e-a1fc-713c630baff1" ,
2025-01-03 18:12:59 +05:00
"transition" : "start" ,
"updated_at" : "2019-08-24T14:15:22Z" ,
"workspace_id" : "0967198e-ec7b-4c6b-b4d3-f71244cadbe9" ,
"workspace_name" : "string" ,
"workspace_owner_avatar_url" : "string" ,
"workspace_owner_id" : "e7078695-5279-4c86-8774-3ac2367a2fc7" ,
2025-05-30 11:00:26 -03:00
"workspace_owner_name" : "string"
2025-01-03 18:12:59 +05:00
},
"name" : "string" ,
"next_start_at" : "2019-08-24T14:15:22Z" ,
"organization_id" : "7c60d51f-b44e-4682-87d6-449835ea4de6" ,
"organization_name" : "string" ,
"outdated" : true ,
"owner_avatar_url" : "string" ,
"owner_id" : "8826ee2e-7933-4665-aef2-2393f84a0d05" ,
"owner_name" : "string" ,
2025-12-15 08:42:08 -08:00
"shared_with" : [
{
"actor_type" : "group" ,
"avatar_url" : "http://example.com" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"name" : "string" ,
"roles" : [
"admin"
]
}
],
2025-01-03 18:12:59 +05:00
"template_active_version_id" : "b0da9c29-67d8-4c87-888c-bafe356f7f3c" ,
"template_allow_user_cancel_workspace_jobs" : true ,
"template_display_name" : "string" ,
"template_icon" : "string" ,
"template_id" : "c6d67e98-83ea-49f0-8812-e4abae2b68bc" ,
"template_name" : "string" ,
"template_require_active_version" : true ,
2025-05-19 16:59:15 -05:00
"template_use_classic_parameter_flow" : true ,
2025-01-03 18:12:59 +05:00
"ttl_ms" : 0 ,
"updated_at" : "2019-08-24T14:15:22Z"
2023-06-28 16:12:49 -05:00
}
```
### Responses
2023-08-03 19:46:02 -05:00
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|----------------------------------------------------|
2023-08-03 19:46:02 -05:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.Workspace ](schemas.md#codersdkworkspace ) |
2023-06-28 16:12:49 -05:00
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2023-08-24 13:25:54 -05:00
## Extend workspace deadline by ID
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2023-08-24 13:25:54 -05:00
# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/workspaces/{ workspace} /extend \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`PUT /api/v2/workspaces/{workspace}/extend`
2023-08-24 13:25:54 -05:00
> Body parameter
```json
{
2025-01-03 18:12:59 +05:00
"deadline" : "2019-08-24T14:15:22Z"
2023-08-24 13:25:54 -05:00
}
```
### Parameters
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|------------------------------------------------------------------------------------|----------|--------------------------------|
2023-08-24 13:25:54 -05:00
| `workspace` | path | string(uuid) | true | Workspace ID |
| `body` | body | [codersdk.PutExtendWorkspaceRequest ](schemas.md#codersdkputextendworkspacerequest ) | true | Extend deadline update request |
### Example responses
> 200 Response
```json
{
2025-01-03 18:12:59 +05:00
"detail" : "string" ,
"message" : "string" ,
"validations" : [
{
"detail" : "string" ,
"field" : "string"
}
]
2023-08-24 13:25:54 -05:00
}
```
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|--------------------------------------------------|
2023-08-24 13:25:54 -05:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.Response ](schemas.md#codersdkresponse ) |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2025-01-03 18:12:59 +05:00
## Favorite workspace by ID
2024-01-24 13:39:19 +00:00
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2024-01-24 13:39:19 +00:00
# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/workspaces/{ workspace} /favorite \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`PUT /api/v2/workspaces/{workspace}/favorite`
2024-01-24 13:39:19 +00:00
### Parameters
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|--------------|----------|--------------|
2024-01-24 13:39:19 +00:00
| `workspace` | path | string(uuid) | true | Workspace ID |
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|-----------------------------------------------------------------|-------------|--------|
2024-01-24 13:39:19 +00:00
| 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 ).
2025-01-03 18:12:59 +05:00
## Unfavorite workspace by ID
2024-01-24 13:39:19 +00:00
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2024-01-24 13:39:19 +00:00
# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/workspaces/{ workspace} /favorite \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`DELETE /api/v2/workspaces/{workspace}/favorite`
2024-01-24 13:39:19 +00:00
### Parameters
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|--------------|----------|--------------|
2024-01-24 13:39:19 +00:00
| `workspace` | path | string(uuid) | true | Workspace ID |
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|-----------------------------------------------------------------|-------------|--------|
2024-01-24 13:39:19 +00:00
| 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 ).
2025-01-03 18:12:59 +05:00
## Resolve workspace autostart by id
2023-11-08 23:24:56 -06:00
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2023-11-08 23:24:56 -06:00
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaces/{ workspace} /resolve-autostart \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/workspaces/{workspace}/resolve-autostart`
2023-11-08 23:24:56 -06:00
### Parameters
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|--------------|----------|--------------|
2023-11-08 23:24:56 -06:00
| `workspace` | path | string(uuid) | true | Workspace ID |
### Example responses
> 200 Response
```json
{
2026-05-21 09:19:29 -06:00
"parameter_mismatch" : true
2023-11-08 23:24:56 -06:00
}
```
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|----------------------------------------------------------------------------------|
2023-11-08 23:24:56 -06:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.ResolveAutostartResponse ](schemas.md#codersdkresolveautostartresponse ) |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2024-09-16 16:31:05 -03:00
## Get workspace timings by ID
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2024-09-16 16:31:05 -03:00
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaces/{ workspace} /timings \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/workspaces/{workspace}/timings`
2024-09-16 16:31:05 -03:00
### Parameters
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|--------------|----------|--------------|
2024-09-16 16:31:05 -03:00
| `workspace` | path | string(uuid) | true | Workspace ID |
### Example responses
> 200 Response
```json
{
2025-01-03 18:12:59 +05:00
"agent_connection_timings" : [
{
"ended_at" : "2019-08-24T14:15:22Z" ,
"stage" : "init" ,
"started_at" : "2019-08-24T14:15:22Z" ,
"workspace_agent_id" : "string" ,
"workspace_agent_name" : "string"
}
],
"agent_script_timings" : [
{
"display_name" : "string" ,
"ended_at" : "2019-08-24T14:15:22Z" ,
"exit_code" : 0 ,
"stage" : "init" ,
"started_at" : "2019-08-24T14:15:22Z" ,
"status" : "string" ,
"workspace_agent_id" : "string" ,
"workspace_agent_name" : "string"
}
],
"provisioner_timings" : [
{
"action" : "string" ,
"ended_at" : "2019-08-24T14:15:22Z" ,
"job_id" : "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f" ,
"resource" : "string" ,
"source" : "string" ,
"stage" : "init" ,
"started_at" : "2019-08-24T14:15:22Z"
}
]
2024-09-16 16:31:05 -03:00
}
```
### Responses
2024-10-14 09:31:03 -03:00
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|----------------------------------------------------------------------------|
2024-10-14 09:31:03 -03:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.WorkspaceBuildTimings ](schemas.md#codersdkworkspacebuildtimings ) |
2024-09-16 16:31:05 -03:00
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2022-12-19 18:43:46 +01:00
## Update workspace TTL by ID
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2022-12-19 18:43:46 +01:00
# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/workspaces/{ workspace} /ttl \
-H 'Content-Type: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`PUT /api/v2/workspaces/{workspace}/ttl`
2022-12-19 18:43:46 +01:00
> Body parameter
```json
{
2025-01-03 18:12:59 +05:00
"ttl_ms" : 0
2022-12-19 18:43:46 +01:00
}
```
### Parameters
2022-12-22 15:53:14 +01:00
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|------------------------------------------------------------------------------------|----------|------------------------------|
2022-12-22 15:53:14 +01:00
| `workspace` | path | string(uuid) | true | Workspace ID |
| `body` | body | [codersdk.UpdateWorkspaceTTLRequest ](schemas.md#codersdkupdateworkspacettlrequest ) | true | Workspace TTL update request |
2022-12-19 18:43:46 +01:00
### Responses
2022-12-21 15:37:30 +01:00
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|-----------------------------------------------------------------|-------------|--------|
2022-12-21 15:37:30 +01:00
| 204 | [No Content ](https://tools.ietf.org/html/rfc7231#section-6.3.5 ) | No Content | |
2022-12-19 18:43:46 +01:00
2023-01-05 15:27:10 +01:00
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2022-12-19 18:43:46 +01:00
2024-03-20 16:44:12 +00:00
## Post Workspace Usage by ID
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2024-03-20 16:44:12 +00:00
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaces/{ workspace} /usage \
2024-06-14 10:08:45 -04:00
-H 'Content-Type: application/json' \
2024-03-20 16:44:12 +00:00
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`POST /api/v2/workspaces/{workspace}/usage`
2024-03-20 16:44:12 +00:00
2024-06-14 10:08:45 -04:00
> Body parameter
```json
{
2025-01-03 18:12:59 +05:00
"agent_id" : "2b1e3b65-2c04-4fa2-a2d7-467901e98978" ,
"app_name" : "vscode"
2024-06-14 10:08:45 -04:00
}
```
2024-03-20 16:44:12 +00:00
### Parameters
2024-06-14 10:08:45 -04:00
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|------------------------------------------------------------------------------------|----------|------------------------------|
2024-06-14 10:08:45 -04:00
| `workspace` | path | string(uuid) | true | Workspace ID |
| `body` | body | [codersdk.PostWorkspaceUsageRequest ](schemas.md#codersdkpostworkspaceusagerequest ) | false | Post workspace usage request |
2024-03-20 16:44:12 +00:00
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|-----------------------------------------------------------------|-------------|--------|
2024-03-20 16:44:12 +00:00
| 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 ).
2022-12-19 18:43:46 +01:00
## Watch workspace by ID
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2022-12-19 18:43:46 +01:00
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaces/{ workspace} /watch \
-H 'Accept: text/event-stream' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/workspaces/{workspace}/watch`
2022-12-19 18:43:46 +01:00
### Parameters
2022-12-22 15:53:14 +01:00
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|-------------|------|--------------|----------|--------------|
2022-12-22 15:53:14 +01:00
| `workspace` | path | string(uuid) | true | Workspace ID |
2022-12-19 18:43:46 +01:00
### Example responses
> 200 Response
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|--------------------------------------------------|
2022-12-19 18:43:46 +01:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.Response ](schemas.md#codersdkresponse ) |
2023-01-05 15:27:10 +01:00
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2025-03-28 17:13:20 -04:00
## Watch workspace by ID via WebSockets
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2025-03-28 17:13:20 -04:00
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaces/{ workspace} /watch-ws \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/workspaces/{workspace}/watch-ws`
2025-03-28 17:13:20 -04:00
### Parameters
| Name | In | Type | Required | Description |
|-------------|------|--------------|----------|--------------|
| `workspace` | path | string(uuid) | true | Workspace ID |
### Example responses
> 200 Response
```json
{
"data" : null ,
"type" : "ping"
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|----------------------------------------------------------------|
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.ServerSentEvent ](schemas.md#codersdkserversentevent ) |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).