# Templates
## Get templates by organization [#get-templates-by-organization]
### Code samples [#code-samples]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templates \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/organizations/{organization}/templates`
Returns a list of templates for the specified organization.
By default, only non-deprecated templates are returned.
To include deprecated templates, specify `deprecated:true` in the search query.
### Parameters [#parameters]
| Name | In | Type | Required | Description |
| -------------- | ---- | ------------ | -------- | --------------- |
| `organization` | path | string(uuid) | true | Organization ID |
### Example responses [#example-responses]
> 200 Response
```json
[
{
"active_user_count": 0,
"active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
"activity_bump_ms": 0,
"agents_allowed": true,
"allow_user_autostart": true,
"allow_user_autostop": true,
"allow_user_cancel_workspace_jobs": true,
"autostart_requirement": {
"days_of_week": [
"monday"
]
},
"autostop_requirement": {
"days_of_week": [
"monday"
],
"weeks": 0
},
"build_time_stats": {
"property1": {
"p50": 123,
"p95": 146
},
"property2": {
"p50": 123,
"p95": 146
}
},
"cors_behavior": "simple",
"created_at": "2019-08-24T14:15:22Z",
"created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
"created_by_name": "string",
"default_ttl_ms": 0,
"deleted": true,
"deprecated": true,
"deprecation_message": "string",
"description": "string",
"disable_module_cache": true,
"display_name": "string",
"failure_ttl_ms": 0,
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"max_port_share_level": "owner",
"name": "string",
"organization_display_name": "string",
"organization_icon": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"organization_name": "string",
"provisioner": "terraform",
"require_active_version": true,
"time_til_autostop_notify_ms": 0,
"time_til_dormant_autodelete_ms": 0,
"time_til_dormant_ms": 0,
"updated_at": "2019-08-24T14:15:22Z",
"use_classic_parameter_flow": true
}
]
```
### Responses [#responses]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Template](/beta-docs/reference/api/schemas/#codersdktemplate) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» active_user_count` | integer | false | | Active user count is set to -1 when loading. |
| `» active_version_id` | string(uuid) | false | | |
| `» activity_bump_ms` | integer | false | | |
| `» agents_allowed` | boolean | false | | |
| `» allow_user_autostart` | boolean | false | | Allow user autostart and AllowUserAutostop are enterprise-only. Their values are only used if your license is entitled to use the advanced template scheduling feature. |
| `» allow_user_autostop` | boolean | false | | |
| `» allow_user_cancel_workspace_jobs` | boolean | false | | |
| `» autostart_requirement` | [codersdk.TemplateAutostartRequirement](/beta-docs/reference/api/schemas/#codersdktemplateautostartrequirement) | false | | |
| `»» days_of_week` | array | false | | Days of week is a list of days of the week in which autostart is allowed to happen. If no days are specified, autostart is not allowed. |
| `» autostop_requirement` | [codersdk.TemplateAutostopRequirement](/beta-docs/reference/api/schemas/#codersdktemplateautostoprequirement) | false | | Autostop requirement and AutostartRequirement are enterprise features. Its value is only used if your license is entitled to use the advanced template scheduling feature. |
| `»» days_of_week` | array | false | | Days of week is a list of days of the week on which restarts are required. Restarts happen within the user's quiet hours (in their configured timezone). If no days are specified, restarts are not required. Weekdays cannot be specified twice. |
| Restarts will only happen on weekdays in this list on weeks which line up with Weeks. | | | | |
| `»» weeks` | integer | false | | Weeks is the number of weeks between required restarts. Weeks are synced across all workspaces (and Coder deployments) using modulo math on a hardcoded epoch week of January 2nd, 2023 (the first Monday of 2023). Values of 0 or 1 indicate weekly restarts. Values of 2 indicate fortnightly restarts, etc. |
| `» build_time_stats` | [codersdk.TemplateBuildTimeStats](/beta-docs/reference/api/schemas/#codersdktemplatebuildtimestats) | false | | |
| `»» [any property]` | [codersdk.TransitionStats](/beta-docs/reference/api/schemas/#codersdktransitionstats) | false | | |
| `»»» p50` | integer | false | | |
| `»»» p95` | integer | false | | |
| `» cors_behavior` | [codersdk.CORSBehavior](/beta-docs/reference/api/schemas/#codersdkcorsbehavior) | false | | |
| `» created_at` | string(date-time) | false | | |
| `» created_by_id` | string(uuid) | false | | |
| `» created_by_name` | string | false | | |
| `» default_ttl_ms` | integer | false | | |
| `» deleted` | boolean | false | | |
| `» deprecated` | boolean | false | | |
| `» deprecation_message` | string | false | | |
| `» description` | string | false | | |
| `» disable_module_cache` | boolean | false | | Disable module cache disables the use of cached Terraform modules during provisioning. |
| `» display_name` | string | false | | |
| `» failure_ttl_ms` | integer | false | | Failure ttl ms TimeTilDormantMillis, and TimeTilDormantAutoDeleteMillis are enterprise-only. Their values are used if your license is entitled to use the advanced template scheduling feature. |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» max_port_share_level` | [codersdk.WorkspaceAgentPortShareLevel](/beta-docs/reference/api/schemas/#codersdkworkspaceagentportsharelevel) | false | | |
| `» name` | string | false | | |
| `» organization_display_name` | string | false | | |
| `» organization_icon` | string | false | | |
| `» organization_id` | string(uuid) | false | | |
| `» organization_name` | string(url) | false | | |
| `» provisioner` | string | false | | |
| `» require_active_version` | boolean | false | | Require active version mandates that workspaces are built with the active template version. |
| `» time_til_autostop_notify_ms` | integer | false | | Time til autostop notify ms is the duration before the workspace's autostop deadline at which a reminder notification is sent. 0 disables the notification. |
| `» time_til_dormant_autodelete_ms` | integer | false | | |
| `» time_til_dormant_ms` | integer | false | | |
| `» updated_at` | string(date-time) | false | | |
| `» use_classic_parameter_flow` | boolean | false | | |
#### Enumerated Values [#enumerated-values]
| Property | Value(s) |
| ---------------------- | -------------------------------------------------- |
| `cors_behavior` | `passthru`, `simple` |
| `max_port_share_level` | `authenticated`, `organization`, `owner`, `public` |
| `provisioner` | `terraform` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Create template by organization [#create-template-by-organization]
### Code samples [#code-samples-1]
```sh
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/templates \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /api/v2/organizations/{organization}/templates`
> Body parameter
```json
{
"activity_bump_ms": 0,
"agents_allowed": true,
"allow_user_autostart": true,
"allow_user_autostop": true,
"allow_user_cancel_workspace_jobs": true,
"autostart_requirement": {
"days_of_week": [
"monday"
]
},
"autostop_requirement": {
"days_of_week": [
"monday"
],
"weeks": 0
},
"cors_behavior": "simple",
"default_ttl_ms": 0,
"delete_ttl_ms": 0,
"description": "string",
"disable_everyone_group_access": true,
"display_name": "string",
"dormant_ttl_ms": 0,
"failure_ttl_ms": 0,
"icon": "string",
"max_port_share_level": "owner",
"name": "string",
"require_active_version": true,
"template_use_classic_parameter_flow": true,
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"time_til_autostop_notify_ms": 0
}
```
### Parameters [#parameters-1]
| Name | In | Type | Required | Description |
| -------------- | ---- | ------------------------------------------------------------------------------------------------- | -------- | --------------- |
| `organization` | path | string | true | Organization ID |
| `body` | body | [codersdk.CreateTemplateRequest](/beta-docs/reference/api/schemas/#codersdkcreatetemplaterequest) | true | Request body |
### Example responses [#example-responses-1]
> 200 Response
```json
{
"active_user_count": 0,
"active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
"activity_bump_ms": 0,
"agents_allowed": true,
"allow_user_autostart": true,
"allow_user_autostop": true,
"allow_user_cancel_workspace_jobs": true,
"autostart_requirement": {
"days_of_week": [
"monday"
]
},
"autostop_requirement": {
"days_of_week": [
"monday"
],
"weeks": 0
},
"build_time_stats": {
"property1": {
"p50": 123,
"p95": 146
},
"property2": {
"p50": 123,
"p95": 146
}
},
"cors_behavior": "simple",
"created_at": "2019-08-24T14:15:22Z",
"created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
"created_by_name": "string",
"default_ttl_ms": 0,
"deleted": true,
"deprecated": true,
"deprecation_message": "string",
"description": "string",
"disable_module_cache": true,
"display_name": "string",
"failure_ttl_ms": 0,
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"max_port_share_level": "owner",
"name": "string",
"organization_display_name": "string",
"organization_icon": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"organization_name": "string",
"provisioner": "terraform",
"require_active_version": true,
"time_til_autostop_notify_ms": 0,
"time_til_dormant_autodelete_ms": 0,
"time_til_dormant_ms": 0,
"updated_at": "2019-08-24T14:15:22Z",
"use_classic_parameter_flow": true
}
```
### Responses [#responses-1]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Template](/beta-docs/reference/api/schemas/#codersdktemplate) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template examples by organization [#get-template-examples-by-organization]
### Code samples [#code-samples-2]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templates/examples \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/organizations/{organization}/templates/examples`
### Parameters [#parameters-2]
| Name | In | Type | Required | Description |
| -------------- | ---- | ------------ | -------- | --------------- |
| `organization` | path | string(uuid) | true | Organization ID |
### Example responses [#example-responses-2]
> 200 Response
```json
[
{
"description": "string",
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"markdown": "string",
"name": "string",
"tags": [
"string"
],
"url": "string"
}
]
```
### Responses [#responses-2]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.TemplateExample](/beta-docs/reference/api/schemas/#codersdktemplateexample) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --------------- | ------------ | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» description` | string | false | | |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» markdown` | string | false | | |
| `» name` | string | false | | |
| `» tags` | array | false | | |
| `» url` | string | false | | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get templates by organization and template name [#get-templates-by-organization-and-template-name]
### Code samples [#code-samples-3]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templates/{templatename} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/organizations/{organization}/templates/{templatename}`
### Parameters [#parameters-3]
| Name | In | Type | Required | Description |
| -------------- | ---- | ------------ | -------- | --------------- |
| `organization` | path | string(uuid) | true | Organization ID |
| `templatename` | path | string | true | Template name |
### Example responses [#example-responses-3]
> 200 Response
```json
{
"active_user_count": 0,
"active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
"activity_bump_ms": 0,
"agents_allowed": true,
"allow_user_autostart": true,
"allow_user_autostop": true,
"allow_user_cancel_workspace_jobs": true,
"autostart_requirement": {
"days_of_week": [
"monday"
]
},
"autostop_requirement": {
"days_of_week": [
"monday"
],
"weeks": 0
},
"build_time_stats": {
"property1": {
"p50": 123,
"p95": 146
},
"property2": {
"p50": 123,
"p95": 146
}
},
"cors_behavior": "simple",
"created_at": "2019-08-24T14:15:22Z",
"created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
"created_by_name": "string",
"default_ttl_ms": 0,
"deleted": true,
"deprecated": true,
"deprecation_message": "string",
"description": "string",
"disable_module_cache": true,
"display_name": "string",
"failure_ttl_ms": 0,
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"max_port_share_level": "owner",
"name": "string",
"organization_display_name": "string",
"organization_icon": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"organization_name": "string",
"provisioner": "terraform",
"require_active_version": true,
"time_til_autostop_notify_ms": 0,
"time_til_dormant_autodelete_ms": 0,
"time_til_dormant_ms": 0,
"updated_at": "2019-08-24T14:15:22Z",
"use_classic_parameter_flow": true
}
```
### Responses [#responses-3]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Template](/beta-docs/reference/api/schemas/#codersdktemplate) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template version by organization, template, and name [#get-template-version-by-organization-template-and-name]
### Code samples [#code-samples-4]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templates/{templatename}/versions/{templateversionname} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/organizations/{organization}/templates/{templatename}/versions/{templateversionname}`
### Parameters [#parameters-4]
| Name | In | Type | Required | Description |
| --------------------- | ---- | ------------ | -------- | --------------------- |
| `organization` | path | string(uuid) | true | Organization ID |
| `templatename` | path | string | true | Template name |
| `templateversionname` | path | string | true | Template version name |
### Example responses [#example-responses-4]
> 200 Response
```json
{
"archived": true,
"created_at": "2019-08-24T14:15:22Z",
"created_by": {
"avatar_url": "http://example.com",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"username": "string"
},
"has_external_agent": true,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"job": {
"available_workers": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"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",
"initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
"input": {
"error": "string",
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
"logs_overflowed": true,
"metadata": {
"template_display_name": "string",
"template_icon": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"template_name": "string",
"template_version_name": "string",
"workspace_build_transition": "start",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"workspace_name": "string"
},
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"queue_position": 0,
"queue_size": 0,
"started_at": "2019-08-24T14:15:22Z",
"status": "pending",
"tags": {
"property1": "string",
"property2": "string"
},
"type": "template_version_import",
"worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b",
"worker_name": "string"
},
"matched_provisioners": {
"available": 0,
"count": 0,
"most_recently_seen": "2019-08-24T14:15:22Z"
},
"message": "string",
"name": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"readme": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"updated_at": "2019-08-24T14:15:22Z",
"warnings": [
"UNSUPPORTED_WORKSPACES"
]
}
```
### Responses [#responses-4]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.TemplateVersion](/beta-docs/reference/api/schemas/#codersdktemplateversion) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get previous template version by organization, template, and name [#get-previous-template-version-by-organization-template-and-name]
### Code samples [#code-samples-5]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templates/{templatename}/versions/{templateversionname}/previous \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/organizations/{organization}/templates/{templatename}/versions/{templateversionname}/previous`
### Parameters [#parameters-5]
| Name | In | Type | Required | Description |
| --------------------- | ---- | ------------ | -------- | --------------------- |
| `organization` | path | string(uuid) | true | Organization ID |
| `templatename` | path | string | true | Template name |
| `templateversionname` | path | string | true | Template version name |
### Example responses [#example-responses-5]
> 200 Response
```json
{
"archived": true,
"created_at": "2019-08-24T14:15:22Z",
"created_by": {
"avatar_url": "http://example.com",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"username": "string"
},
"has_external_agent": true,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"job": {
"available_workers": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"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",
"initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
"input": {
"error": "string",
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
"logs_overflowed": true,
"metadata": {
"template_display_name": "string",
"template_icon": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"template_name": "string",
"template_version_name": "string",
"workspace_build_transition": "start",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"workspace_name": "string"
},
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"queue_position": 0,
"queue_size": 0,
"started_at": "2019-08-24T14:15:22Z",
"status": "pending",
"tags": {
"property1": "string",
"property2": "string"
},
"type": "template_version_import",
"worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b",
"worker_name": "string"
},
"matched_provisioners": {
"available": 0,
"count": 0,
"most_recently_seen": "2019-08-24T14:15:22Z"
},
"message": "string",
"name": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"readme": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"updated_at": "2019-08-24T14:15:22Z",
"warnings": [
"UNSUPPORTED_WORKSPACES"
]
}
```
### Responses [#responses-5]
| Status | Meaning | Description | Schema |
| ------ | --------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.TemplateVersion](/beta-docs/reference/api/schemas/#codersdktemplateversion) |
| 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](/beta-docs/reference/api/authentication/).
## Create template version by organization [#create-template-version-by-organization]
### Code samples [#code-samples-6]
```sh
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/templateversions \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /api/v2/organizations/{organization}/templateversions`
> Body parameter
```json
{
"example_id": "string",
"file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"message": "string",
"name": "string",
"provisioner": "terraform",
"storage_method": "file",
"tags": {
"property1": "string",
"property2": "string"
},
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"user_variable_values": [
{
"name": "string",
"value": "string"
}
]
}
```
### Parameters [#parameters-6]
| Name | In | Type | Required | Description |
| -------------- | ---- | --------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------- |
| `organization` | path | string(uuid) | true | Organization ID |
| `body` | body | [codersdk.CreateTemplateVersionRequest](/beta-docs/reference/api/schemas/#codersdkcreatetemplateversionrequest) | true | Create template version request |
### Example responses [#example-responses-6]
> 201 Response
```json
{
"archived": true,
"created_at": "2019-08-24T14:15:22Z",
"created_by": {
"avatar_url": "http://example.com",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"username": "string"
},
"has_external_agent": true,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"job": {
"available_workers": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"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",
"initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
"input": {
"error": "string",
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
"logs_overflowed": true,
"metadata": {
"template_display_name": "string",
"template_icon": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"template_name": "string",
"template_version_name": "string",
"workspace_build_transition": "start",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"workspace_name": "string"
},
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"queue_position": 0,
"queue_size": 0,
"started_at": "2019-08-24T14:15:22Z",
"status": "pending",
"tags": {
"property1": "string",
"property2": "string"
},
"type": "template_version_import",
"worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b",
"worker_name": "string"
},
"matched_provisioners": {
"available": 0,
"count": 0,
"most_recently_seen": "2019-08-24T14:15:22Z"
},
"message": "string",
"name": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"readme": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"updated_at": "2019-08-24T14:15:22Z",
"warnings": [
"UNSUPPORTED_WORKSPACES"
]
}
```
### Responses [#responses-6]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------- |
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.TemplateVersion](/beta-docs/reference/api/schemas/#codersdktemplateversion) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get all templates [#get-all-templates]
### Code samples [#code-samples-7]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templates \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templates`
Returns a list of templates.
By default, only non-deprecated templates are returned.
To include deprecated templates, specify `deprecated:true` in the search query.
### Example responses [#example-responses-7]
> 200 Response
```json
[
{
"active_user_count": 0,
"active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
"activity_bump_ms": 0,
"agents_allowed": true,
"allow_user_autostart": true,
"allow_user_autostop": true,
"allow_user_cancel_workspace_jobs": true,
"autostart_requirement": {
"days_of_week": [
"monday"
]
},
"autostop_requirement": {
"days_of_week": [
"monday"
],
"weeks": 0
},
"build_time_stats": {
"property1": {
"p50": 123,
"p95": 146
},
"property2": {
"p50": 123,
"p95": 146
}
},
"cors_behavior": "simple",
"created_at": "2019-08-24T14:15:22Z",
"created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
"created_by_name": "string",
"default_ttl_ms": 0,
"deleted": true,
"deprecated": true,
"deprecation_message": "string",
"description": "string",
"disable_module_cache": true,
"display_name": "string",
"failure_ttl_ms": 0,
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"max_port_share_level": "owner",
"name": "string",
"organization_display_name": "string",
"organization_icon": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"organization_name": "string",
"provisioner": "terraform",
"require_active_version": true,
"time_til_autostop_notify_ms": 0,
"time_til_dormant_autodelete_ms": 0,
"time_til_dormant_ms": 0,
"updated_at": "2019-08-24T14:15:22Z",
"use_classic_parameter_flow": true
}
]
```
### Responses [#responses-7]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Template](/beta-docs/reference/api/schemas/#codersdktemplate) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» active_user_count` | integer | false | | Active user count is set to -1 when loading. |
| `» active_version_id` | string(uuid) | false | | |
| `» activity_bump_ms` | integer | false | | |
| `» agents_allowed` | boolean | false | | |
| `» allow_user_autostart` | boolean | false | | Allow user autostart and AllowUserAutostop are enterprise-only. Their values are only used if your license is entitled to use the advanced template scheduling feature. |
| `» allow_user_autostop` | boolean | false | | |
| `» allow_user_cancel_workspace_jobs` | boolean | false | | |
| `» autostart_requirement` | [codersdk.TemplateAutostartRequirement](/beta-docs/reference/api/schemas/#codersdktemplateautostartrequirement) | false | | |
| `»» days_of_week` | array | false | | Days of week is a list of days of the week in which autostart is allowed to happen. If no days are specified, autostart is not allowed. |
| `» autostop_requirement` | [codersdk.TemplateAutostopRequirement](/beta-docs/reference/api/schemas/#codersdktemplateautostoprequirement) | false | | Autostop requirement and AutostartRequirement are enterprise features. Its value is only used if your license is entitled to use the advanced template scheduling feature. |
| `»» days_of_week` | array | false | | Days of week is a list of days of the week on which restarts are required. Restarts happen within the user's quiet hours (in their configured timezone). If no days are specified, restarts are not required. Weekdays cannot be specified twice. |
| Restarts will only happen on weekdays in this list on weeks which line up with Weeks. | | | | |
| `»» weeks` | integer | false | | Weeks is the number of weeks between required restarts. Weeks are synced across all workspaces (and Coder deployments) using modulo math on a hardcoded epoch week of January 2nd, 2023 (the first Monday of 2023). Values of 0 or 1 indicate weekly restarts. Values of 2 indicate fortnightly restarts, etc. |
| `» build_time_stats` | [codersdk.TemplateBuildTimeStats](/beta-docs/reference/api/schemas/#codersdktemplatebuildtimestats) | false | | |
| `»» [any property]` | [codersdk.TransitionStats](/beta-docs/reference/api/schemas/#codersdktransitionstats) | false | | |
| `»»» p50` | integer | false | | |
| `»»» p95` | integer | false | | |
| `» cors_behavior` | [codersdk.CORSBehavior](/beta-docs/reference/api/schemas/#codersdkcorsbehavior) | false | | |
| `» created_at` | string(date-time) | false | | |
| `» created_by_id` | string(uuid) | false | | |
| `» created_by_name` | string | false | | |
| `» default_ttl_ms` | integer | false | | |
| `» deleted` | boolean | false | | |
| `» deprecated` | boolean | false | | |
| `» deprecation_message` | string | false | | |
| `» description` | string | false | | |
| `» disable_module_cache` | boolean | false | | Disable module cache disables the use of cached Terraform modules during provisioning. |
| `» display_name` | string | false | | |
| `» failure_ttl_ms` | integer | false | | Failure ttl ms TimeTilDormantMillis, and TimeTilDormantAutoDeleteMillis are enterprise-only. Their values are used if your license is entitled to use the advanced template scheduling feature. |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» max_port_share_level` | [codersdk.WorkspaceAgentPortShareLevel](/beta-docs/reference/api/schemas/#codersdkworkspaceagentportsharelevel) | false | | |
| `» name` | string | false | | |
| `» organization_display_name` | string | false | | |
| `» organization_icon` | string | false | | |
| `» organization_id` | string(uuid) | false | | |
| `» organization_name` | string(url) | false | | |
| `» provisioner` | string | false | | |
| `» require_active_version` | boolean | false | | Require active version mandates that workspaces are built with the active template version. |
| `» time_til_autostop_notify_ms` | integer | false | | Time til autostop notify ms is the duration before the workspace's autostop deadline at which a reminder notification is sent. 0 disables the notification. |
| `» time_til_dormant_autodelete_ms` | integer | false | | |
| `» time_til_dormant_ms` | integer | false | | |
| `» updated_at` | string(date-time) | false | | |
| `» use_classic_parameter_flow` | boolean | false | | |
#### Enumerated Values [#enumerated-values-1]
| Property | Value(s) |
| ---------------------- | -------------------------------------------------- |
| `cors_behavior` | `passthru`, `simple` |
| `max_port_share_level` | `authenticated`, `organization`, `owner`, `public` |
| `provisioner` | `terraform` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template examples [#get-template-examples]
### Code samples [#code-samples-8]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templates/examples \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templates/examples`
### Example responses [#example-responses-8]
> 200 Response
```json
[
{
"description": "string",
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"markdown": "string",
"name": "string",
"tags": [
"string"
],
"url": "string"
}
]
```
### Responses [#responses-8]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.TemplateExample](/beta-docs/reference/api/schemas/#codersdktemplateexample) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --------------- | ------------ | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» description` | string | false | | |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» markdown` | string | false | | |
| `» name` | string | false | | |
| `» tags` | array | false | | |
| `» url` | string | false | | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template settings by ID [#get-template-settings-by-id]
### Code samples [#code-samples-9]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templates/{template} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templates/{template}`
### Parameters [#parameters-7]
| Name | In | Type | Required | Description |
| ---------- | ---- | ------------ | -------- | ----------- |
| `template` | path | string(uuid) | true | Template ID |
### Example responses [#example-responses-9]
> 200 Response
```json
{
"active_user_count": 0,
"active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
"activity_bump_ms": 0,
"agents_allowed": true,
"allow_user_autostart": true,
"allow_user_autostop": true,
"allow_user_cancel_workspace_jobs": true,
"autostart_requirement": {
"days_of_week": [
"monday"
]
},
"autostop_requirement": {
"days_of_week": [
"monday"
],
"weeks": 0
},
"build_time_stats": {
"property1": {
"p50": 123,
"p95": 146
},
"property2": {
"p50": 123,
"p95": 146
}
},
"cors_behavior": "simple",
"created_at": "2019-08-24T14:15:22Z",
"created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
"created_by_name": "string",
"default_ttl_ms": 0,
"deleted": true,
"deprecated": true,
"deprecation_message": "string",
"description": "string",
"disable_module_cache": true,
"display_name": "string",
"failure_ttl_ms": 0,
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"max_port_share_level": "owner",
"name": "string",
"organization_display_name": "string",
"organization_icon": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"organization_name": "string",
"provisioner": "terraform",
"require_active_version": true,
"time_til_autostop_notify_ms": 0,
"time_til_dormant_autodelete_ms": 0,
"time_til_dormant_ms": 0,
"updated_at": "2019-08-24T14:15:22Z",
"use_classic_parameter_flow": true
}
```
### Responses [#responses-9]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Template](/beta-docs/reference/api/schemas/#codersdktemplate) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Delete template by ID [#delete-template-by-id]
### Code samples [#code-samples-10]
```sh
# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/templates/{template} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`DELETE /api/v2/templates/{template}`
### Parameters [#parameters-8]
| Name | In | Type | Required | Description |
| ---------- | ---- | ------------ | -------- | ----------- |
| `template` | path | string(uuid) | true | Template ID |
### Example responses [#example-responses-10]
> 200 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses-10]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Update template settings by ID [#update-template-settings-by-id]
### Code samples [#code-samples-11]
```sh
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/templates/{template} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PATCH /api/v2/templates/{template}`
> Body parameter
```json
{
"activity_bump_ms": 0,
"agents_allowed": true,
"allow_user_autostart": true,
"allow_user_autostop": true,
"allow_user_cancel_workspace_jobs": true,
"autostart_requirement": {
"days_of_week": [
"monday"
]
},
"autostop_requirement": {
"days_of_week": [
"monday"
],
"weeks": 0
},
"cors_behavior": "simple",
"default_ttl_ms": 0,
"deprecation_message": "string",
"description": "string",
"disable_everyone_group_access": true,
"disable_module_cache": true,
"display_name": "string",
"failure_ttl_ms": 0,
"icon": "string",
"max_port_share_level": "owner",
"name": "string",
"require_active_version": true,
"time_til_autostop_notify_ms": 0,
"time_til_dormant_autodelete_ms": 0,
"time_til_dormant_ms": 0,
"update_workspace_dormant_at": true,
"update_workspace_last_used_at": true,
"use_classic_parameter_flow": true
}
```
### Parameters [#parameters-9]
| Name | In | Type | Required | Description |
| ---------- | ---- | ------------------------------------------------------------------------------------------- | -------- | ------------------------------- |
| `template` | path | string(uuid) | true | Template ID |
| `body` | body | [codersdk.UpdateTemplateMeta](/beta-docs/reference/api/schemas/#codersdkupdatetemplatemeta) | true | Patch template settings request |
### Example responses [#example-responses-11]
> 200 Response
```json
{
"active_user_count": 0,
"active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
"activity_bump_ms": 0,
"agents_allowed": true,
"allow_user_autostart": true,
"allow_user_autostop": true,
"allow_user_cancel_workspace_jobs": true,
"autostart_requirement": {
"days_of_week": [
"monday"
]
},
"autostop_requirement": {
"days_of_week": [
"monday"
],
"weeks": 0
},
"build_time_stats": {
"property1": {
"p50": 123,
"p95": 146
},
"property2": {
"p50": 123,
"p95": 146
}
},
"cors_behavior": "simple",
"created_at": "2019-08-24T14:15:22Z",
"created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
"created_by_name": "string",
"default_ttl_ms": 0,
"deleted": true,
"deprecated": true,
"deprecation_message": "string",
"description": "string",
"disable_module_cache": true,
"display_name": "string",
"failure_ttl_ms": 0,
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"max_port_share_level": "owner",
"name": "string",
"organization_display_name": "string",
"organization_icon": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"organization_name": "string",
"provisioner": "terraform",
"require_active_version": true,
"time_til_autostop_notify_ms": 0,
"time_til_dormant_autodelete_ms": 0,
"time_til_dormant_ms": 0,
"updated_at": "2019-08-24T14:15:22Z",
"use_classic_parameter_flow": true
}
```
### Responses [#responses-11]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Template](/beta-docs/reference/api/schemas/#codersdktemplate) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template DAUs by ID [#get-template-daus-by-id]
### Code samples [#code-samples-12]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templates/{template}/daus \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templates/{template}/daus`
### Parameters [#parameters-10]
| Name | In | Type | Required | Description |
| ---------- | ---- | ------------ | -------- | ----------- |
| `template` | path | string(uuid) | true | Template ID |
### Example responses [#example-responses-12]
> 200 Response
```json
{
"entries": [
{
"amount": 0,
"date": "string"
}
],
"tz_hour_offset": 0
}
```
### Responses [#responses-12]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.DAUsResponse](/beta-docs/reference/api/schemas/#codersdkdausresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## List template versions by template ID [#list-template-versions-by-template-id]
### Code samples [#code-samples-13]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templates/{template}/versions \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templates/{template}/versions`
### Parameters [#parameters-11]
| Name | In | Type | Required | Description |
| ------------------ | ----- | ------------ | -------- | ------------------------------------- |
| `template` | path | string(uuid) | true | Template ID |
| `after_id` | query | string(uuid) | false | After ID |
| `include_archived` | query | boolean | false | Include archived versions in the list |
| `limit` | query | integer | false | Page limit |
| `offset` | query | integer | false | Page offset |
### Example responses [#example-responses-13]
> 200 Response
```json
[
{
"archived": true,
"created_at": "2019-08-24T14:15:22Z",
"created_by": {
"avatar_url": "http://example.com",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"username": "string"
},
"has_external_agent": true,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"job": {
"available_workers": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"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",
"initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
"input": {
"error": "string",
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
"logs_overflowed": true,
"metadata": {
"template_display_name": "string",
"template_icon": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"template_name": "string",
"template_version_name": "string",
"workspace_build_transition": "start",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"workspace_name": "string"
},
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"queue_position": 0,
"queue_size": 0,
"started_at": "2019-08-24T14:15:22Z",
"status": "pending",
"tags": {
"property1": "string",
"property2": "string"
},
"type": "template_version_import",
"worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b",
"worker_name": "string"
},
"matched_provisioners": {
"available": 0,
"count": 0,
"most_recently_seen": "2019-08-24T14:15:22Z"
},
"message": "string",
"name": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"readme": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"updated_at": "2019-08-24T14:15:22Z",
"warnings": [
"UNSUPPORTED_WORKSPACES"
]
}
]
```
### Responses [#responses-13]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.TemplateVersion](/beta-docs/reference/api/schemas/#codersdktemplateversion) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------------------------- | --------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» archived` | boolean | false | | |
| `» created_at` | string(date-time) | false | | |
| `» created_by` | [codersdk.MinimalUser](/beta-docs/reference/api/schemas/#codersdkminimaluser) | false | | |
| `»» avatar_url` | string(uri) | false | | |
| `»» id` | string(uuid) | true | | |
| `»» name` | string | false | | |
| `»» username` | string | true | | |
| `» has_external_agent` | boolean | false | | |
| `» id` | string(uuid) | false | | |
| `» job` | [codersdk.ProvisionerJob](/beta-docs/reference/api/schemas/#codersdkprovisionerjob) | false | | |
| `»» available_workers` | array | false | | |
| `»» canceled_at` | string(date-time) | false | | |
| `»» completed_at` | string(date-time) | false | | |
| `»» created_at` | string(date-time) | false | | |
| `»» error` | string | false | | |
| `»» error_code` | [codersdk.JobErrorCode](/beta-docs/reference/api/schemas/#codersdkjoberrorcode) | false | | |
| `»» file_id` | string(uuid) | false | | |
| `»» id` | string(uuid) | false | | |
| `»» initiator_id` | string(uuid) | false | | |
| `»» input` | [codersdk.ProvisionerJobInput](/beta-docs/reference/api/schemas/#codersdkprovisionerjobinput) | false | | |
| `»»» error` | string | false | | |
| `»»» template_version_id` | string(uuid) | false | | |
| `»»» workspace_build_id` | string(uuid) | false | | |
| `»» logs_overflowed` | boolean | false | | |
| `»» metadata` | [codersdk.ProvisionerJobMetadata](/beta-docs/reference/api/schemas/#codersdkprovisionerjobmetadata) | false | | |
| `»»» template_display_name` | string | false | | |
| `»»» template_icon` | string | false | | |
| `»»» template_id` | string(uuid) | false | | |
| `»»» template_name` | string | false | | |
| `»»» template_version_name` | string | false | | |
| `»»» workspace_build_transition` | [codersdk.WorkspaceTransition](/beta-docs/reference/api/schemas/#codersdkworkspacetransition) | false | | |
| `»»» workspace_id` | string(uuid) | false | | |
| `»»» workspace_name` | string | false | | |
| `»» organization_id` | string(uuid) | false | | |
| `»» queue_position` | integer | false | | |
| `»» queue_size` | integer | false | | |
| `»» started_at` | string(date-time) | false | | |
| `»» status` | [codersdk.ProvisionerJobStatus](/beta-docs/reference/api/schemas/#codersdkprovisionerjobstatus) | false | | |
| `»» tags` | object | false | | |
| `»»» [any property]` | string | false | | |
| `»» type` | [codersdk.ProvisionerJobType](/beta-docs/reference/api/schemas/#codersdkprovisionerjobtype) | false | | |
| `»» worker_id` | string(uuid) | false | | |
| `»» worker_name` | string | false | | |
| `» matched_provisioners` | [codersdk.MatchedProvisioners](/beta-docs/reference/api/schemas/#codersdkmatchedprovisioners) | false | | |
| `»» available` | integer | false | | Available is the number of provisioner daemons that are available to take jobs. This may be less than the count if some provisioners are busy or have been stopped. |
| `»» count` | integer | false | | Count is the number of provisioner daemons that matched the given tags. If the count is 0, it means no provisioner daemons matched the requested tags. |
| `»» most_recently_seen` | string(date-time) | false | | Most recently seen is the most recently seen time of the set of matched provisioners. If no provisioners matched, this field will be null. |
| `» message` | string | false | | |
| `» name` | string | false | | |
| `» organization_id` | string(uuid) | false | | |
| `» readme` | string | false | | |
| `» template_id` | string(uuid) | false | | |
| `» updated_at` | string(date-time) | false | | |
| `» warnings` | array | false | | |
#### Enumerated Values [#enumerated-values-2]
| Property | Value(s) |
| ---------------------------- | ------------------------------------------------------------------------ |
| `error_code` | `INSUFFICIENT_QUOTA`, `REQUIRED_TEMPLATE_VARIABLES` |
| `workspace_build_transition` | `delete`, `start`, `stop` |
| `status` | `canceled`, `canceling`, `failed`, `pending`, `running`, `succeeded` |
| `type` | `template_version_dry_run`, `template_version_import`, `workspace_build` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Update active template version by template ID [#update-active-template-version-by-template-id]
### Code samples [#code-samples-14]
```sh
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/templates/{template}/versions \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PATCH /api/v2/templates/{template}/versions`
> Body parameter
```json
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
```
### Parameters [#parameters-12]
| Name | In | Type | Required | Description |
| ---------- | ---- | ------------------------------------------------------------------------------------------------------------- | -------- | ------------------------- |
| `template` | path | string(uuid) | true | Template ID |
| `body` | body | [codersdk.UpdateActiveTemplateVersion](/beta-docs/reference/api/schemas/#codersdkupdateactivetemplateversion) | true | Modified template version |
### Example responses [#example-responses-14]
> 200 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses-14]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Archive template unused versions by template id [#archive-template-unused-versions-by-template-id]
### Code samples [#code-samples-15]
```sh
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/templates/{template}/versions/archive \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /api/v2/templates/{template}/versions/archive`
> Body parameter
```json
{
"all": true
}
```
### Parameters [#parameters-13]
| Name | In | Type | Required | Description |
| ---------- | ---- | ------------------------------------------------------------------------------------------------------------------- | -------- | --------------- |
| `template` | path | string(uuid) | true | Template ID |
| `body` | body | [codersdk.ArchiveTemplateVersionsRequest](/beta-docs/reference/api/schemas/#codersdkarchivetemplateversionsrequest) | true | Archive request |
### Example responses [#example-responses-15]
> 200 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses-15]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template version by template ID and name [#get-template-version-by-template-id-and-name]
### Code samples [#code-samples-16]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templates/{template}/versions/{templateversionname} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templates/{template}/versions/{templateversionname}`
### Parameters [#parameters-14]
| Name | In | Type | Required | Description |
| --------------------- | ---- | ------------ | -------- | --------------------- |
| `template` | path | string(uuid) | true | Template ID |
| `templateversionname` | path | string | true | Template version name |
### Example responses [#example-responses-16]
> 200 Response
```json
[
{
"archived": true,
"created_at": "2019-08-24T14:15:22Z",
"created_by": {
"avatar_url": "http://example.com",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"username": "string"
},
"has_external_agent": true,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"job": {
"available_workers": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"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",
"initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
"input": {
"error": "string",
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
"logs_overflowed": true,
"metadata": {
"template_display_name": "string",
"template_icon": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"template_name": "string",
"template_version_name": "string",
"workspace_build_transition": "start",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"workspace_name": "string"
},
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"queue_position": 0,
"queue_size": 0,
"started_at": "2019-08-24T14:15:22Z",
"status": "pending",
"tags": {
"property1": "string",
"property2": "string"
},
"type": "template_version_import",
"worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b",
"worker_name": "string"
},
"matched_provisioners": {
"available": 0,
"count": 0,
"most_recently_seen": "2019-08-24T14:15:22Z"
},
"message": "string",
"name": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"readme": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"updated_at": "2019-08-24T14:15:22Z",
"warnings": [
"UNSUPPORTED_WORKSPACES"
]
}
]
```
### Responses [#responses-16]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.TemplateVersion](/beta-docs/reference/api/schemas/#codersdktemplateversion) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------------------------- | --------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» archived` | boolean | false | | |
| `» created_at` | string(date-time) | false | | |
| `» created_by` | [codersdk.MinimalUser](/beta-docs/reference/api/schemas/#codersdkminimaluser) | false | | |
| `»» avatar_url` | string(uri) | false | | |
| `»» id` | string(uuid) | true | | |
| `»» name` | string | false | | |
| `»» username` | string | true | | |
| `» has_external_agent` | boolean | false | | |
| `» id` | string(uuid) | false | | |
| `» job` | [codersdk.ProvisionerJob](/beta-docs/reference/api/schemas/#codersdkprovisionerjob) | false | | |
| `»» available_workers` | array | false | | |
| `»» canceled_at` | string(date-time) | false | | |
| `»» completed_at` | string(date-time) | false | | |
| `»» created_at` | string(date-time) | false | | |
| `»» error` | string | false | | |
| `»» error_code` | [codersdk.JobErrorCode](/beta-docs/reference/api/schemas/#codersdkjoberrorcode) | false | | |
| `»» file_id` | string(uuid) | false | | |
| `»» id` | string(uuid) | false | | |
| `»» initiator_id` | string(uuid) | false | | |
| `»» input` | [codersdk.ProvisionerJobInput](/beta-docs/reference/api/schemas/#codersdkprovisionerjobinput) | false | | |
| `»»» error` | string | false | | |
| `»»» template_version_id` | string(uuid) | false | | |
| `»»» workspace_build_id` | string(uuid) | false | | |
| `»» logs_overflowed` | boolean | false | | |
| `»» metadata` | [codersdk.ProvisionerJobMetadata](/beta-docs/reference/api/schemas/#codersdkprovisionerjobmetadata) | false | | |
| `»»» template_display_name` | string | false | | |
| `»»» template_icon` | string | false | | |
| `»»» template_id` | string(uuid) | false | | |
| `»»» template_name` | string | false | | |
| `»»» template_version_name` | string | false | | |
| `»»» workspace_build_transition` | [codersdk.WorkspaceTransition](/beta-docs/reference/api/schemas/#codersdkworkspacetransition) | false | | |
| `»»» workspace_id` | string(uuid) | false | | |
| `»»» workspace_name` | string | false | | |
| `»» organization_id` | string(uuid) | false | | |
| `»» queue_position` | integer | false | | |
| `»» queue_size` | integer | false | | |
| `»» started_at` | string(date-time) | false | | |
| `»» status` | [codersdk.ProvisionerJobStatus](/beta-docs/reference/api/schemas/#codersdkprovisionerjobstatus) | false | | |
| `»» tags` | object | false | | |
| `»»» [any property]` | string | false | | |
| `»» type` | [codersdk.ProvisionerJobType](/beta-docs/reference/api/schemas/#codersdkprovisionerjobtype) | false | | |
| `»» worker_id` | string(uuid) | false | | |
| `»» worker_name` | string | false | | |
| `» matched_provisioners` | [codersdk.MatchedProvisioners](/beta-docs/reference/api/schemas/#codersdkmatchedprovisioners) | false | | |
| `»» available` | integer | false | | Available is the number of provisioner daemons that are available to take jobs. This may be less than the count if some provisioners are busy or have been stopped. |
| `»» count` | integer | false | | Count is the number of provisioner daemons that matched the given tags. If the count is 0, it means no provisioner daemons matched the requested tags. |
| `»» most_recently_seen` | string(date-time) | false | | Most recently seen is the most recently seen time of the set of matched provisioners. If no provisioners matched, this field will be null. |
| `» message` | string | false | | |
| `» name` | string | false | | |
| `» organization_id` | string(uuid) | false | | |
| `» readme` | string | false | | |
| `» template_id` | string(uuid) | false | | |
| `» updated_at` | string(date-time) | false | | |
| `» warnings` | array | false | | |
#### Enumerated Values [#enumerated-values-3]
| Property | Value(s) |
| ---------------------------- | ------------------------------------------------------------------------ |
| `error_code` | `INSUFFICIENT_QUOTA`, `REQUIRED_TEMPLATE_VARIABLES` |
| `workspace_build_transition` | `delete`, `start`, `stop` |
| `status` | `canceled`, `canceling`, `failed`, `pending`, `running`, `succeeded` |
| `type` | `template_version_dry_run`, `template_version_import`, `workspace_build` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template version by ID [#get-template-version-by-id]
### Code samples [#code-samples-17]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}`
### Parameters [#parameters-15]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Example responses [#example-responses-17]
> 200 Response
```json
{
"archived": true,
"created_at": "2019-08-24T14:15:22Z",
"created_by": {
"avatar_url": "http://example.com",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"username": "string"
},
"has_external_agent": true,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"job": {
"available_workers": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"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",
"initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
"input": {
"error": "string",
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
"logs_overflowed": true,
"metadata": {
"template_display_name": "string",
"template_icon": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"template_name": "string",
"template_version_name": "string",
"workspace_build_transition": "start",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"workspace_name": "string"
},
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"queue_position": 0,
"queue_size": 0,
"started_at": "2019-08-24T14:15:22Z",
"status": "pending",
"tags": {
"property1": "string",
"property2": "string"
},
"type": "template_version_import",
"worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b",
"worker_name": "string"
},
"matched_provisioners": {
"available": 0,
"count": 0,
"most_recently_seen": "2019-08-24T14:15:22Z"
},
"message": "string",
"name": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"readme": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"updated_at": "2019-08-24T14:15:22Z",
"warnings": [
"UNSUPPORTED_WORKSPACES"
]
}
```
### Responses [#responses-17]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.TemplateVersion](/beta-docs/reference/api/schemas/#codersdktemplateversion) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Patch template version by ID [#patch-template-version-by-id]
### Code samples [#code-samples-18]
```sh
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/templateversions/{templateversion} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PATCH /api/v2/templateversions/{templateversion}`
> Body parameter
```json
{
"message": "string",
"name": "string"
}
```
### Parameters [#parameters-16]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------ |
| `templateversion` | path | string(uuid) | true | Template version ID |
| `body` | body | [codersdk.PatchTemplateVersionRequest](/beta-docs/reference/api/schemas/#codersdkpatchtemplateversionrequest) | true | Patch template version request |
### Example responses [#example-responses-18]
> 200 Response
```json
{
"archived": true,
"created_at": "2019-08-24T14:15:22Z",
"created_by": {
"avatar_url": "http://example.com",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"username": "string"
},
"has_external_agent": true,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"job": {
"available_workers": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"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",
"initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
"input": {
"error": "string",
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
"logs_overflowed": true,
"metadata": {
"template_display_name": "string",
"template_icon": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"template_name": "string",
"template_version_name": "string",
"workspace_build_transition": "start",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"workspace_name": "string"
},
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"queue_position": 0,
"queue_size": 0,
"started_at": "2019-08-24T14:15:22Z",
"status": "pending",
"tags": {
"property1": "string",
"property2": "string"
},
"type": "template_version_import",
"worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b",
"worker_name": "string"
},
"matched_provisioners": {
"available": 0,
"count": 0,
"most_recently_seen": "2019-08-24T14:15:22Z"
},
"message": "string",
"name": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"readme": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"updated_at": "2019-08-24T14:15:22Z",
"warnings": [
"UNSUPPORTED_WORKSPACES"
]
}
```
### Responses [#responses-18]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.TemplateVersion](/beta-docs/reference/api/schemas/#codersdktemplateversion) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Archive template version [#archive-template-version]
### Code samples [#code-samples-19]
```sh
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/templateversions/{templateversion}/archive \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /api/v2/templateversions/{templateversion}/archive`
### Parameters [#parameters-17]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Example responses [#example-responses-19]
> 200 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses-19]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Cancel template version by ID [#cancel-template-version-by-id]
### Code samples [#code-samples-20]
```sh
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/templateversions/{templateversion}/cancel \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PATCH /api/v2/templateversions/{templateversion}/cancel`
### Parameters [#parameters-18]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Example responses [#example-responses-20]
> 200 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses-20]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Create template version dry-run [#create-template-version-dry-run]
### Code samples [#code-samples-21]
```sh
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/templateversions/{templateversion}/dry-run \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /api/v2/templateversions/{templateversion}/dry-run`
> Body parameter
```json
{
"rich_parameter_values": [
{
"name": "string",
"value": "string"
}
],
"user_variable_values": [
{
"name": "string",
"value": "string"
}
],
"workspace_name": "string"
}
```
### Parameters [#parameters-19]
| Name | In | Type | Required | Description |
| ----------------- | ---- | --------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
| `body` | body | [codersdk.CreateTemplateVersionDryRunRequest](/beta-docs/reference/api/schemas/#codersdkcreatetemplateversiondryrunrequest) | true | Dry-run request |
### Example responses [#example-responses-21]
> 201 Response
```json
{
"available_workers": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"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",
"initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
"input": {
"error": "string",
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
"logs_overflowed": true,
"metadata": {
"template_display_name": "string",
"template_icon": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"template_name": "string",
"template_version_name": "string",
"workspace_build_transition": "start",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"workspace_name": "string"
},
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"queue_position": 0,
"queue_size": 0,
"started_at": "2019-08-24T14:15:22Z",
"status": "pending",
"tags": {
"property1": "string",
"property2": "string"
},
"type": "template_version_import",
"worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b",
"worker_name": "string"
}
```
### Responses [#responses-21]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------ | ----------- | ----------------------------------------------------------------------------------- |
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.ProvisionerJob](/beta-docs/reference/api/schemas/#codersdkprovisionerjob) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template version dry-run by job ID [#get-template-version-dry-run-by-job-id]
### Code samples [#code-samples-22]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/dry-run/{jobID} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/dry-run/{jobID}`
### Parameters [#parameters-20]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
| `jobID` | path | string(uuid) | true | Job ID |
### Example responses [#example-responses-22]
> 200 Response
```json
{
"available_workers": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"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",
"initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
"input": {
"error": "string",
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
"logs_overflowed": true,
"metadata": {
"template_display_name": "string",
"template_icon": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"template_name": "string",
"template_version_name": "string",
"workspace_build_transition": "start",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"workspace_name": "string"
},
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"queue_position": 0,
"queue_size": 0,
"started_at": "2019-08-24T14:15:22Z",
"status": "pending",
"tags": {
"property1": "string",
"property2": "string"
},
"type": "template_version_import",
"worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b",
"worker_name": "string"
}
```
### Responses [#responses-22]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.ProvisionerJob](/beta-docs/reference/api/schemas/#codersdkprovisionerjob) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Cancel template version dry-run by job ID [#cancel-template-version-dry-run-by-job-id]
### Code samples [#code-samples-23]
```sh
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/templateversions/{templateversion}/dry-run/{jobID}/cancel \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PATCH /api/v2/templateversions/{templateversion}/dry-run/{jobID}/cancel`
### Parameters [#parameters-21]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `jobID` | path | string(uuid) | true | Job ID |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Example responses [#example-responses-23]
> 200 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses-23]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template version dry-run logs by job ID [#get-template-version-dry-run-logs-by-job-id]
### Code samples [#code-samples-24]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/dry-run/{jobID}/logs \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/dry-run/{jobID}/logs`
### Parameters [#parameters-22]
| Name | In | Type | Required | Description |
| ----------------- | ----- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
| `jobID` | path | string(uuid) | true | Job ID |
| `before` | query | integer | false | Before Unix timestamp |
| `after` | query | integer | false | After Unix timestamp |
| `follow` | query | boolean | false | Follow log stream |
| `format` | query | string | false | Log output format. Accepted: 'json' (default), 'text' (plain text with RFC3339 timestamps and ANSI colors). Not supported with follow=true. |
#### Enumerated Values [#enumerated-values-4]
| Parameter | Value(s) |
| --------- | -------------- |
| `format` | `json`, `text` |
### Example responses [#example-responses-24]
> 200 Response
```json
[
{
"created_at": "2019-08-24T14:15:22Z",
"id": 0,
"log_level": "trace",
"log_source": "provisioner_daemon",
"output": "string",
"stage": "string"
}
]
```
### Responses [#responses-24]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.ProvisionerJobLog](/beta-docs/reference/api/schemas/#codersdkprovisionerjoblog) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------- | ------------------------------------------------------------------------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» created_at` | string(date-time) | false | | |
| `» id` | integer | false | | |
| `» log_level` | [codersdk.LogLevel](/beta-docs/reference/api/schemas/#codersdkloglevel) | false | | |
| `» log_source` | [codersdk.LogSource](/beta-docs/reference/api/schemas/#codersdklogsource) | false | | |
| `» output` | string | false | | |
| `» stage` | string | false | | |
#### Enumerated Values [#enumerated-values-5]
| Property | Value(s) |
| ------------ | ----------------------------------------- |
| `log_level` | `debug`, `error`, `info`, `trace`, `warn` |
| `log_source` | `provisioner`, `provisioner_daemon` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template version dry-run matched provisioners [#get-template-version-dry-run-matched-provisioners]
### Code samples [#code-samples-25]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/dry-run/{jobID}/matched-provisioners \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/dry-run/{jobID}/matched-provisioners`
### Parameters [#parameters-23]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
| `jobID` | path | string(uuid) | true | Job ID |
### Example responses [#example-responses-25]
> 200 Response
```json
{
"available": 0,
"count": 0,
"most_recently_seen": "2019-08-24T14:15:22Z"
}
```
### Responses [#responses-25]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.MatchedProvisioners](/beta-docs/reference/api/schemas/#codersdkmatchedprovisioners) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template version dry-run resources by job ID [#get-template-version-dry-run-resources-by-job-id]
### Code samples [#code-samples-26]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/dry-run/{jobID}/resources \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/dry-run/{jobID}/resources`
### Parameters [#parameters-24]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
| `jobID` | path | string(uuid) | true | Job ID |
### Example responses [#example-responses-26]
> 200 Response
```json
[
{
"agents": [
{
"api_version": "string",
"apps": [
{
"command": "string",
"display_name": "string",
"external": true,
"group": "string",
"health": "disabled",
"healthcheck": {
"interval": 0,
"threshold": 0,
"url": "string"
},
"hidden": true,
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"open_in": "slim-window",
"sharing_level": "owner",
"slug": "string",
"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"
}
],
"subdomain": true,
"subdomain_name": "string",
"tooltip": "string",
"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,
"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"
}
}
],
"name": "string",
"operating_system": "string",
"parent_id": {
"uuid": "string",
"valid": true
},
"ready_at": "2019-08-24T14:15:22Z",
"resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
"scripts": [
{
"cron": "string",
"display_name": "string",
"exit_code": 0,
"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,
"status": "ok",
"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"
}
]
```
### Responses [#responses-26]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.WorkspaceResource](/beta-docs/reference/api/schemas/#codersdkworkspaceresource) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `[array item]` | array | false | | |
| `» agents` | array | false | | |
| `»» api_version` | string | false | | |
| `»» apps` | array | false | | |
| `»»» command` | string | false | | |
| `»»» display_name` | string | false | | Display name is a friendly name for the app. |
| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on the client or not. |
| `»»» group` | string | false | | |
| `»»» health` | [codersdk.WorkspaceAppHealth](/beta-docs/reference/api/schemas/#codersdkworkspaceapphealth) | false | | |
| `»»» healthcheck` | [codersdk.Healthcheck](/beta-docs/reference/api/schemas/#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. |
| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. |
| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". |
| `»»»» url` | string | false | | URL specifies the endpoint to check for the app health. |
| `»»» hidden` | boolean | false | | |
| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. |
| `»»» id` | string(uuid) | false | | |
| `»»» open_in` | [codersdk.WorkspaceAppOpenIn](/beta-docs/reference/api/schemas/#codersdkworkspaceappopenin) | false | | |
| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](/beta-docs/reference/api/schemas/#codersdkworkspaceappsharinglevel) | false | | |
| `»»» slug` | string | false | | Slug is a unique identifier within the agent. |
| `»»» statuses` | array | false | | Statuses is a list of statuses for the app. |
| `»»»» agent_id` | string(uuid) | false | | |
| `»»»» app_id` | string(uuid) | false | | |
| `»»»» created_at` | string(date-time) | false | | |
| `»»»» icon` | string | false | | 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` | string(uuid) | false | | |
| `»»»» message` | string | false | | |
| `»»»» needs_user_attention` | boolean | false | | Deprecated: This field is unused and will be removed in a future version. NeedsUserAttention specifies whether the status needs user attention. |
| `»»»» state` | [codersdk.WorkspaceAppStatusState](/beta-docs/reference/api/schemas/#codersdkworkspaceappstatusstate) | false | | |
| `»»»» uri` | string | false | | Uri is the URI of the resource that the status is for. e.g. [https://github.com/org/repo/pull/123](https://github.com/org/repo/pull/123) e.g. file:///path/to/file |
| `»»»» workspace_id` | string(uuid) | false | | |
| `»»» subdomain` | boolean | false | | 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` | string | false | | Subdomain name is the application domain exposed on the `coder server`. |
| `»»» tooltip` | string | false | | Tooltip is an optional markdown supported field that is displayed when hovering over workspace apps in the UI. |
| `»»» url` | string | false | | URL is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. |
| `»» architecture` | string | false | | |
| `»» connection_timeout_seconds` | integer | false | | |
| `»» created_at` | string(date-time) | false | | |
| `»» directory` | string | false | | |
| `»» disconnected_at` | string(date-time) | false | | |
| `»» display_apps` | array | false | | |
| `»» environment_variables` | object | false | | |
| `»»» [any property]` | string | false | | |
| `»» expanded_directory` | string | false | | |
| `»» first_connected_at` | string(date-time) | false | | |
| `»» health` | [codersdk.WorkspaceAgentHealth](/beta-docs/reference/api/schemas/#codersdkworkspaceagenthealth) | false | | Health reports the health of the agent. |
| `»»» healthy` | boolean | false | | Healthy is true if the agent is healthy. |
| `»»» reason` | string | false | | Reason is a human-readable explanation of the agent's health. It is empty if Healthy is true. |
| `»» id` | string(uuid) | false | | |
| `»» instance_id` | string | false | | |
| `»» last_connected_at` | string(date-time) | false | | |
| `»» latency` | object | false | | Latency is mapped by region name (e.g. "New York City", "Seattle"). |
| `»»» [any property]` | [codersdk.DERPRegion](/beta-docs/reference/api/schemas/#codersdkderpregion) | false | | |
| `»»»» latency_ms` | number | false | | |
| `»»»» preferred` | boolean | false | | |
| `»» lifecycle_state` | [codersdk.WorkspaceAgentLifecycle](/beta-docs/reference/api/schemas/#codersdkworkspaceagentlifecycle) | false | | |
| `»» log_sources` | array | false | | |
| `»»» created_at` | string(date-time) | false | | |
| `»»» display_name` | string | false | | |
| `»»» icon` | string | false | | |
| `»»» id` | string(uuid) | false | | |
| `»»» workspace_agent_id` | string(uuid) | false | | |
| `»» logs_length` | integer | false | | |
| `»» logs_overflowed` | boolean | false | | |
| `»» metadata` | array | false | | Metadata is only populated on the workspaces list endpoint when the request opts in with the include\_agent\_metadata search key, and it only carries the requested keys. The description's script is always empty here: it can be long, and list consumers want values. |
| `»»» description` | [codersdk.WorkspaceAgentMetadataDescription](/beta-docs/reference/api/schemas/#codersdkworkspaceagentmetadatadescription) | false | | |
| `»»»» display_name` | string | false | | |
| `»»»» interval` | integer | false | | |
| `»»»» key` | string | false | | |
| `»»»» script` | string | false | | |
| `»»»» timeout` | integer | false | | |
| `»»» result` | [codersdk.WorkspaceAgentMetadataResult](/beta-docs/reference/api/schemas/#codersdkworkspaceagentmetadataresult) | false | | |
| `»»»» age` | integer | false | | Age is the number of seconds since the metadata was collected. It is provided in addition to CollectedAt to protect against clock skew. |
| `»»»» collected_at` | string(date-time) | false | | |
| `»»»» error` | string | false | | |
| `»»»» value` | string | false | | |
| `»» name` | string | false | | |
| `»» operating_system` | string | false | | |
| `»» parent_id` | [uuid.NullUUID](/beta-docs/reference/api/schemas/#uuidnulluuid) | false | | |
| `»»» uuid` | string | false | | |
| `»»» valid` | boolean | false | | Valid is true if UUID is not NULL |
| `»» ready_at` | string(date-time) | false | | |
| `»» resource_id` | string(uuid) | false | | |
| `»» scripts` | array | false | | |
| `»»» cron` | string | false | | |
| `»»» display_name` | string | false | | |
| `»»» exit_code` | integer | false | | |
| `»»» id` | string(uuid) | false | | |
| `»»» log_path` | string | false | | |
| `»»» log_source_id` | string(uuid) | false | | |
| `»»» run_on_start` | boolean | false | | |
| `»»» run_on_stop` | boolean | false | | |
| `»»» script` | string | false | | |
| `»»» start_blocks_login` | boolean | false | | |
| `»»» status` | [codersdk.WorkspaceAgentScriptStatus](/beta-docs/reference/api/schemas/#codersdkworkspaceagentscriptstatus) | false | | |
| `»»» timeout` | integer | false | | |
| `»» started_at` | string(date-time) | false | | |
| `»» startup_script_behavior` | [codersdk.WorkspaceAgentStartupScriptBehavior](/beta-docs/reference/api/schemas/#codersdkworkspaceagentstartupscriptbehavior) | false | | Startup script behavior is a legacy field that is deprecated in favor of the `coder_script` resource. It's only referenced by old clients. Deprecated: Remove in the future! |
| `»» status` | [codersdk.WorkspaceAgentStatus](/beta-docs/reference/api/schemas/#codersdkworkspaceagentstatus) | false | | |
| `»» subsystems` | array | false | | |
| `»» troubleshooting_url` | string | false | | |
| `»» updated_at` | string(date-time) | false | | |
| `»» version` | string | false | | |
| `» created_at` | string(date-time) | false | | |
| `» daily_cost` | integer | false | | |
| `» hide` | boolean | false | | |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» job_id` | string(uuid) | false | | |
| `» metadata` | array | false | | |
| `»» key` | string | false | | |
| `»» sensitive` | boolean | false | | |
| `»» value` | string | false | | |
| `» name` | string | false | | |
| `» type` | string | false | | |
| `» workspace_transition` | [codersdk.WorkspaceTransition](/beta-docs/reference/api/schemas/#codersdkworkspacetransition) | false | | |
#### Enumerated Values [#enumerated-values-6]
| Property | Value(s) |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `health` | `disabled`, `healthy`, `initializing`, `unhealthy` |
| `open_in` | `slim-window`, `tab` |
| `sharing_level` | `authenticated`, `organization`, `owner`, `public` |
| `state` | `complete`, `failure`, `idle`, `working` |
| `lifecycle_state` | `created`, `off`, `ready`, `shutdown_error`, `shutdown_timeout`, `shutting_down`, `start_error`, `start_timeout`, `starting` |
| `status` | `connected`, `connecting`, `disconnected`, `exit_failure`, `ok`, `pipes_left_open`, `timed_out`, `timeout` |
| `startup_script_behavior` | `blocking`, `non-blocking` |
| `workspace_transition` | `delete`, `start`, `stop` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Open dynamic parameters WebSocket by template version [#open-dynamic-parameters-websocket-by-template-version]
### Code samples [#code-samples-27]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/dynamic-parameters \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/dynamic-parameters`
### Parameters [#parameters-25]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Responses [#responses-27]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------------------ | ------------------- | ------ |
| 101 | [Switching Protocols](https://tools.ietf.org/html/rfc7231#section-6.2.2) | Switching Protocols | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Evaluate dynamic parameters for template version [#evaluate-dynamic-parameters-for-template-version]
### Code samples [#code-samples-28]
```sh
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/templateversions/{templateversion}/dynamic-parameters/evaluate \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /api/v2/templateversions/{templateversion}/dynamic-parameters/evaluate`
> Body parameter
```json
{
"id": 0,
"inputs": {
"property1": "string",
"property2": "string"
},
"owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05"
}
```
### Parameters [#parameters-26]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------------------------------------------------------------------------------------------------- | -------- | ------------------------ |
| `templateversion` | path | string(uuid) | true | Template version ID |
| `body` | body | [codersdk.DynamicParametersRequest](/beta-docs/reference/api/schemas/#codersdkdynamicparametersrequest) | true | Initial parameter values |
### Example responses [#example-responses-27]
> 200 Response
```json
{
"diagnostics": [
{
"detail": "string",
"extra": {
"code": "string"
},
"severity": "error",
"summary": "string"
}
],
"id": 0,
"parameters": [
{
"default_value": {
"valid": true,
"value": "string"
},
"description": "string",
"diagnostics": [
{
"detail": "string",
"extra": {
"code": "string"
},
"severity": "error",
"summary": "string"
}
],
"display_name": "string",
"ephemeral": true,
"form_type": "",
"icon": "string",
"mutable": true,
"name": "string",
"options": [
{
"description": "string",
"icon": "string",
"name": "string",
"value": {
"valid": true,
"value": "string"
}
}
],
"order": 0,
"required": true,
"styling": {
"disabled": true,
"label": "string",
"mask_input": true,
"placeholder": "string"
},
"type": "string",
"validations": [
{
"validation_error": "string",
"validation_max": 0,
"validation_min": 0,
"validation_monotonic": "string",
"validation_regex": "string"
}
],
"value": {
"valid": true,
"value": "string"
}
}
]
}
```
### Responses [#responses-28]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.DynamicParametersResponse](/beta-docs/reference/api/schemas/#codersdkdynamicparametersresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get external auth by template version [#get-external-auth-by-template-version]
### Code samples [#code-samples-29]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/external-auth \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/external-auth`
### Parameters [#parameters-27]
| Name | In | Type | Required | Description |
| ----------------- | ----- | ------------ | -------- | ------------------------------------------------------------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
| `user_id` | query | string(uuid) | false | Owner to report external auth state for. Defaults to the requesting user. |
### Example responses [#example-responses-28]
> 200 Response
```json
[
{
"authenticate_url": "string",
"authenticated": true,
"display_icon": "string",
"display_name": "string",
"id": "string",
"optional": true,
"type": "string"
}
]
```
### Responses [#responses-29]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.TemplateVersionExternalAuth](/beta-docs/reference/api/schemas/#codersdktemplateversionexternalauth) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------------- | ------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» authenticate_url` | string | false | | |
| `» authenticated` | boolean | false | | |
| `» display_icon` | string | false | | |
| `» display_name` | string | false | | |
| `» id` | string | false | | |
| `» optional` | boolean | false | | |
| `» type` | string | false | | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get logs by template version [#get-logs-by-template-version]
### Code samples [#code-samples-30]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/logs \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/logs`
### Parameters [#parameters-28]
| Name | In | Type | Required | Description |
| ----------------- | ----- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
| `before` | query | integer | false | Before log id |
| `after` | query | integer | false | After log id |
| `follow` | query | boolean | false | Follow log stream |
| `format` | query | string | false | Log output format. Accepted: 'json' (default), 'text' (plain text with RFC3339 timestamps and ANSI colors). Not supported with follow=true. |
#### Enumerated Values [#enumerated-values-7]
| Parameter | Value(s) |
| --------- | -------------- |
| `format` | `json`, `text` |
### Example responses [#example-responses-29]
> 200 Response
```json
[
{
"created_at": "2019-08-24T14:15:22Z",
"id": 0,
"log_level": "trace",
"log_source": "provisioner_daemon",
"output": "string",
"stage": "string"
}
]
```
### Responses [#responses-30]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.ProvisionerJobLog](/beta-docs/reference/api/schemas/#codersdkprovisionerjoblog) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------- | ------------------------------------------------------------------------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» created_at` | string(date-time) | false | | |
| `» id` | integer | false | | |
| `» log_level` | [codersdk.LogLevel](/beta-docs/reference/api/schemas/#codersdkloglevel) | false | | |
| `» log_source` | [codersdk.LogSource](/beta-docs/reference/api/schemas/#codersdklogsource) | false | | |
| `» output` | string | false | | |
| `» stage` | string | false | | |
#### Enumerated Values [#enumerated-values-8]
| Property | Value(s) |
| ------------ | ----------------------------------------- |
| `log_level` | `debug`, `error`, `info`, `trace`, `warn` |
| `log_source` | `provisioner`, `provisioner_daemon` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Removed: Get parameters by template version [#removed-get-parameters-by-template-version]
### Code samples [#code-samples-31]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/parameters \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/parameters`
### Parameters [#parameters-29]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Responses [#responses-31]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template version presets [#get-template-version-presets]
### Code samples [#code-samples-32]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/presets \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/presets`
### Parameters [#parameters-30]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Example responses [#example-responses-30]
> 200 Response
```json
[
{
"default": true,
"description": "string",
"desiredPrebuildInstances": 0,
"icon": "string",
"id": "string",
"name": "string",
"parameters": [
{
"name": "string",
"value": "string"
}
]
}
]
```
### Responses [#responses-32]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Preset](/beta-docs/reference/api/schemas/#codersdkpreset) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ---------------------------- | ------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» default` | boolean | false | | |
| `» description` | string | false | | |
| `» desiredPrebuildInstances` | integer | false | | |
| `» icon` | string | false | | |
| `» id` | string | false | | |
| `» name` | string | false | | |
| `» parameters` | array | false | | |
| `»» name` | string | false | | |
| `»» value` | string | false | | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get resources by template version [#get-resources-by-template-version]
### Code samples [#code-samples-33]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/resources \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/resources`
### Parameters [#parameters-31]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Example responses [#example-responses-31]
> 200 Response
```json
[
{
"agents": [
{
"api_version": "string",
"apps": [
{
"command": "string",
"display_name": "string",
"external": true,
"group": "string",
"health": "disabled",
"healthcheck": {
"interval": 0,
"threshold": 0,
"url": "string"
},
"hidden": true,
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"open_in": "slim-window",
"sharing_level": "owner",
"slug": "string",
"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"
}
],
"subdomain": true,
"subdomain_name": "string",
"tooltip": "string",
"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,
"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"
}
}
],
"name": "string",
"operating_system": "string",
"parent_id": {
"uuid": "string",
"valid": true
},
"ready_at": "2019-08-24T14:15:22Z",
"resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
"scripts": [
{
"cron": "string",
"display_name": "string",
"exit_code": 0,
"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,
"status": "ok",
"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"
}
]
```
### Responses [#responses-33]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.WorkspaceResource](/beta-docs/reference/api/schemas/#codersdkworkspaceresource) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `[array item]` | array | false | | |
| `» agents` | array | false | | |
| `»» api_version` | string | false | | |
| `»» apps` | array | false | | |
| `»»» command` | string | false | | |
| `»»» display_name` | string | false | | Display name is a friendly name for the app. |
| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on the client or not. |
| `»»» group` | string | false | | |
| `»»» health` | [codersdk.WorkspaceAppHealth](/beta-docs/reference/api/schemas/#codersdkworkspaceapphealth) | false | | |
| `»»» healthcheck` | [codersdk.Healthcheck](/beta-docs/reference/api/schemas/#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. |
| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. |
| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". |
| `»»»» url` | string | false | | URL specifies the endpoint to check for the app health. |
| `»»» hidden` | boolean | false | | |
| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. |
| `»»» id` | string(uuid) | false | | |
| `»»» open_in` | [codersdk.WorkspaceAppOpenIn](/beta-docs/reference/api/schemas/#codersdkworkspaceappopenin) | false | | |
| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](/beta-docs/reference/api/schemas/#codersdkworkspaceappsharinglevel) | false | | |
| `»»» slug` | string | false | | Slug is a unique identifier within the agent. |
| `»»» statuses` | array | false | | Statuses is a list of statuses for the app. |
| `»»»» agent_id` | string(uuid) | false | | |
| `»»»» app_id` | string(uuid) | false | | |
| `»»»» created_at` | string(date-time) | false | | |
| `»»»» icon` | string | false | | 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` | string(uuid) | false | | |
| `»»»» message` | string | false | | |
| `»»»» needs_user_attention` | boolean | false | | Deprecated: This field is unused and will be removed in a future version. NeedsUserAttention specifies whether the status needs user attention. |
| `»»»» state` | [codersdk.WorkspaceAppStatusState](/beta-docs/reference/api/schemas/#codersdkworkspaceappstatusstate) | false | | |
| `»»»» uri` | string | false | | Uri is the URI of the resource that the status is for. e.g. [https://github.com/org/repo/pull/123](https://github.com/org/repo/pull/123) e.g. file:///path/to/file |
| `»»»» workspace_id` | string(uuid) | false | | |
| `»»» subdomain` | boolean | false | | 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` | string | false | | Subdomain name is the application domain exposed on the `coder server`. |
| `»»» tooltip` | string | false | | Tooltip is an optional markdown supported field that is displayed when hovering over workspace apps in the UI. |
| `»»» url` | string | false | | URL is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. |
| `»» architecture` | string | false | | |
| `»» connection_timeout_seconds` | integer | false | | |
| `»» created_at` | string(date-time) | false | | |
| `»» directory` | string | false | | |
| `»» disconnected_at` | string(date-time) | false | | |
| `»» display_apps` | array | false | | |
| `»» environment_variables` | object | false | | |
| `»»» [any property]` | string | false | | |
| `»» expanded_directory` | string | false | | |
| `»» first_connected_at` | string(date-time) | false | | |
| `»» health` | [codersdk.WorkspaceAgentHealth](/beta-docs/reference/api/schemas/#codersdkworkspaceagenthealth) | false | | Health reports the health of the agent. |
| `»»» healthy` | boolean | false | | Healthy is true if the agent is healthy. |
| `»»» reason` | string | false | | Reason is a human-readable explanation of the agent's health. It is empty if Healthy is true. |
| `»» id` | string(uuid) | false | | |
| `»» instance_id` | string | false | | |
| `»» last_connected_at` | string(date-time) | false | | |
| `»» latency` | object | false | | Latency is mapped by region name (e.g. "New York City", "Seattle"). |
| `»»» [any property]` | [codersdk.DERPRegion](/beta-docs/reference/api/schemas/#codersdkderpregion) | false | | |
| `»»»» latency_ms` | number | false | | |
| `»»»» preferred` | boolean | false | | |
| `»» lifecycle_state` | [codersdk.WorkspaceAgentLifecycle](/beta-docs/reference/api/schemas/#codersdkworkspaceagentlifecycle) | false | | |
| `»» log_sources` | array | false | | |
| `»»» created_at` | string(date-time) | false | | |
| `»»» display_name` | string | false | | |
| `»»» icon` | string | false | | |
| `»»» id` | string(uuid) | false | | |
| `»»» workspace_agent_id` | string(uuid) | false | | |
| `»» logs_length` | integer | false | | |
| `»» logs_overflowed` | boolean | false | | |
| `»» metadata` | array | false | | Metadata is only populated on the workspaces list endpoint when the request opts in with the include\_agent\_metadata search key, and it only carries the requested keys. The description's script is always empty here: it can be long, and list consumers want values. |
| `»»» description` | [codersdk.WorkspaceAgentMetadataDescription](/beta-docs/reference/api/schemas/#codersdkworkspaceagentmetadatadescription) | false | | |
| `»»»» display_name` | string | false | | |
| `»»»» interval` | integer | false | | |
| `»»»» key` | string | false | | |
| `»»»» script` | string | false | | |
| `»»»» timeout` | integer | false | | |
| `»»» result` | [codersdk.WorkspaceAgentMetadataResult](/beta-docs/reference/api/schemas/#codersdkworkspaceagentmetadataresult) | false | | |
| `»»»» age` | integer | false | | Age is the number of seconds since the metadata was collected. It is provided in addition to CollectedAt to protect against clock skew. |
| `»»»» collected_at` | string(date-time) | false | | |
| `»»»» error` | string | false | | |
| `»»»» value` | string | false | | |
| `»» name` | string | false | | |
| `»» operating_system` | string | false | | |
| `»» parent_id` | [uuid.NullUUID](/beta-docs/reference/api/schemas/#uuidnulluuid) | false | | |
| `»»» uuid` | string | false | | |
| `»»» valid` | boolean | false | | Valid is true if UUID is not NULL |
| `»» ready_at` | string(date-time) | false | | |
| `»» resource_id` | string(uuid) | false | | |
| `»» scripts` | array | false | | |
| `»»» cron` | string | false | | |
| `»»» display_name` | string | false | | |
| `»»» exit_code` | integer | false | | |
| `»»» id` | string(uuid) | false | | |
| `»»» log_path` | string | false | | |
| `»»» log_source_id` | string(uuid) | false | | |
| `»»» run_on_start` | boolean | false | | |
| `»»» run_on_stop` | boolean | false | | |
| `»»» script` | string | false | | |
| `»»» start_blocks_login` | boolean | false | | |
| `»»» status` | [codersdk.WorkspaceAgentScriptStatus](/beta-docs/reference/api/schemas/#codersdkworkspaceagentscriptstatus) | false | | |
| `»»» timeout` | integer | false | | |
| `»» started_at` | string(date-time) | false | | |
| `»» startup_script_behavior` | [codersdk.WorkspaceAgentStartupScriptBehavior](/beta-docs/reference/api/schemas/#codersdkworkspaceagentstartupscriptbehavior) | false | | Startup script behavior is a legacy field that is deprecated in favor of the `coder_script` resource. It's only referenced by old clients. Deprecated: Remove in the future! |
| `»» status` | [codersdk.WorkspaceAgentStatus](/beta-docs/reference/api/schemas/#codersdkworkspaceagentstatus) | false | | |
| `»» subsystems` | array | false | | |
| `»» troubleshooting_url` | string | false | | |
| `»» updated_at` | string(date-time) | false | | |
| `»» version` | string | false | | |
| `» created_at` | string(date-time) | false | | |
| `» daily_cost` | integer | false | | |
| `» hide` | boolean | false | | |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» job_id` | string(uuid) | false | | |
| `» metadata` | array | false | | |
| `»» key` | string | false | | |
| `»» sensitive` | boolean | false | | |
| `»» value` | string | false | | |
| `» name` | string | false | | |
| `» type` | string | false | | |
| `» workspace_transition` | [codersdk.WorkspaceTransition](/beta-docs/reference/api/schemas/#codersdkworkspacetransition) | false | | |
#### Enumerated Values [#enumerated-values-9]
| Property | Value(s) |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `health` | `disabled`, `healthy`, `initializing`, `unhealthy` |
| `open_in` | `slim-window`, `tab` |
| `sharing_level` | `authenticated`, `organization`, `owner`, `public` |
| `state` | `complete`, `failure`, `idle`, `working` |
| `lifecycle_state` | `created`, `off`, `ready`, `shutdown_error`, `shutdown_timeout`, `shutting_down`, `start_error`, `start_timeout`, `starting` |
| `status` | `connected`, `connecting`, `disconnected`, `exit_failure`, `ok`, `pipes_left_open`, `timed_out`, `timeout` |
| `startup_script_behavior` | `blocking`, `non-blocking` |
| `workspace_transition` | `delete`, `start`, `stop` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get rich parameters by template version [#get-rich-parameters-by-template-version]
### Code samples [#code-samples-34]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/rich-parameters \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/rich-parameters`
### Parameters [#parameters-32]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Example responses [#example-responses-32]
> 200 Response
```json
[
{
"default_value": "string",
"description": "string",
"description_plaintext": "string",
"display_name": "string",
"ephemeral": true,
"form_type": "",
"icon": "string",
"mutable": true,
"name": "string",
"options": [
{
"description": "string",
"icon": "string",
"name": "string",
"value": "string"
}
],
"required": true,
"type": "string",
"validation_error": "string",
"validation_max": 0,
"validation_min": 0,
"validation_monotonic": "increasing",
"validation_regex": "string"
}
]
```
### Responses [#responses-34]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.TemplateVersionParameter](/beta-docs/reference/api/schemas/#codersdktemplateversionparameter) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» default_value` | string | false | | |
| `» description` | string | false | | |
| `» description_plaintext` | string | false | | |
| `» display_name` | string | false | | |
| `» ephemeral` | boolean | false | | |
| `» form_type` | string | false | | Form type has an enum value of empty string, `""`. Keep the leading comma in the enums struct tag. |
| `» icon` | string | false | | |
| `» mutable` | boolean | false | | |
| `» name` | string | false | | |
| `» options` | array | false | | |
| `»» description` | string | false | | |
| `»» icon` | string | false | | |
| `»» name` | string | false | | |
| `»» value` | string | false | | |
| `» required` | boolean | false | | |
| `» type` | string | false | | |
| `» validation_error` | string | false | | |
| `» validation_max` | integer | false | | |
| `» validation_min` | integer | false | | |
| `» validation_monotonic` | [codersdk.ValidationMonotonicOrder](/beta-docs/reference/api/schemas/#codersdkvalidationmonotonicorder) | false | | |
| `» validation_regex` | string | false | | |
#### Enumerated Values [#enumerated-values-10]
| Property | Value(s) |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `form_type` | \`\`, `checkbox`, `dropdown`, `error`, `input`, `multi-select`, `radio`, `slider`, `switch`, `tag-select`, `textarea` |
| `type` | `bool`, `list(string)`, `number`, `string` |
| `validation_monotonic` | `decreasing`, `increasing` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Removed: Get schema by template version [#removed-get-schema-by-template-version]
### Code samples [#code-samples-35]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/schema \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/schema`
### Parameters [#parameters-33]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Responses [#responses-35]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Unarchive template version [#unarchive-template-version]
### Code samples [#code-samples-36]
```sh
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/templateversions/{templateversion}/unarchive \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /api/v2/templateversions/{templateversion}/unarchive`
### Parameters [#parameters-34]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Example responses [#example-responses-33]
> 200 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses-36]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get template variables by template version [#get-template-variables-by-template-version]
### Code samples [#code-samples-37]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/variables \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/templateversions/{templateversion}/variables`
### Parameters [#parameters-35]
| Name | In | Type | Required | Description |
| ----------------- | ---- | ------------ | -------- | ------------------- |
| `templateversion` | path | string(uuid) | true | Template version ID |
### Example responses [#example-responses-34]
> 200 Response
```json
[
{
"default_value": "string",
"description": "string",
"name": "string",
"required": true,
"sensitive": true,
"type": "string",
"value": "string"
}
]
```
### Responses [#responses-37]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.TemplateVersionVariable](/beta-docs/reference/api/schemas/#codersdktemplateversionvariable) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ----------------- | ------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» default_value` | string | false | | |
| `» description` | string | false | | |
| `» name` | string | false | | |
| `» required` | boolean | false | | |
| `» sensitive` | boolean | false | | |
| `» type` | string | false | | |
| `» value` | string | false | | |
#### Enumerated Values [#enumerated-values-11]
| Property | Value(s) |
| -------- | -------------------------- |
| `type` | `bool`, `number`, `string` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).