Home
/
API
/
Templates

Templates

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

NameInTypeRequiredDescription
organizationpathstring(uuid)trueOrganization ID

Example responses

200 Response

[
  {
    "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,
    "autostop_requirement": {
      "days_of_week": ["monday"],
      "weeks": 0
    },
    "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",
    "max_ttl_ms": 0,
    "name": "string",
    "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
    "provisioner": "terraform",
    "time_til_dormant_autodelete_ms": 0,
    "time_til_dormant_ms": 0,
    "updated_at": "2019-08-24T14:15:22Z"
  }
]

Responses

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.Template

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» active_user_countintegerfalseActive user count is set to -1 when loading.
» active_version_idstring(uuid)false
» allow_user_autostartbooleanfalseAllow 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_autostopbooleanfalse
» allow_user_cancel_workspace_jobsbooleanfalse
» autostop_requirementcodersdk.TemplateAutostopRequirementfalseAutostop requirement is an enterprise feature. Its value is only used if your license is entitled to use the advanced template scheduling feature.
»» days_of_weekarrayfalseDays 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.
»» weeksintegerfalseWeeks 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_statscodersdk.TemplateBuildTimeStatsfalse
»» [any property]codersdk.TransitionStatsfalse
»»» p50integerfalse
»»» p95integerfalse
» created_atstring(date-time)false
» created_by_idstring(uuid)false
» created_by_namestringfalse
» default_ttl_msintegerfalse
» descriptionstringfalse
» display_namestringfalse
» failure_ttl_msintegerfalseFailure ttl ms TimeTilDormantMillis, and TimeTilDormantAutoDeleteMillis are enterprise-only. Their values are used if your license is entitled to use the advanced template scheduling feature.
» iconstringfalse
» idstring(uuid)false
» max_ttl_msintegerfalseMax ttl ms remove max_ttl once autostop_requirement is matured
» namestringfalse
» organization_idstring(uuid)false
» provisionerstringfalse
» time_til_dormant_autodelete_msintegerfalse
» time_til_dormant_msintegerfalse
» updated_atstring(date-time)false

Enumerated Values

PropertyValue
provisionerterraform

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

Body parameter

{
  "allow_user_autostart": true,
  "allow_user_autostop": true,
  "allow_user_cancel_workspace_jobs": true,
  "autostop_requirement": {
    "days_of_week": ["monday"],
    "weeks": 0
  },
  "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_ttl_ms": 0,
  "name": "string",
  "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1"
}

Parameters

NameInTypeRequiredDescription
organizationpathstringtrueOrganization ID
bodybodycodersdk.CreateTemplateRequesttrueRequest body

Example responses

200 Response

