Coder Templates API

openapi: 3.2.0
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.UpdateActiveTemplateVersion:
      type: object
      properties:
        id:
          type: string
          format: uuid
      required:
      - id
    codersdk.Template:
      type: object
      properties:
        active_user_count:
          type: integer
          description: ActiveUserCount is set to -1 when loading.
        active_version_id:
          type: string
          format: uuid
        activity_bump_ms:
          type: integer
        allow_user_autostart:
          type: boolean
          description: 'AllowUserAutostart 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:
          type: boolean
        allow_user_cancel_workspace_jobs:
          type: boolean
        autostart_requirement:
          $ref: '#/components/schemas/codersdk.TemplateAutostartRequirement'
        autostop_requirement:
          description: 'AutostopRequirement and AutostartRequirement are enterprise features. Its

            value is only used if your license is entitled to use the advanced template

            scheduling feature.'
          allOf:
          - $ref: '#/components/schemas/codersdk.TemplateAutostopRequirement'
        build_time_stats:
          $ref: '#/components/schemas/codersdk.TemplateBuildTimeStats'
        cors_behavior:
          $ref: '#/components/schemas/codersdk.CORSBehavior'
        created_at:
          type: string
          format: date-time
        created_by_id:
          type: string
          format: uuid
        created_by_name:
          type: string
        default_ttl_ms:
          type: integer
        deleted:
          type: boolean
        deprecated:
          type: boolean
        deprecation_message:
          type: string
        description:
          type: string
        disable_module_cache:
          type: boolean
          description: 'DisableModuleCache disables the use of cached Terraform modules during

            provisioning.'
        display_name:
          type: string
        failure_ttl_ms:
          type: integer
          description: 'FailureTTLMillis, TimeTilDormantMillis, and TimeTilDormantAutoDeleteMillis are enterprise-only. Their

            values are used if your license is entitled to use the advanced

            template scheduling feature.'
        icon:
          type: string
        id:
          type: string
          format: uuid
        max_port_share_level:
          $ref: '#/components/schemas/codersdk.WorkspaceAgentPortShareLevel'
        name:
          type: string
        organization_display_name:
          type: string
        organization_icon:
          type: string
        organization_id:
          type: string
          format: uuid
        organization_name:
          type: string
          format: url
        provisioner:
          type: string
          enum:
          - terraform
        require_active_version:
          type: boolean
          description: 'RequireActiveVersion mandates that workspaces are built with the active

            template version.'
        time_til_dormant_autodelete_ms:
          type: integer
        time_til_dormant_ms:
          type: integer
        updated_at:
          type: string
          format:

# --- 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