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

# Create environment

> Creates a custom environment for a canvas. The name is trimmed and must satisfy the environment name rules: lowercase letters, digits and single hyphens, at most 64 characters, not a reserved name (`production`, `promoted`, `latest`, `draft`) and not a UUID.



## OpenAPI

````yaml POST /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:
    post:
      tags:
        - Environment
      summary: Create environment
      description: >
        Creates a custom environment for a canvas. The name is trimmed and must
        satisfy the

        [environment name rules](#/components/schemas/EnvironmentName):
        lowercase letters, digits and single

        hyphens, at most 64 characters, not a reserved name (`production`,
        `promoted`, `latest`, `draft`) and

        not a UUID. Violations return `400`.


        Environment names are unique per canvas; creating a name that already
        exists returns `409`.

        The new environment has no published version until you call `POST
        /environment/publish-by-name`.
      operationId: createEnvironment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentCreateRequest'
      responses:
        '201':
          description: Environment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '400':
          description: >-
            Invalid environment name (bad characters, too long, reserved, or a
            UUID)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/EnvironmentUnauthorized'
        '403':
          $ref: '#/components/responses/EnvironmentForbidden'
        '404':
          $ref: '#/components/responses/EnvironmentNotFound'
        '409':
          description: An environment with this name already exists for the canvas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/EnvironmentValidationError'
      security:
        - bearerAuth: []
components:
  schemas:
    EnvironmentCreateRequest:
      type: object
      properties:
        resourceType:
          $ref: '#/components/schemas/EnvironmentResourceType'
        resourceId:
          type: string
          format: uuid
          description: Canvas (prompt) ID
        name:
          $ref: '#/components/schemas/EnvironmentName'
      required:
        - resourceType
        - resourceId
        - name
      example:
        resourceType: prompt
        resourceId: 95cec438-6080-44fe-8275-28b16bd40178
        name: staging
    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
    Error: {}
    EnvironmentResourceType:
      type: string
      enum:
        - prompt
      description: >-
        Resource type an environment is attached to. Only canvases (`prompt`)
        are supported today.
    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:
    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.