{
  "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,
  "autostop_requirement": {
    "days_of_week": ["monday"],
    "weeks": 0
  },
  "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",
  "max_ttl_ms": 0,
  "name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "provisioner": "terraform",
  "time_til_dormant_autodelete_ms": 0,
  "time_til_dormant_ms": 0,
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

NameInTypeRequiredDescription
organizationpathstring(uuid)trueOrganization ID

Example responses

200 Response

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

Responses

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.TemplateExample

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» descriptionstringfalse
» iconstringfalse
» idstring(uuid)false
» markdownstringfalse
» namestringfalse
» tagsarrayfalse
» urlstringfalse

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

NameInTypeRequiredDescription
organizationpathstring(uuid)trueOrganization ID
templatenamepathstringtrueTemplate name

Example responses

200 Response

{
  "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,
  "autostop_requirement": {
    "days_of_week": ["monday"],
    "weeks": 0
  },
  "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",
  "max_ttl_ms": 0,
  "name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "provisioner": "terraform",
  "time_til_dormant_autodelete_ms": 0,
  "time_til_dormant_ms": 0,
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

NameInTypeRequiredDescription
organizationpathstring(uuid)trueOrganization ID
templatenamepathstringtrueTemplate name
templateversionnamepathstringtrueTemplate version name

Example responses

200 Response

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

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

NameInTypeRequiredDescription
organizationpathstring(uuid)trueOrganization ID
templatenamepathstringtrueTemplate name
templateversionnamepathstringtrueTemplate version name

Example responses

200 Response

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

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

Body parameter

{
  "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

NameInTypeRequiredDescription
organizationpathstring(uuid)trueOrganization ID
bodybodycodersdk.CreateTemplateVersionRequesttrueCreate template version request

Example responses

201 Response

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

StatusMeaningDescriptionSchema
201CreatedCreatedcodersdk.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

NameInTypeRequiredDescription
templatepathstring(uuid)trueTemplate ID

Example responses

200 Response

{
  "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,
  "autostop_requirement": {
    "days_of_week": ["monday"],
    "weeks": 0
  },
  "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",
  "max_ttl_ms": 0,
  "name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "provisioner": "terraform",
  "time_til_dormant_autodelete_ms": 0,
  "time_til_dormant_ms": 0,
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

NameInTypeRequiredDescription
templatepathstring(uuid)trueTemplate ID

Example responses

200 Response

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

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

NameInTypeRequiredDescription
templatepathstring(uuid)trueTemplate ID

Example responses

200 Response

{
  "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,
  "autostop_requirement": {
    "days_of_week": ["monday"],
    "weeks": 0
  },
  "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",
  "max_ttl_ms": 0,
  "name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "provisioner": "terraform",
  "time_til_dormant_autodelete_ms": 0,
  "time_til_dormant_ms": 0,
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

NameInTypeRequiredDescription
templatepathstring(uuid)trueTemplate ID

Example responses

200 Response

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

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

NameInTypeRequiredDescription
templatepathstring(uuid)trueTemplate ID
after_idquerystring(uuid)falseAfter ID
limitqueryintegerfalsePage limit
offsetqueryintegerfalsePage offset

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
      "avatar_url": "http://example.com",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "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": "REQUIRED_TEMPLATE_VARIABLES",
      "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "queue_position": 0,
      "queue_size": 0,
      "started_at": "2019-08-24T14:15:22Z",
      "status": "pending",
      "tags": {
        "property1": "string",
        "property2": "string"
      },
      "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
    },
    "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

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.TemplateVersion

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» created_atstring(date-time)false
» created_bycodersdk.MinimalUserfalse
»» avatar_urlstring(uri)false
»» idstring(uuid)true
»» usernamestringtrue
» idstring(uuid)false
» jobcodersdk.ProvisionerJobfalse
»» canceled_atstring(date-time)false
»» completed_atstring(date-time)false
»» created_atstring(date-time)false
»» errorstringfalse
»» error_codecodersdk.JobErrorCodefalse
»» file_idstring(uuid)false
»» idstring(uuid)false
»» queue_positionintegerfalse
»» queue_sizeintegerfalse
»» started_atstring(date-time)false
»» statuscodersdk.ProvisionerJobStatusfalse
»» tagsobjectfalse
»»» [any property]stringfalse
»» worker_idstring(uuid)false
» messagestringfalse
» namestringfalse
» organization_idstring(uuid)false
» readmestringfalse
» template_idstring(uuid)false
» updated_atstring(date-time)false
» warningsarrayfalse

Enumerated Values

PropertyValue
error_codeREQUIRED_TEMPLATE_VARIABLES
statuspending
statusrunning
statussucceeded
statuscanceling
statuscanceled
statusfailed

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

Body parameter

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

Parameters

NameInTypeRequiredDescription
templatepathstring(uuid)trueTemplate ID
bodybodycodersdk.UpdateActiveTemplateVersiontrueModified template version

Example responses

200 Response

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

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

NameInTypeRequiredDescription
templatepathstring(uuid)trueTemplate ID
templateversionnamepathstringtrueTemplate version name

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
      "avatar_url": "http://example.com",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "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": "REQUIRED_TEMPLATE_VARIABLES",
      "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "queue_position": 0,
      "queue_size": 0,
      "started_at": "2019-08-24T14:15:22Z",
      "status": "pending",
      "tags": {
        "property1": "string",
        "property2": "string"
      },
      "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
    },
    "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

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.TemplateVersion

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» created_atstring(date-time)false
» created_bycodersdk.MinimalUserfalse
»» avatar_urlstring(uri)false
»» idstring(uuid)true
»» usernamestringtrue
» idstring(uuid)false
» jobcodersdk.ProvisionerJobfalse
»» canceled_atstring(date-time)false
»» completed_atstring(date-time)false
»» created_atstring(date-time)false
»» errorstringfalse
»» error_codecodersdk.JobErrorCodefalse
»» file_idstring(uuid)false
»» idstring(uuid)false
»» queue_positionintegerfalse
»» queue_sizeintegerfalse
»» started_atstring(date-time)false
»» statuscodersdk.ProvisionerJobStatusfalse
»» tagsobjectfalse
»»» [any property]stringfalse
»» worker_idstring(uuid)false
» messagestringfalse
» namestringfalse
» organization_idstring(uuid)false
» readmestringfalse
» template_idstring(uuid)false
» updated_atstring(date-time)false
» warningsarrayfalse

Enumerated Values

PropertyValue
error_codeREQUIRED_TEMPLATE_VARIABLES
statuspending
statusrunning
statussucceeded
statuscanceling
statuscanceled
statusfailed

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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID

Example responses

200 Response

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

StatusMeaningDescriptionSchema
200OKOKcodersdk.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}

Body parameter

{
  "message": "string",
  "name": "string"
}

Parameters

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID
bodybodycodersdk.PatchTemplateVersionRequesttruePatch template version request

Example responses

200 Response

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

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID

Example responses

200 Response

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

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

Body parameter

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

Parameters

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID
bodybodycodersdk.CreateTemplateVersionDryRunRequesttrueDry-run request

Example responses

201 Response

{
  "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",
  "queue_position": 0,
  "queue_size": 0,
  "started_at": "2019-08-24T14:15:22Z",
  "status": "pending",
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
}

Responses

StatusMeaningDescriptionSchema
201CreatedCreatedcodersdk.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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID
jobIDpathstring(uuid)trueJob ID

Example responses

200 Response

{
  "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",
  "queue_position": 0,
  "queue_size": 0,
  "started_at": "2019-08-24T14:15:22Z",
  "status": "pending",
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
}

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

NameInTypeRequiredDescription
jobIDpathstring(uuid)trueJob ID
templateversionpathstring(uuid)trueTemplate version ID

Example responses

200 Response

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

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID
jobIDpathstring(uuid)trueJob ID
beforequeryintegerfalseBefore Unix timestamp
afterqueryintegerfalseAfter Unix timestamp
followquerybooleanfalseFollow log stream

Example responses

200 Response

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

Responses

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.ProvisionerJobLog

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» created_atstring(date-time)false
» idintegerfalse
» log_levelcodersdk.LogLevelfalse
» log_sourcecodersdk.LogSourcefalse
» outputstringfalse
» stagestringfalse

Enumerated Values

PropertyValue
log_leveltrace
log_leveldebug
log_levelinfo
log_levelwarn
log_levelerror
log_sourceprovisioner_daemon
log_sourceprovisioner

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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID
jobIDpathstring(uuid)trueJob ID

Example responses

200 Response

[
  {
    "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,
            "subdomain_name": "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,
        "name": "string",
        "operating_system": "string",
        "ready_at": "2019-08-24T14:15:22Z",
        "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
        "scripts": [
          {
            "cron": "string",
            "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,
            "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

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.WorkspaceResource

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» agentsarrayfalse
»» appsarrayfalse
»»» commandstringfalse
»»» display_namestringfalseDisplay name is a friendly name for the app.
»»» externalbooleanfalseExternal specifies whether the URL should be opened externally on the client or not.
»»» healthcodersdk.WorkspaceAppHealthfalse
»»» healthcheckcodersdk.HealthcheckfalseHealthcheck specifies the configuration for checking app health.
»»»» intervalintegerfalseInterval specifies the seconds between each health check.
»»»» thresholdintegerfalseThreshold specifies the number of consecutive failed health checks before returning "unhealthy".
»»»» urlstringfalseURL specifies the endpoint to check for the app health.
»»» iconstringfalseIcon is a relative path or external URL that specifies an icon to be displayed in the dashboard.
»»» idstring(uuid)false
»»» sharing_levelcodersdk.WorkspaceAppSharingLevelfalse
»»» slugstringfalseSlug is a unique identifier within the agent.
»»» subdomainbooleanfalseSubdomain 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_namestringfalseSubdomain name is the application domain exposed on the coder server.
»»» urlstringfalseURL is the address being proxied to inside the workspace. If external is specified, this will be opened on the client.
»» architecturestringfalse
»» connection_timeout_secondsintegerfalse
»» created_atstring(date-time)false
»» directorystringfalse
»» disconnected_atstring(date-time)false
»» display_appsarrayfalse
»» environment_variablesobjectfalse
»»» [any property]stringfalse
»» expanded_directorystringfalse
»» first_connected_atstring(date-time)false
»» healthcodersdk.WorkspaceAgentHealthfalseHealth reports the health of the agent.
»»» healthybooleanfalseHealthy is true if the agent is healthy.
»»» reasonstringfalseReason is a human-readable explanation of the agent's health. It is empty if Healthy is true.
»» idstring(uuid)false
»» instance_idstringfalse
»» last_connected_atstring(date-time)false
»» latencyobjectfalseLatency is mapped by region name (e.g. "New York City", "Seattle").
»»» [any property]codersdk.DERPRegionfalse
»»»» latency_msnumberfalse
»»»» preferredbooleanfalse
»» lifecycle_statecodersdk.WorkspaceAgentLifecyclefalse
»» log_sourcesarrayfalse
»»» created_atstring(date-time)false
»»» display_namestringfalse
»»» iconstringfalse
»»» idstring(uuid)false
»»» workspace_agent_idstring(uuid)false
»» logs_lengthintegerfalse
»» logs_overflowedbooleanfalse
»» namestringfalse
»» operating_systemstringfalse
»» ready_atstring(date-time)false
»» resource_idstring(uuid)false
»» scriptsarrayfalse
»»» cronstringfalse
»»» log_pathstringfalse
»»» log_source_idstring(uuid)false
»»» run_on_startbooleanfalse
»»» run_on_stopbooleanfalse
»»» scriptstringfalse
»»» start_blocks_loginbooleanfalse
»»» timeoutintegerfalse
»» started_atstring(date-time)false
»» startup_script_behaviorcodersdk.WorkspaceAgentStartupScriptBehaviorfalseStartup 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!
»» statuscodersdk.WorkspaceAgentStatusfalse
»» subsystemsarrayfalse
»» troubleshooting_urlstringfalse
»» updated_atstring(date-time)false
»» versionstringfalse
» created_atstring(date-time)false
» daily_costintegerfalse
» hidebooleanfalse
» iconstringfalse
» idstring(uuid)false
» job_idstring(uuid)false
» metadataarrayfalse
»» keystringfalse
»» sensitivebooleanfalse
»» valuestringfalse
» namestringfalse
» typestringfalse
» workspace_transitioncodersdk.WorkspaceTransitionfalse

Enumerated Values

PropertyValue
healthdisabled
healthinitializing
healthhealthy
healthunhealthy
sharing_levelowner
sharing_levelauthenticated
sharing_levelpublic
lifecycle_statecreated
lifecycle_statestarting
lifecycle_statestart_timeout
lifecycle_statestart_error
lifecycle_stateready
lifecycle_stateshutting_down
lifecycle_stateshutdown_timeout
lifecycle_stateshutdown_error
lifecycle_stateoff
startup_script_behaviorblocking
startup_script_behaviornon-blocking
statusconnecting
statusconnected
statusdisconnected
statustimeout
workspace_transitionstart
workspace_transitionstop
workspace_transitiondelete

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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID

Example responses

200 Response

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

Responses

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.TemplateVersionGitAuth

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» authenticate_urlstringfalse
» authenticatedbooleanfalse
» idstringfalse
» typecodersdk.GitProviderfalse

Enumerated Values

PropertyValue
typeazure-devops
typegithub
typegitlab
typebitbucket

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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID
beforequeryintegerfalseBefore log id
afterqueryintegerfalseAfter log id
followquerybooleanfalseFollow log stream

Example responses

200 Response

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

Responses

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.ProvisionerJobLog

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» created_atstring(date-time)false
» idintegerfalse
» log_levelcodersdk.LogLevelfalse
» log_sourcecodersdk.LogSourcefalse
» outputstringfalse
» stagestringfalse

Enumerated Values

PropertyValue
log_leveltrace
log_leveldebug
log_levelinfo
log_levelwarn
log_levelerror
log_sourceprovisioner_daemon
log_sourceprovisioner

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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID

Responses

StatusMeaningDescriptionSchema
200OKOK

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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID

Example responses

200 Response

[
  {
    "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,
            "subdomain_name": "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,
        "name": "string",
        "operating_system": "string",
        "ready_at": "2019-08-24T14:15:22Z",
        "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
        "scripts": [
          {
            "cron": "string",
            "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,
            "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

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.WorkspaceResource

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» agentsarrayfalse
»» appsarrayfalse
»»» commandstringfalse
»»» display_namestringfalseDisplay name is a friendly name for the app.
»»» externalbooleanfalseExternal specifies whether the URL should be opened externally on the client or not.
»»» healthcodersdk.WorkspaceAppHealthfalse
»»» healthcheckcodersdk.HealthcheckfalseHealthcheck specifies the configuration for checking app health.
»»»» intervalintegerfalseInterval specifies the seconds between each health check.
»»»» thresholdintegerfalseThreshold specifies the number of consecutive failed health checks before returning "unhealthy".
»»»» urlstringfalseURL specifies the endpoint to check for the app health.
»»» iconstringfalseIcon is a relative path or external URL that specifies an icon to be displayed in the dashboard.
»»» idstring(uuid)false
»»» sharing_levelcodersdk.WorkspaceAppSharingLevelfalse
»»» slugstringfalseSlug is a unique identifier within the agent.
»»» subdomainbooleanfalseSubdomain 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_namestringfalseSubdomain name is the application domain exposed on the coder server.
»»» urlstringfalseURL is the address being proxied to inside the workspace. If external is specified, this will be opened on the client.
»» architecturestringfalse
»» connection_timeout_secondsintegerfalse
»» created_atstring(date-time)false
»» directorystringfalse
»» disconnected_atstring(date-time)false
»» display_appsarrayfalse
»» environment_variablesobjectfalse
»»» [any property]stringfalse
»» expanded_directorystringfalse
»» first_connected_atstring(date-time)false
»» healthcodersdk.WorkspaceAgentHealthfalseHealth reports the health of the agent.
»»» healthybooleanfalseHealthy is true if the agent is healthy.
»»» reasonstringfalseReason is a human-readable explanation of the agent's health. It is empty if Healthy is true.
»» idstring(uuid)false
»» instance_idstringfalse
»» last_connected_atstring(date-time)false
»» latencyobjectfalseLatency is mapped by region name (e.g. "New York City", "Seattle").
»»» [any property]codersdk.DERPRegionfalse
»»»» latency_msnumberfalse
»»»» preferredbooleanfalse
»» lifecycle_statecodersdk.WorkspaceAgentLifecyclefalse
»» log_sourcesarrayfalse
»»» created_atstring(date-time)false
»»» display_namestringfalse
»»» iconstringfalse
»»» idstring(uuid)false
»»» workspace_agent_idstring(uuid)false
»» logs_lengthintegerfalse
»» logs_overflowedbooleanfalse
»» namestringfalse
»» operating_systemstringfalse
»» ready_atstring(date-time)false
»» resource_idstring(uuid)false
»» scriptsarrayfalse
»»» cronstringfalse
»»» log_pathstringfalse
»»» log_source_idstring(uuid)false
»»» run_on_startbooleanfalse
»»» run_on_stopbooleanfalse
»»» scriptstringfalse
»»» start_blocks_loginbooleanfalse
»»» timeoutintegerfalse
»» started_atstring(date-time)false
»» startup_script_behaviorcodersdk.WorkspaceAgentStartupScriptBehaviorfalseStartup 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!
»» statuscodersdk.WorkspaceAgentStatusfalse
»» subsystemsarrayfalse
»» troubleshooting_urlstringfalse
»» updated_atstring(date-time)false
»» versionstringfalse
» created_atstring(date-time)false
» daily_costintegerfalse
» hidebooleanfalse
» iconstringfalse
» idstring(uuid)false
» job_idstring(uuid)false
» metadataarrayfalse
»» keystringfalse
»» sensitivebooleanfalse
»» valuestringfalse
» namestringfalse
» typestringfalse
» workspace_transitioncodersdk.WorkspaceTransitionfalse

Enumerated Values

PropertyValue
healthdisabled
healthinitializing
healthhealthy
healthunhealthy
sharing_levelowner
sharing_levelauthenticated
sharing_levelpublic
lifecycle_statecreated
lifecycle_statestarting
lifecycle_statestart_timeout
lifecycle_statestart_error
lifecycle_stateready
lifecycle_stateshutting_down
lifecycle_stateshutdown_timeout
lifecycle_stateshutdown_error
lifecycle_stateoff
startup_script_behaviorblocking
startup_script_behaviornon-blocking
statusconnecting
statusconnected
statusdisconnected
statustimeout
workspace_transitionstart
workspace_transitionstop
workspace_transitiondelete

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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID

Example responses

200 Response

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

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.TemplateVersionParameter

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» default_valuestringfalse
» descriptionstringfalse
» description_plaintextstringfalse
» display_namestringfalse
» ephemeralbooleanfalse
» iconstringfalse
» mutablebooleanfalse
» namestringfalse
» optionsarrayfalse
»» descriptionstringfalse
»» iconstringfalse
»» namestringfalse
»» valuestringfalse
» requiredbooleanfalse
» typestringfalse
» validation_errorstringfalse
» validation_maxintegerfalse
» validation_minintegerfalse
» validation_monotoniccodersdk.ValidationMonotonicOrderfalse
» validation_regexstringfalse

Enumerated Values

PropertyValue
typestring
typenumber
typebool
typelist(string)
validation_monotonicincreasing
validation_monotonicdecreasing

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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID

Responses

StatusMeaningDescriptionSchema
200OKOK

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

NameInTypeRequiredDescription
templateversionpathstring(uuid)trueTemplate version ID

Example responses

200 Response

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

Responses

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.TemplateVersionVariable

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» default_valuestringfalse
» descriptionstringfalse
» namestringfalse
» requiredbooleanfalse
» sensitivebooleanfalse
» typestringfalse
» valuestringfalse

Enumerated Values

PropertyValue
typestring
typenumber
typebool

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

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