Coder Templates API

openapi: 3.0.3
info:
  description: Coderd is the service created by running coder server. It is a thin API that connects workspaces, provisioners and users. coderd stores its state in Postgres and is the only service that communicates with Postgres.
  title: Coder Agents Templates API
  termsOfService: https://coder.com/legal/terms-of-service
  contact:
    name: API Support
    url: https://coder.com
    email: support@coder.com
  license:
    name: AGPL-3.0
    url: https://github.com/coder/coder/blob/main/LICENSE
  version: '2.0'
servers:
- url: https://{coderHost}/api/v2
  description: Coder instance
  variables:
    coderHost:
      default: coder.example.com
      description: Your Coder deployment hostname
security:
- CoderSessionToken: []
tags:
- name: Templates
paths:
  /api/v2/organizations/{organization}/templates:
    get:
      operationId: get-templates-by-organization
      summary: Get templates by organization
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      description: 'Returns a list of templates for the specified organization.

        By default, only non-deprecated templates are returned.

        To include deprecated templates, specify `deprecated:true` in the search query.'
      parameters:
      - name: organization
        in: path
        required: true
        description: Organization ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.Template'
    post:
      operationId: create-template-by-organization
      summary: Create template by organization
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: organization
        in: path
        required: true
        description: Organization ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.CreateTemplateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Template'
  /api/v2/organizations/{organization}/templates/examples:
    get:
      operationId: get-template-examples-by-organization
      summary: Get template examples by organization
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: organization
        in: path
        required: true
        description: Organization ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.TemplateExample'
  /api/v2/organizations/{organization}/templates/{templatename}:
    get:
      operationId: get-templates-by-organization-and-template-name
      summary: Get templates by organization and template name
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: organization
        in: path
        required: true
        description: Organization ID
        schema:
          type: string
      - name: templatename
        in: path
        required: true
        description: Template name
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Template'
  /api/v2/organizations/{organization}/templates/{templatename}/versions/{templateversionname}:
    get:
      operationId: get-template-version-by-organization-template-and-name
      summary: Get template version by organization, template, and name
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: organization
        in: path
        required: true
        description: Organization ID
        schema:
          type: string
      - name: templatename
        in: path
        required: true
        description: Template name
        schema:
          type: string
      - name: templateversionname
        in: path
        required: true
        description: Template version name
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.TemplateVersion'
  /api/v2/organizations/{organization}/templates/{templatename}/versions/{templateversionname}/previous:
    get:
      operationId: get-previous-template-version-by-organization-template-and-name
      summary: Get previous template version by organization, template, and name
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: organization
        in: path
        required: true
        description: Organization ID
        schema:
          type: string
      - name: templatename
        in: path
        required: true
        description: Template name
        schema:
          type: string
      - name: templateversionname
        in: path
        required: true
        description: Template version name
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.TemplateVersion'
        '204':
          description: No Content
  /api/v2/organizations/{organization}/templateversions:
    post:
      operationId: create-template-version-by-organization
      summary: Create template version by organization
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: organization
        in: path
        required: true
        description: Organization ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.CreateTemplateVersionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.TemplateVersion'
  /api/v2/templates:
    get:
      operationId: get-all-templates
      summary: Get all templates
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      description: 'Returns a list of templates.

        By default, only non-deprecated templates are returned.

        To include deprecated templates, specify `deprecated:true` in the search query.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.Template'
  /api/v2/templates/examples:
    get:
      operationId: get-template-examples
      summary: Get template examples
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.TemplateExample'
  /api/v2/templates/{template}:
    get:
      operationId: get-template-settings-by-id
      summary: Get template settings by ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: template
        in: path
        required: true
        description: Template ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Template'
    delete:
      operationId: delete-template-by-id
      summary: Delete template by ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: template
        in: path
        required: true
        description: Template ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Response'
    patch:
      operationId: update-template-settings-by-id
      summary: Update template settings by ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: template
        in: path
        required: true
        description: Template ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.UpdateTemplateMeta'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Template'
  /api/v2/templates/{template}/daus:
    get:
      operationId: get-template-daus-by-id
      summary: Get template DAUs by ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: template
        in: path
        required: true
        description: Template ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.DAUsResponse'
  /api/v2/templates/{template}/versions:
    get:
      operationId: list-template-versions-by-template-id
      summary: List template versions by template ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: template
        in: path
        required: true
        description: Template ID
        schema:
          type: string
      - name: after_id
        in: query
        required: false
        description: After ID
        schema:
          type: string
      - name: include_archived
        in: query
        required: false
        description: Include archived versions in the list
        schema:
          type: boolean
      - name: limit
        in: query
        required: false
        description: Page limit
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Page offset
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.TemplateVersion'
    patch:
      operationId: update-active-template-version-by-template-id
      summary: Update active template version by template ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: template
        in: path
        required: true
        description: Template ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.UpdateActiveTemplateVersion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Response'
  /api/v2/templates/{template}/versions/archive:
    post:
      operationId: archive-template-unused-versions-by-template-id
      summary: Archive template unused versions by template id
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: template
        in: path
        required: true
        description: Template ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.ArchiveTemplateVersionsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Response'
  /api/v2/templates/{template}/versions/{templateversionname}:
    get:
      operationId: get-template-version-by-template-id-and-name
      summary: Get template version by template ID and name
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: template
        in: path
        required: true
        description: Template ID
        schema:
          type: string
      - name: templateversionname
        in: path
        required: true
        description: Template version name
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.TemplateVersion'
  /api/v2/templateversions/{templateversion}:
    get:
      operationId: get-template-version-by-id
      summary: Get template version by ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.TemplateVersion'
    patch:
      operationId: patch-template-version-by-id
      summary: Patch template version by ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.PatchTemplateVersionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.TemplateVersion'
  /api/v2/templateversions/{templateversion}/archive:
    post:
      operationId: archive-template-version
      summary: Archive template version
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Response'
  /api/v2/templateversions/{templateversion}/cancel:
    patch:
      operationId: cancel-template-version-by-id
      summary: Cancel template version by ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Response'
  /api/v2/templateversions/{templateversion}/dry-run:
    post:
      operationId: create-template-version-dry-run
      summary: Create template version dry-run
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.CreateTemplateVersionDryRunRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.ProvisionerJob'
  /api/v2/templateversions/{templateversion}/dry-run/{jobID}:
    get:
      operationId: get-template-version-dry-run-by-job-id
      summary: Get template version dry-run by job ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      - name: jobID
        in: path
        required: true
        description: Job ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.ProvisionerJob'
  /api/v2/templateversions/{templateversion}/dry-run/{jobID}/cancel:
    patch:
      operationId: cancel-template-version-dry-run-by-job-id
      summary: Cancel template version dry-run by job ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: jobID
        in: path
        required: true
        description: Job ID
        schema:
          type: string
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Response'
  /api/v2/templateversions/{templateversion}/dry-run/{jobID}/logs:
    get:
      operationId: get-template-version-dry-run-logs-by-job-id
      summary: Get template version dry-run logs by job ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      - name: jobID
        in: path
        required: true
        description: Job ID
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Before Unix timestamp
        schema:
          type: integer
      - name: after
        in: query
        required: false
        description: After Unix timestamp
        schema:
          type: integer
      - name: follow
        in: query
        required: false
        description: Follow log stream
        schema:
          type: boolean
      - name: format
        in: query
        required: false
        description: 'Log output format. Accepted: ''json'' (default), ''text'' (plain text with RFC3339 timestamps and ANSI colors). Not supported with follow=true.'
        schema:
          type: string
          enum:
          - json
          - text
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.ProvisionerJobLog'
  /api/v2/templateversions/{templateversion}/dry-run/{jobID}/matched-provisioners:
    get:
      operationId: get-template-version-dry-run-matched-provisioners
      summary: Get template version dry-run matched provisioners
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      - name: jobID
        in: path
        required: true
        description: Job ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.MatchedProvisioners'
  /api/v2/templateversions/{templateversion}/dry-run/{jobID}/resources:
    get:
      operationId: get-template-version-dry-run-resources-by-job-id
      summary: Get template version dry-run resources by job ID
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      - name: jobID
        in: path
        required: true
        description: Job ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.WorkspaceResource'
  /api/v2/templateversions/{templateversion}/dynamic-parameters:
    get:
      operationId: open-dynamic-parameters-websocket-by-template-version
      summary: Open dynamic parameters WebSocket by template version
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '101':
          description: Switching Protocols
  /api/v2/templateversions/{templateversion}/dynamic-parameters/evaluate:
    post:
      operationId: evaluate-dynamic-parameters-for-template-version
      summary: Evaluate dynamic parameters for template version
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.DynamicParametersRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.DynamicParametersResponse'
  /api/v2/templateversions/{templateversion}/external-auth:
    get:
      operationId: get-external-auth-by-template-version
      summary: Get external auth by template version
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.TemplateVersionExternalAuth'
  /api/v2/templateversions/{templateversion}/logs:
    get:
      operationId: get-logs-by-template-version
      summary: Get logs by template version
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Before log id
        schema:
          type: integer
      - name: after
        in: query
        required: false
        description: After log id
        schema:
          type: integer
      - name: follow
        in: query
        required: false
        description: Follow log stream
        schema:
          type: boolean
      - name: format
        in: query
        required: false
        description: 'Log output format. Accepted: ''json'' (default), ''text'' (plain text with RFC3339 timestamps and ANSI colors). Not supported with follow=true.'
        schema:
          type: string
          enum:
          - json
          - text
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.ProvisionerJobLog'
  /api/v2/templateversions/{templateversion}/parameters:
    get:
      operationId: removed-get-parameters-by-template-version
      summary: 'Removed: Get parameters by template version'
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
  /api/v2/templateversions/{templateversion}/presets:
    get:
      operationId: get-template-version-presets
      summary: Get template version presets
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.Preset'
  /api/v2/templateversions/{templateversion}/resources:
    get:
      operationId: get-resources-by-template-version
      summary: Get resources by template version
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.WorkspaceResource'
  /api/v2/templateversions/{templateversion}/rich-parameters:
    get:
      operationId: get-rich-parameters-by-template-version
      summary: Get rich parameters by template version
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.TemplateVersionParameter'
  /api/v2/templateversions/{templateversion}/schema:
    get:
      operationId: removed-get-schema-by-template-version
      summary: 'Removed: Get schema by template version'
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
  /api/v2/templateversions/{templateversion}/unarchive:
    post:
      operationId: unarchive-template-version
      summary: Unarchive template version
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Response'
  /api/v2/templateversions/{templateversion}/variables:
    get:
      operationId: get-template-variables-by-template-version
      summary: Get template variables by template version
      tags:
      - Templates
      security:
      - CoderSessionToken: []
      parameters:
      - name: templateversion
        in: path
        required: true
        description: Template version ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.TemplateVersionVariable'
