> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List environments

> Returns every environment of a canvas (prompt), ordered with `production` first and the remaining environments alphabetically.



## OpenAPI

````yaml GET /environment
openapi: 3.0.1
info:
  title: Tela API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tela.com
security: []
paths:
  /environment:
    get:
      tags:
        - Environment
      summary: List environments
      description: >
        Returns every environment of a canvas (prompt), ordered with
        `production` first and the remaining

        environments alphabetically. Each item carries the version currently
        published to the environment

        (`currentVersion`) and the active publication record
        (`activePublication`), both `null` when nothing

        has been published yet.


        The system `production` environment is created on demand if the canvas
        does not have one yet, so

        the response always contains at least that entry.
      operationId: listEnvironments
      parameters:
        - $ref: '#/components/parameters/EnvironmentResourceTypeQuery'
        - $ref: '#/components/parameters/EnvironmentResourceIdQuery'
      responses:
        '200':
          description: Environments of the canvas
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EnvironmentWithCurrentVersion'
        '400':
          $ref: '#/components/responses/EnvironmentBadRequest'
        '401':
          $ref: '#/components/responses/EnvironmentUnauthorized'
        '403':
          $ref: '#/components/responses/EnvironmentForbidden'
        '404':
          $ref: '#/components/responses/EnvironmentNotFound'
        '422':
          $ref: '#/components/responses/EnvironmentValidationError'
      security:
        - bearerAuth: []
components:
  parameters:
    EnvironmentResourceTypeQuery:
      name: resourceType
      in: query
      required: true
      description: >-
        Type of resource the environment belongs to. Only `prompt` (a canvas) is
        supported.
      schema:
        $ref: '#/components/schemas/EnvironmentResourceType'
    EnvironmentResourceIdQuery:
      name: resourceId
      in: query
      required: true
      description: Canvas (prompt) ID.
      schema:
        type: string
        format: uuid
  schemas:
    EnvironmentWithCurrentVersion:
      allOf:
        - $ref: '#/components/schemas/Environment'
        - type: object
          properties:
            currentVersion:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/EnvironmentCurrentVersion'
            activePublication:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/EnvironmentActivePublication'
          required:
            - currentVersion
            - activePublication
      example:
        id: 0a3f6c2e-9d1b-4c7a-b5e8-2f4d6a8c0e1b
        resourceType: prompt
        resourceId: 95cec438-6080-44fe-8275-28b16bd40178
        name: production
        isSystem: true
        currentVersionId: 76065caa-c519-441a-8fe2-cc43e29664ab
        workspaceId: 3f55cfd9-4427-4887-a181-d9ad39967802
        createdBy: jane@example.com
        deletedBy: null
        createdAt: '2025-05-20T09:30:00.000Z'
        updatedAt: '2025-06-02T15:45:10.000Z'
        deletedAt: null
        currentVersion:
          id: 76065caa-c519-441a-8fe2-cc43e29664ab
          title: Contract analysis v3
          promptId: 95cec438-6080-44fe-8275-28b16bd40178
          draft: false
          promoted: true
          createdAt: '2025-06-02T15:40:00.000Z'
          updatedAt: '2025-06-02T15:45:10.000Z'
          createdBy: jane@example.com
          updatedBy: jane@example.com
          versionIndex: 3
        activePublication:
          publishedAt: '2025-06-02T15:45:10.000Z'
          publishedBy: jane@example.com
    EnvironmentResourceType:
      type: string
      enum:
        - prompt
      description: >-
        Resource type an environment is attached to. Only canvases (`prompt`)
        are supported today.
    Environment:
      type: object
      description: An environment of a canvas. Timestamps are ISO 8601 strings.
      properties:
        id:
          type: string
          format: uuid
        resourceType:
          $ref: '#/components/schemas/EnvironmentResourceType'
        resourceId:
          type: string
          format: uuid
          description: Canvas (prompt) ID
        name:
          $ref: '#/components/schemas/EnvironmentName'
        isSystem:
          type: boolean
          description: >-
            `true` for the built-in `production` environment, which cannot be
            deleted.
        currentVersionId:
          type: string
          format: uuid
          nullable: true
          description: >-
            Version currently published to the environment, or `null` when
            nothing was published.
        workspaceId:
          type: string
          format: uuid
        createdBy:
          type: string
          description: Email of the user or key that created the environment.
        deletedBy:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
      required:
        - id
        - resourceType
        - resourceId
        - name
        - isSystem
        - currentVersionId
        - workspaceId
        - createdBy
        - deletedBy
        - createdAt
        - updatedAt
        - deletedAt
      example:
        id: 2f1c9a7e-3b4d-4e5f-8a6b-1c2d3e4f5a6b
        resourceType: prompt
        resourceId: 95cec438-6080-44fe-8275-28b16bd40178
        name: staging
        isSystem: false
        currentVersionId: null
        workspaceId: 3f55cfd9-4427-4887-a181-d9ad39967802
        createdBy: jane@example.com
        deletedBy: null
        createdAt: '2025-06-01T12:00:00.000Z'
        updatedAt: '2025-06-01T12:00:00.000Z'
        deletedAt: null
    EnvironmentCurrentVersion:
      type: object
      description: Summary of the version currently published to an environment.
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        promptId:
          type: string
          format: uuid
        draft:
          type: boolean
          nullable: true
        promoted:
          type: boolean
          nullable: true
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
        createdBy:
          type: string
        updatedBy:
          type: string
        versionIndex:
          type: integer
          description: >-
            1-based position of the version in the canvas history (1 is the
            oldest). Omitted when it cannot be computed.
      required:
        - id
        - title
        - promptId
        - draft
        - promoted
        - createdAt
        - updatedAt
        - createdBy
        - updatedBy
    EnvironmentActivePublication:
      type: object
      description: The publication record that is currently active for the environment.
      properties:
        publishedAt:
          type: string
          format: date-time
        publishedBy:
          type: string
          description: Email of the user or key that published the version.
      required:
        - publishedAt
        - publishedBy
    Error: {}
    EnvironmentName:
      type: string
      pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
      maxLength: 64
      description: >
        Environment name. Lowercase letters, digits and single hyphens between
        segments (no leading, trailing

        or consecutive hyphens), at most 64 characters. Leading/trailing
        whitespace is trimmed before validation.


        `production` is the system environment every canvas has; it is the only
        reserved name you can publish to.

        The names `production`, `promoted`, `latest` and `draft` are reserved
        and cannot be used for custom

        environments, and a custom name cannot be a UUID.


        The same rules apply to the `environment_name` field of `POST
        /v2/chat/completions`, which runs the

        version currently published to that environment of the given `canvas_id`
        (`environment_name` cannot be

        combined with `version_id` or `application_id`, and returns `404` when
        the environment does not exist or

        has no published version).
      example: staging
  responses:
    EnvironmentBadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    EnvironmentUnauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    EnvironmentForbidden:
      description: The key does not have the required role or access to the canvas' project
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    EnvironmentNotFound:
      description: Canvas or environment not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    EnvironmentValidationError:
      description: Request body or query failed schema validation (`code` is `VALIDATION`)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT or UUID

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.