Templates - Coder v2 Docs

Templates

Get templates by organization

Code samples

# 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 /organizations/{organization}/templates

Parameters

Name	In	Type	Required	Description
`organization`	path	string(uuid)	true	Organization ID

Example responses

[
  {
    "active_user_count": 0,
    "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
    "allow_user_autostart": true,
    "allow_user_autostop": true,
    "allow_user_cancel_workspace_jobs": true,
    "build_time_stats": {
      "property1": {
        "p50": 123,
        "p95": 146
      },
      "property2": {
        "p50": 123,
        "p95": 146
      }
    },
    "created_at": "2019-08-24T14:15:22Z",
    "created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
    "created_by_name": "string",
    "default_ttl_ms": 0,
    "description": "string",
    "display_name": "string",
    "failure_ttl_ms": 0,
    "icon": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "inactivity_ttl_ms": 0,
    "max_ttl_ms": 0,
    "name": "string",
    "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
    "provisioner": "terraform",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.Template

Response Schema

Status Code 200

Name	Type	Required	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
`» 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
`» build_time_stats`	codersdk.TemplateBuildTimeStats	false
`»» [any property]`	codersdk.TransitionStats	false
`»»» p50`	integer	false
`»»» p95`	integer	false
`» created_at`	string(date-time)	false
`» created_by_id`	string(uuid)	false
`» created_by_name`	string	false
`» default_ttl_ms`	integer	false
`» description`	string	false
`» display_name`	string	false
`» failure_ttl_ms`	integer	false	Failure ttl ms and InactivityTTLMillis 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
`» inactivity_ttl_ms`	integer	false
`» max_ttl_ms`	integer	false	Max ttl ms is an enterprise feature. It's value is only used if your license is entitled to use the advanced template scheduling feature.
`» name`	string	false
`» organization_id`	string(uuid)	false
`» provisioner`	string	false
`» updated_at`	string(date-time)	false

Enumerated Values

Property	Value
`provisioner`	`terraform`

To perform this operation, you must be authenticated. Learn more.

Create template by organization

Code samples

# 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 /organizations/{organization}/templates

{
  "allow_user_autostart": true,
  "allow_user_autostop": true,
  "allow_user_cancel_workspace_jobs": true,
  "default_ttl_ms": 0,
  "description": "string",
  "display_name": "string",
  "failure_ttl_ms": 0,
  "icon": "string",
  "inactivity_ttl_ms": 0,
  "max_ttl_ms": 0,
  "name": "string",
  "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1"
}

Parameters

Name	In	Type	Required	Description
`organization`	path	string	true	Organization ID
`body`	body	codersdk.CreateTemplateRequest	true	Request body

Example responses

{
  "active_user_count": 0,
  "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
  "allow_user_autostart": true,
  "allow_user_autostop": true,
  "allow_user_cancel_workspace_jobs": true,
  "build_time_stats": {
    "property1": {
      "p50": 123,
      "p95": 146
    },
    "property2": {
      "p50": 123,
      "p95": 146
    }
  },
  "created_at": "2019-08-24T14:15:22Z",
  "created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
  "created_by_name": "string",
  "default_ttl_ms": 0,
  "description": "string",
  "display_name": "string",
  "failure_ttl_ms": 0,
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "inactivity_ttl_ms": 0,
  "max_ttl_ms": 0,
  "name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "provisioner": "terraform",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.Template

To perform this operation, you must be authenticated. Learn more.

Get template examples by organization

Code samples

# 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 /organizations/{organization}/templates/examples

Parameters

Name	In	Type	Required	Description
`organization`	path	string(uuid)	true	Organization ID

Example responses

[
  {
    "description": "string",
    "icon": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "markdown": "string",
    "name": "string",
    "tags": ["string"],
    "url": "string"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.TemplateExample

Response Schema

Status Code 200

Name	Type	Required
`[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.

Get templates by organization and template name

Code samples

# 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 /organizations/{organization}/templates/{templatename}

Parameters

Name	In	Type	Required	Description
`organization`	path	string(uuid)	true	Organization ID
`templatename`	path	string	true	Template name

Example responses

{
  "active_user_count": 0,
  "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
  "allow_user_autostart": true,
  "allow_user_autostop": true,
  "allow_user_cancel_workspace_jobs": true,
  "build_time_stats": {
    "property1": {
      "p50": 123,
      "p95": 146
    },
    "property2": {
      "p50": 123,
      "p95": 146
    }
  },
  "created_at": "2019-08-24T14:15:22Z",
  "created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
  "created_by_name": "string",
  "default_ttl_ms": 0,
  "description": "string",
  "display_name": "string",
  "failure_ttl_ms": 0,
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "inactivity_ttl_ms": 0,
  "max_ttl_ms": 0,
  "name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "provisioner": "terraform",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.Template

To perform this operation, you must be authenticated. Learn more.

Get template version by organization, template, and name

Code samples

# 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 /organizations/{organization}/templates/{templatename}/versions/{templateversionname}

Parameters

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

{
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "avatar_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
    "email": "[email protected]",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_seen_at": "2019-08-24T14:15:22Z",
    "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
    "roles": [
      {
        "display_name": "string",
        "name": "string"
      }
    ],
    "status": "active",
    "username": "string"
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "job": {
    "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": "MISSING_TEMPLATE_PARAMETER",
    "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "pending",
    "tags": {
      "property1": "string",
      "property2": "string"
    },
    "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
  },
  "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

Status	Meaning	Description	Schema
200	OK	OK	codersdk.TemplateVersion

To perform this operation, you must be authenticated. Learn more.

Get previous template version by organization, template, and name

Code samples

# 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 /organizations/{organization}/templates/{templatename}/versions/{templateversionname}/previous

Parameters

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

{
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "avatar_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
    "email": "[email protected]",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_seen_at": "2019-08-24T14:15:22Z",
    "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
    "roles": [
      {
        "display_name": "string",
        "name": "string"
      }
    ],
    "status": "active",
    "username": "string"
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "job": {
    "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": "MISSING_TEMPLATE_PARAMETER",
    "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "pending",
    "tags": {
      "property1": "string",
      "property2": "string"
    },
    "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
  },
  "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

Status	Meaning	Description	Schema
200	OK	OK	codersdk.TemplateVersion

To perform this operation, you must be authenticated. Learn more.

Create template version by organization

Code samples

# 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 /organizations/{organization}/templateversions

{
  "example_id": "string",
  "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
  "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

Name	In	Type	Required	Description
`organization`	path	string(uuid)	true	Organization ID
`body`	body	codersdk.CreateTemplateVersionRequest	true	Create template version request

Example responses

{
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "avatar_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
    "email": "[email protected]",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_seen_at": "2019-08-24T14:15:22Z",
    "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
    "roles": [
      {
        "display_name": "string",
        "name": "string"
      }
    ],
    "status": "active",
    "username": "string"
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "job": {
    "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": "MISSING_TEMPLATE_PARAMETER",
    "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "pending",
    "tags": {
      "property1": "string",
      "property2": "string"
    },
    "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
  },
  "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

Status	Meaning	Description	Schema
201	Created	Created	codersdk.TemplateVersion

To perform this operation, you must be authenticated. Learn more.

Get template metadata by ID

Code samples

# 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 /templates/{template}

Parameters

Name	In	Type	Required	Description
`template`	path	string(uuid)	true	Template ID

Example responses

{
  "active_user_count": 0,
  "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
  "allow_user_autostart": true,
  "allow_user_autostop": true,
  "allow_user_cancel_workspace_jobs": true,
  "build_time_stats": {
    "property1": {
      "p50": 123,
      "p95": 146
    },
    "property2": {
      "p50": 123,
      "p95": 146
    }
  },
  "created_at": "2019-08-24T14:15:22Z",
  "created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
  "created_by_name": "string",
  "default_ttl_ms": 0,
  "description": "string",
  "display_name": "string",
  "failure_ttl_ms": 0,
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "inactivity_ttl_ms": 0,
  "max_ttl_ms": 0,
  "name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "provisioner": "terraform",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.Template

To perform this operation, you must be authenticated. Learn more.

Delete template by ID

Code samples

# 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 /templates/{template}

Parameters

Name	In	Type	Required	Description
`template`	path	string(uuid)	true	Template ID

Example responses

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Update template metadata by ID

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/templates/{template} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /templates/{template}

Parameters

Name	In	Type	Required	Description
`template`	path	string(uuid)	true	Template ID

Example responses

{
  "active_user_count": 0,
  "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
  "allow_user_autostart": true,
  "allow_user_autostop": true,
  "allow_user_cancel_workspace_jobs": true,
  "build_time_stats": {
    "property1": {
      "p50": 123,
      "p95": 146
    },
    "property2": {
      "p50": 123,
      "p95": 146
    }
  },
  "created_at": "2019-08-24T14:15:22Z",
  "created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
  "created_by_name": "string",
  "default_ttl_ms": 0,
  "description": "string",
  "display_name": "string",
  "failure_ttl_ms": 0,
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "inactivity_ttl_ms": 0,
  "max_ttl_ms": 0,
  "name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "provisioner": "terraform",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.Template

To perform this operation, you must be authenticated. Learn more.

Get template DAUs by ID

Code samples

# 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 /templates/{template}/daus

Parameters

Name	In	Type	Required	Description
`template`	path	string(uuid)	true	Template ID

Example responses

{
  "entries": [
    {
      "amount": 0,
      "date": "2019-08-24T14:15:22Z"
    }
  ],
  "tz_hour_offset": 0
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.DAUsResponse

To perform this operation, you must be authenticated. Learn more.

List template versions by template ID

Code samples

# 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 /templates/{template}/versions

Parameters

Name	In	Type	Required	Description
`template`	path	string(uuid)	true	Template ID
`after_id`	query	string(uuid)	false	After ID
`limit`	query	integer	false	Page limit
`offset`	query	integer	false	Page offset

Example responses

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "email": "[email protected]",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "last_seen_at": "2019-08-24T14:15:22Z",
      "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
      "roles": [
        {
          "display_name": "string",
          "name": "string"
        }
      ],
      "status": "active",
      "username": "string"
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "job": {
      "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": "MISSING_TEMPLATE_PARAMETER",
      "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "started_at": "2019-08-24T14:15:22Z",
      "status": "pending",
      "tags": {
        "property1": "string",
        "property2": "string"
      },
      "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
    },
    "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

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.TemplateVersion

Response Schema

Status Code 200

Name	Type	Required
`[array item]`	array	false
`» created_at`	string(date-time)	false
`» created_by`	codersdk.User	false
`»» avatar_url`	string(uri)	false
`»» created_at`	string(date-time)	true
`»» email`	string(email)	true
`»» id`	string(uuid)	true
`»» last_seen_at`	string(date-time)	false
`»» organization_ids`	array	false
`»» roles`	array	false
`»»» display_name`	string	false
`»»» name`	string	false
`»» status`	codersdk.UserStatus	false
`»» username`	string	true
`» id`	string(uuid)	false
`» job`	codersdk.ProvisionerJob	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	false
`»» file_id`	string(uuid)	false
`»» id`	string(uuid)	false
`»» started_at`	string(date-time)	false
`»» status`	codersdk.ProvisionerJobStatus	false
`»» tags`	object	false
`»»» [any property]`	string	false
`»» worker_id`	string(uuid)	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

Property	Value
`status`	`active`
`status`	`suspended`
`error_code`	`MISSING_TEMPLATE_PARAMETER`
`error_code`	`REQUIRED_TEMPLATE_VARIABLES`
`status`	`pending`
`status`	`running`
`status`	`succeeded`
`status`	`canceling`
`status`	`canceled`
`status`	`failed`

To perform this operation, you must be authenticated. Learn more.

Update active template version by template ID

Code samples

# 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 /templates/{template}/versions

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Parameters

Name	In	Type	Required	Description
`template`	path	string(uuid)	true	Template ID
`body`	body	codersdk.UpdateActiveTemplateVersion	true	Modified template version

Example responses

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get template version by template ID and name

Code samples

# 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 /templates/{template}/versions/{templateversionname}

Parameters

Name	In	Type	Required	Description
`template`	path	string(uuid)	true	Template ID
`templateversionname`	path	string	true	Template version name

Example responses

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "email": "[email protected]",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "last_seen_at": "2019-08-24T14:15:22Z",
      "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
      "roles": [
        {
          "display_name": "string",
          "name": "string"
        }
      ],
      "status": "active",
      "username": "string"
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "job": {
      "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": "MISSING_TEMPLATE_PARAMETER",
      "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "started_at": "2019-08-24T14:15:22Z",
      "status": "pending",
      "tags": {
        "property1": "string",
        "property2": "string"
      },
      "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
    },
    "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

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.TemplateVersion

Response Schema

Status Code 200

Name	Type	Required
`[array item]`	array	false
`» created_at`	string(date-time)	false
`» created_by`	codersdk.User	false
`»» avatar_url`	string(uri)	false
`»» created_at`	string(date-time)	true
`»» email`	string(email)	true
`»» id`	string(uuid)	true
`»» last_seen_at`	string(date-time)	false
`»» organization_ids`	array	false
`»» roles`	array	false
`»»» display_name`	string	false
`»»» name`	string	false
`»» status`	codersdk.UserStatus	false
`»» username`	string	true
`» id`	string(uuid)	false
`» job`	codersdk.ProvisionerJob	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	false
`»» file_id`	string(uuid)	false
`»» id`	string(uuid)	false
`»» started_at`	string(date-time)	false
`»» status`	codersdk.ProvisionerJobStatus	false
`»» tags`	object	false
`»»» [any property]`	string	false
`»» worker_id`	string(uuid)	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

Property	Value
`status`	`active`
`status`	`suspended`
`error_code`	`MISSING_TEMPLATE_PARAMETER`
`error_code`	`REQUIRED_TEMPLATE_VARIABLES`
`status`	`pending`
`status`	`running`
`status`	`succeeded`
`status`	`canceling`
`status`	`canceled`
`status`	`failed`

To perform this operation, you must be authenticated. Learn more.

Get template version by ID

Code samples

# 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 /templateversions/{templateversion}

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID

Example responses

{
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "avatar_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
    "email": "[email protected]",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_seen_at": "2019-08-24T14:15:22Z",
    "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
    "roles": [
      {
        "display_name": "string",
        "name": "string"
      }
    ],
    "status": "active",
    "username": "string"
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "job": {
    "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": "MISSING_TEMPLATE_PARAMETER",
    "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "pending",
    "tags": {
      "property1": "string",
      "property2": "string"
    },
    "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
  },
  "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

Status	Meaning	Description	Schema
200	OK	OK	codersdk.TemplateVersion

To perform this operation, you must be authenticated. Learn more.

Patch template version by ID

Code samples

# 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 /templateversions/{templateversion}

{
  "name": "string"
}

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID
`body`	body	codersdk.PatchTemplateVersionRequest	true	Patch template version request

Example responses

{
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "avatar_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
    "email": "[email protected]",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_seen_at": "2019-08-24T14:15:22Z",
    "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
    "roles": [
      {
        "display_name": "string",
        "name": "string"
      }
    ],
    "status": "active",
    "username": "string"
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "job": {
    "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": "MISSING_TEMPLATE_PARAMETER",
    "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "pending",
    "tags": {
      "property1": "string",
      "property2": "string"
    },
    "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
  },
  "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

Status	Meaning	Description	Schema
200	OK	OK	codersdk.TemplateVersion

To perform this operation, you must be authenticated. Learn more.

Cancel template version by ID

Code samples

# 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 /templateversions/{templateversion}/cancel

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID

Example responses

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Create template version dry-run

Code samples

# 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 /templateversions/{templateversion}/dry-run

{
  "rich_parameter_values": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "user_variable_values": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "workspace_name": "string"
}

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID
`body`	body	codersdk.CreateTemplateVersionDryRunRequest	true	Dry-run request

Example responses

{
  "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": "MISSING_TEMPLATE_PARAMETER",
  "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "started_at": "2019-08-24T14:15:22Z",
  "status": "pending",
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
}

Responses

Status	Meaning	Description	Schema
201	Created	Created	codersdk.ProvisionerJob

To perform this operation, you must be authenticated. Learn more.

Get template version dry-run by job ID

Code samples

# 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 /templateversions/{templateversion}/dry-run/{jobID}

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID
`jobID`	path	string(uuid)	true	Job ID

Example responses

{
  "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": "MISSING_TEMPLATE_PARAMETER",
  "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "started_at": "2019-08-24T14:15:22Z",
  "status": "pending",
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.ProvisionerJob

To perform this operation, you must be authenticated. Learn more.

Cancel template version dry-run by job ID

Code samples

# 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 /templateversions/{templateversion}/dry-run/{jobID}/cancel

Parameters

Name	In	Type	Required	Description
`jobID`	path	string(uuid)	true	Job ID
`templateversion`	path	string(uuid)	true	Template version ID

Example responses

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get template version dry-run logs by job ID

Code samples

# 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 /templateversions/{templateversion}/dry-run/{jobID}/logs

Parameters

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

Example responses

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "id": 0,
    "log_level": "trace",
    "log_source": "provisioner_daemon",
    "output": "string",
    "stage": "string"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.ProvisionerJobLog

Response Schema

Status Code 200

Name	Type	Required
`[array item]`	array	false
`» created_at`	string(date-time)	false
`» id`	integer	false
`» log_level`	codersdk.LogLevel	false
`» log_source`	codersdk.LogSource	false
`» output`	string	false
`» stage`	string	false

Enumerated Values

Property	Value
`log_level`	`trace`
`log_level`	`debug`
`log_level`	`info`
`log_level`	`warn`
`log_level`	`error`
`log_source`	`provisioner_daemon`
`log_source`	`provisioner`

To perform this operation, you must be authenticated. Learn more.

Get template version dry-run resources by job ID

Code samples

# 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 /templateversions/{templateversion}/dry-run/{jobID}/resources

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID
`jobID`	path	string(uuid)	true	Job ID

Example responses

[
  {
    "agents": [
      {
        "apps": [
          {
            "command": "string",
            "display_name": "string",
            "external": true,
            "health": "disabled",
            "healthcheck": {
              "interval": 0,
              "threshold": 0,
              "url": "string"
            },
            "icon": "string",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "sharing_level": "owner",
            "slug": "string",
            "subdomain": true,
            "url": "string"
          }
        ],
        "architecture": "string",
        "connection_timeout_seconds": 0,
        "created_at": "2019-08-24T14:15:22Z",
        "directory": "string",
        "disconnected_at": "2019-08-24T14:15:22Z",
        "environment_variables": {
          "property1": "string",
          "property2": "string"
        },
        "expanded_directory": "string",
        "first_connected_at": "2019-08-24T14:15:22Z",
        "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",
        "login_before_ready": true,
        "name": "string",
        "operating_system": "string",
        "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
        "shutdown_script": "string",
        "shutdown_script_timeout_seconds": 0,
        "startup_logs_length": 0,
        "startup_logs_overflowed": true,
        "startup_script": "string",
        "startup_script_timeout_seconds": 0,
        "status": "connecting",
        "subsystem": "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

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.WorkspaceResource

Response Schema

Status Code 200

Name	Type	Required	Description
`[array item]`	array	false
`» agents`	array	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.
`»»» health`	codersdk.WorkspaceAppHealth	false
`»»» healthcheck`	codersdk.Healthcheck	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.
`»»» 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
`»»» sharing_level`	codersdk.WorkspaceAppSharingLevel	false
`»»» slug`	string	false	Slug is a unique identifier within the agent.
`»»» 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.
`»»» 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
`»» environment_variables`	object	false
`»»» [any property]`	string	false
`»» expanded_directory`	string	false
`»» first_connected_at`	string(date-time)	false
`»» 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	false
`»»»» latency_ms`	number	false
`»»»» preferred`	boolean	false
`»» lifecycle_state`	codersdk.WorkspaceAgentLifecycle	false
`»» login_before_ready`	boolean	false	»login before ready if true, the agent will delay logins until it is ready (e.g. executing startup script has ended).
`»» name`	string	false
`»» operating_system`	string	false
`»» resource_id`	string(uuid)	false
`»» shutdown_script`	string	false
`»» shutdown_script_timeout_seconds`	integer	false
`»» startup_logs_length`	integer	false
`»» startup_logs_overflowed`	boolean	false
`»» startup_script`	string	false
`»» startup_script_timeout_seconds`	integer	false	»startup script timeout seconds is the number of seconds to wait for the startup script to complete. If the script does not complete within this time, the agent lifecycle will be marked as start_timeout.
`»» status`	codersdk.WorkspaceAgentStatus	false
`»» subsystem`	codersdk.AgentSubsystem	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	false

Enumerated Values

Property	Value
`health`	`disabled`
`health`	`initializing`
`health`	`healthy`
`health`	`unhealthy`
`sharing_level`	`owner`
`sharing_level`	`authenticated`
`sharing_level`	`public`
`lifecycle_state`	`created`
`lifecycle_state`	`starting`
`lifecycle_state`	`start_timeout`
`lifecycle_state`	`start_error`
`lifecycle_state`	`ready`
`lifecycle_state`	`shutting_down`
`lifecycle_state`	`shutdown_timeout`
`lifecycle_state`	`shutdown_error`
`lifecycle_state`	`off`
`status`	`connecting`
`status`	`connected`
`status`	`disconnected`
`status`	`timeout`
`subsystem`	`envbox`
`workspace_transition`	`start`
`workspace_transition`	`stop`
`workspace_transition`	`delete`

To perform this operation, you must be authenticated. Learn more.

Get git auth by template version

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/gitauth \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /templateversions/{templateversion}/gitauth

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID

Example responses

[
  {
    "authenticate_url": "string",
    "authenticated": true,
    "id": "string",
    "type": "azure-devops"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.TemplateVersionGitAuth

Response Schema

Status Code 200

Name	Type	Required
`[array item]`	array	false
`» authenticate_url`	string	false
`» authenticated`	boolean	false
`» id`	string	false
`» type`	codersdk.GitProvider	false

Enumerated Values

Property	Value
`type`	`azure-devops`
`type`	`github`
`type`	`gitlab`
`type`	`bitbucket`

To perform this operation, you must be authenticated. Learn more.

Get logs by template version

Code samples

# 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 /templateversions/{templateversion}/logs

Parameters

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

Example responses

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "id": 0,
    "log_level": "trace",
    "log_source": "provisioner_daemon",
    "output": "string",
    "stage": "string"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.ProvisionerJobLog

Response Schema

Status Code 200

Name	Type	Required
`[array item]`	array	false
`» created_at`	string(date-time)	false
`» id`	integer	false
`» log_level`	codersdk.LogLevel	false
`» log_source`	codersdk.LogSource	false
`» output`	string	false
`» stage`	string	false

Enumerated Values

Property	Value
`log_level`	`trace`
`log_level`	`debug`
`log_level`	`info`
`log_level`	`warn`
`log_level`	`error`
`log_source`	`provisioner_daemon`
`log_source`	`provisioner`

To perform this operation, you must be authenticated. Learn more.

Removed: Get parameters by template version

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/parameters \
  -H 'Coder-Session-Token: API_KEY'

GET /templateversions/{templateversion}/parameters

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID

Responses

Status	Meaning	Description	Schema
200	OK	OK

To perform this operation, you must be authenticated. Learn more.

Get resources by template version

Code samples

# 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 /templateversions/{templateversion}/resources

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID

Example responses

[
  {
    "agents": [
      {
        "apps": [
          {
            "command": "string",
            "display_name": "string",
            "external": true,
            "health": "disabled",
            "healthcheck": {
              "interval": 0,
              "threshold": 0,
              "url": "string"
            },
            "icon": "string",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "sharing_level": "owner",
            "slug": "string",
            "subdomain": true,
            "url": "string"
          }
        ],
        "architecture": "string",
        "connection_timeout_seconds": 0,
        "created_at": "2019-08-24T14:15:22Z",
        "directory": "string",
        "disconnected_at": "2019-08-24T14:15:22Z",
        "environment_variables": {
          "property1": "string",
          "property2": "string"
        },
        "expanded_directory": "string",
        "first_connected_at": "2019-08-24T14:15:22Z",
        "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",
        "login_before_ready": true,
        "name": "string",
        "operating_system": "string",
        "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
        "shutdown_script": "string",
        "shutdown_script_timeout_seconds": 0,
        "startup_logs_length": 0,
        "startup_logs_overflowed": true,
        "startup_script": "string",
        "startup_script_timeout_seconds": 0,
        "status": "connecting",
        "subsystem": "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

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.WorkspaceResource

Response Schema

Status Code 200

Name	Type	Required	Description
`[array item]`	array	false
`» agents`	array	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.
`»»» health`	codersdk.WorkspaceAppHealth	false
`»»» healthcheck`	codersdk.Healthcheck	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.
`»»» 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
`»»» sharing_level`	codersdk.WorkspaceAppSharingLevel	false
`»»» slug`	string	false	Slug is a unique identifier within the agent.
`»»» 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.
`»»» 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
`»» environment_variables`	object	false
`»»» [any property]`	string	false
`»» expanded_directory`	string	false
`»» first_connected_at`	string(date-time)	false
`»» 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	false
`»»»» latency_ms`	number	false
`»»»» preferred`	boolean	false
`»» lifecycle_state`	codersdk.WorkspaceAgentLifecycle	false
`»» login_before_ready`	boolean	false	»login before ready if true, the agent will delay logins until it is ready (e.g. executing startup script has ended).
`»» name`	string	false
`»» operating_system`	string	false
`»» resource_id`	string(uuid)	false
`»» shutdown_script`	string	false
`»» shutdown_script_timeout_seconds`	integer	false
`»» startup_logs_length`	integer	false
`»» startup_logs_overflowed`	boolean	false
`»» startup_script`	string	false
`»» startup_script_timeout_seconds`	integer	false	»startup script timeout seconds is the number of seconds to wait for the startup script to complete. If the script does not complete within this time, the agent lifecycle will be marked as start_timeout.
`»» status`	codersdk.WorkspaceAgentStatus	false
`»» subsystem`	codersdk.AgentSubsystem	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	false

Enumerated Values

Property	Value
`health`	`disabled`
`health`	`initializing`
`health`	`healthy`
`health`	`unhealthy`
`sharing_level`	`owner`
`sharing_level`	`authenticated`
`sharing_level`	`public`
`lifecycle_state`	`created`
`lifecycle_state`	`starting`
`lifecycle_state`	`start_timeout`
`lifecycle_state`	`start_error`
`lifecycle_state`	`ready`
`lifecycle_state`	`shutting_down`
`lifecycle_state`	`shutdown_timeout`
`lifecycle_state`	`shutdown_error`
`lifecycle_state`	`off`
`status`	`connecting`
`status`	`connected`
`status`	`disconnected`
`status`	`timeout`
`subsystem`	`envbox`
`workspace_transition`	`start`
`workspace_transition`	`stop`
`workspace_transition`	`delete`

To perform this operation, you must be authenticated. Learn more.

Get rich parameters by template version

Code samples

# 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 /templateversions/{templateversion}/rich-parameters

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID

Example responses

[
  {
    "default_value": "string",
    "description": "string",
    "description_plaintext": "string",
    "display_name": "string",
    "icon": "string",
    "legacy_variable_name": "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

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.TemplateVersionParameter

Response Schema

Status Code 200

Name	Type	Required
`[array item]`	array	false
`» default_value`	string	false
`» description`	string	false
`» description_plaintext`	string	false
`» display_name`	string	false
`» icon`	string	false
`» legacy_variable_name`	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	false
`» validation_regex`	string	false

Enumerated Values

Property	Value
`type`	`string`
`type`	`number`
`type`	`bool`
`type`	`list(string)`
`validation_monotonic`	`increasing`
`validation_monotonic`	`decreasing`

To perform this operation, you must be authenticated. Learn more.

Removed: Get schema by template version

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/schema \
  -H 'Coder-Session-Token: API_KEY'

GET /templateversions/{templateversion}/schema

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID

Responses

Status	Meaning	Description	Schema
200	OK	OK

To perform this operation, you must be authenticated. Learn more.

Get template variables by template version

Code samples

# 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 /templateversions/{templateversion}/variables

Parameters

Name	In	Type	Required	Description
`templateversion`	path	string(uuid)	true	Template version ID

Example responses

[
  {
    "default_value": "string",
    "description": "string",
    "name": "string",
    "required": true,
    "sensitive": true,
    "type": "string",
    "value": "string"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.TemplateVersionVariable

Response Schema

Status Code 200

Name	Type	Required
`[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

Property	Value
`type`	`string`
`type`	`number`
`type`	`bool`

To perform this operation, you must be authenticated. Learn more.

See an opportunity to improve our docs? Make an edit.

On this page