components:
  schemas:
    codersdk.Preset:
      type: object
      properties:
        default:
          type: boolean
        description:
          type: string
        desiredPrebuildInstances:
          type: integer
        icon:
          type: string
        id:
          type: string
        name:
          type: string
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.PresetParameter'
    codersdk.PresetParameter:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
    codersdk.UpdateActiveTemplateVersion:
      type: object
      properties:
        id:
          type: string
          format: uuid
      required:
      - id
    codersdk.AgentSubsystem:
      type: string
      enum:
      - envbox
      - envbuilder
      - exectrace
    codersdk.FriendlyDiagnostic:
      type: object
      properties:
        detail:
          type: string
        extra:
          $ref: '#/components/schemas/codersdk.DiagnosticExtra'
        severity:
          $ref: '#/components/schemas/codersdk.DiagnosticSeverityString'
        summary:
          type: string
    codersdk.DiagnosticExtra:
      type: object
      properties:
        code:
          type: string
    codersdk.DisplayApp:
      type: string
      enum:
      - vscode
      - vscode_insiders
      - web_terminal
      - port_forwarding_helper
      - ssh_helper
    codersdk.WorkspaceAppSharingLevel:
      type: string
      enum:
      - owner
      - authenticated
      - organization
      - public
    codersdk.WorkspaceAgentHealth:
      type: object
      properties:
        healthy:
          type: boolean
          description: Healthy is true if the agent is healthy.
          example: false
        reason:
          type: string
          description: Reason is a human-readable explanation of the agent's health. It is empty if Healthy is true.
          example: agent has lost connection
    codersdk.ArchiveTemplateVersionsRequest:
      type: object
      properties:
        all:
          type: boolean
          description: 'By default, only failed versions are archived. Set this to true

            to archive all unused versions regardless of job status.'
    codersdk.UpdateTemplateMeta:
      type: object
      properties:
        activity_bump_ms:
          type: integer
          description: 'ActivityBumpMillis allows optionally specifying the activity bump

            duration for all workspaces created from this template. Defaults to 1h

            but can be set to 0 to disable activity bumping.'
        allow_user_autostart:
          type: boolean
        allow_user_autostop:
          type: boolean
        allow_user_cancel_workspace_jobs:
          type: boolean
        autostart_requirement:
          $ref: '#/components/schemas/codersdk.TemplateAutostartRequirement'
        autostop_requirement:
          description: 'AutostopRequirement and AutostartRequirement can only be set if your license

            includes the advanced template scheduling feature. If you attempt to set this

            value while unlicensed, it will be ignored.'
          allOf:
          - $ref: '#/components/schemas/codersdk.TemplateAutostopRequirement'
        cors_behavior:
          $ref: '#/components/schemas/codersdk.CORSBeh

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coder/refs/heads/main/openapi/coder-templates-api-openapi.yml