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

# Publish a version to an environment

> Publishes a prompt version to the environment identified by `envName` and returns the updated environment together with the published version.



## OpenAPI

````yaml POST /environment/publish-by-name
openapi: 3.0.1
info:
  title: Tela API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tela.com
security: []
paths:
  /environment/publish-by-name:
    post:
      tags:
        - Environment
      summary: Publish a version to an environment
      description: >
        Publishes a prompt version to the environment identified by `envName`
        and returns the updated environment

        together with the published version.


        Effects:

        - The version becomes the environment's current version; the previous
        publication is marked unpublished
          and a new publication record is appended to the history.
        - The version is taken out of draft (`draft: false`).

        - Publishing to `production` additionally promotes the version
        (`promoted: true`, un-promoting the
          previous one), updates Workstation apps of the canvas to use it, and invalidates the promoted-version cache.
        - Publishing the version that is already active is a no-op and returns
        the current state.


        If the environment does not exist: `production` is created
        automatically; any other name is created only

        when `autoCreate` is `true`, otherwise the request returns `404`.
        Reserved names other than `production`

        are rejected with `400`.
      operationId: publishVersionToEnvironment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentPublishByNameRequest'
      responses:
        '200':
          description: Version published
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentPublishResult'
        '400':
          description: Invalid environment name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/EnvironmentUnauthorized'
        '403':
          $ref: '#/components/responses/EnvironmentForbidden'
        '404':
          description: >-
            Canvas, version or environment not found (environment lookups fail
            unless `autoCreate` is set)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/EnvironmentValidationError'
      security:
        - bearerAuth: []
components:
  schemas:
    EnvironmentPublishByNameRequest:
      type: object
      properties:
        resourceType:
          $ref: '#/components/schemas/EnvironmentResourceType'
        resourceId:
          type: string
          format: uuid
          description: Canvas (prompt) ID
        envName:
          $ref: '#/components/schemas/EnvironmentName'
        versionId:
          type: string
          format: uuid
          description: ID of the prompt version to publish. Must belong to the canvas.
        autoCreate:
          type: boolean
          description: >-
            Create the environment if it does not exist yet. Not needed for
            `production`, which is always created on demand.
      required:
        - resourceType
        - resourceId
        - envName
        - versionId
      example:
        resourceType: prompt
        resourceId: 95cec438-6080-44fe-8275-28b16bd40178
        envName: staging
        versionId: 76065caa-c519-441a-8fe2-cc43e29664ab
        autoCreate: true
    EnvironmentPublishResult:
      type: object
      properties:
        environment:
          $ref: '#/components/schemas/Environment'
        version:
          $ref: '#/components/schemas/EnvironmentPromptVersion'
      required:
        - environment
        - version
      example:
        environment:
          id: 2f1c9a7e-3b4d-4e5f-8a6b-1c2d3e4f5a6b
          resourceType: prompt
          resourceId: 95cec438-6080-44fe-8275-28b16bd40178
          name: staging
          isSystem: false
          currentVersionId: 76065caa-c519-441a-8fe2-cc43e29664ab
          workspaceId: 3f55cfd9-4427-4887-a181-d9ad39967802
          createdBy: jane@example.com
          deletedBy: null
          createdAt: '2025-06-01T12:00:00.000Z'
          updatedAt: '2025-06-03T10:12:45.000Z'
          deletedAt: null
        version:
          id: 76065caa-c519-441a-8fe2-cc43e29664ab
          promptId: 95cec438-6080-44fe-8275-28b16bd40178
          title: Contract analysis v3
          titleLocked: false
          content: null
          markdownContent: null
          variables:
            - name: document
              type: file
              required: true
          configuration:
            model: gpt-4.1
            temperature: 0
          promoted: false
          draft: false
          originVersionId: 1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7a8b
          workspaceId: 3f55cfd9-4427-4887-a181-d9ad39967802
          workflowSpec: null
          graph: null
          isWorkflow: false
          createdBy: jane@example.com
          updatedBy: jane@example.com
          deletedBy: null
          createdAt: '2025-06-02T15:40:00.000Z'
          updatedAt: '2025-06-03T10:12:45.000Z'
          deletedAt: null
          promptCustomTags: []
          message:
            id: 9c8b7a6f-5e4d-4c3b-a2f1-0e9d8c7b6a5f
            role: system
            content: >-
              You are a contract analyst. Summarize the key clauses of
              {{document}}.
            markdownContent: null
            promptVersionId: 76065caa-c519-441a-8fe2-cc43e29664ab
            index: 0
            createdBy: jane@example.com
            updatedBy: jane@example.com
            createdAt: '2025-06-02T15:40:00.000Z'
            updatedAt: '2025-06-02T15:40:00.000Z'
            deletedAt: null
          messages:
            - id: 9c8b7a6f-5e4d-4c3b-a2f1-0e9d8c7b6a5f
              role: system
              content: >-
                You are a contract analyst. Summarize the key clauses of
                {{document}}.
              markdownContent: null
              promptVersionId: 76065caa-c519-441a-8fe2-cc43e29664ab
              index: 0
              createdBy: jane@example.com
              updatedBy: jane@example.com
              createdAt: '2025-06-02T15:40:00.000Z'
              updatedAt: '2025-06-02T15:40: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
    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
    EnvironmentPromptVersion:
      type: object
      description: >
        A prompt version as returned by environment operations. `variables` and
        `configuration` follow the

        prompt-version schemas of the main API; they are typed loosely here.
      properties:
        id:
          type: string
          format: uuid
        promptId:
          type: string
          format: uuid
          description: Canvas ID
        title:
          type: string
        titleLocked:
          type: boolean
        content:
          type: string
          nullable: true
        markdownContent:
          type: string
          nullable: true
        variables:
          type: array
          description: Variable definitions of the version.
          items:
            type: object
        configuration:
          type: object
          nullable: true
          description: >-
            Model configuration (model, temperature, structured output,
            functions, ...).
        promoted:
          type: boolean
          nullable: true
          description: >-
            `true` when this is the canvas' promoted version (the one served by
            `production`).
        draft:
          type: boolean
          nullable: true
        originVersionId:
          type: string
          format: uuid
          nullable: true
          description: Version this one was duplicated from, if any.
        workspaceId:
          type: string
          format: uuid
        workflowSpec:
          type: string
          nullable: true
          description: Serialized workflow specification, when the version is a workflow.
        graph:
          type: string
          nullable: true
          description: Serialized workflow graph, when the version is a workflow.
        isWorkflow:
          type: boolean
          nullable: true
        createdBy:
          type: string
        updatedBy:
          type: string
        deletedBy:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
        deletedAt:
          type: string
          format: date-time
          nullable: true
        message:
          nullable: true
          description: >-
            First message of the version (`messages[0]`), kept for
            compatibility.
          allOf:
            - $ref: '#/components/schemas/EnvironmentPromptVersionMessage'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/EnvironmentPromptVersionMessage'
        versionIndex:
          type: integer
          description: >-
            1-based position of the version in the canvas history. Present on
            `GET /environment/version`; omitted when it cannot be computed.
        promptCustomTags:
          type: array
          items:
            type: string
          description: Custom tags configured on the canvas.
      required:
        - id
        - promptId
        - title
        - titleLocked
        - variables
        - configuration
        - promoted
        - draft
        - originVersionId
        - workspaceId
        - createdBy
        - updatedBy
        - createdAt
        - updatedAt
        - deletedAt
        - messages
      example:
        id: 76065caa-c519-441a-8fe2-cc43e29664ab
        promptId: 95cec438-6080-44fe-8275-28b16bd40178
        title: Contract analysis v3
        titleLocked: false
        content: null
        markdownContent: null
        variables:
          - name: document
            type: file
            required: true
        configuration:
          model: gpt-4.1
          temperature: 0
        promoted: true
        draft: false
        originVersionId: 1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7a8b
        workspaceId: 3f55cfd9-4427-4887-a181-d9ad39967802
        workflowSpec: null
        graph: null
        isWorkflow: false
        createdBy: jane@example.com
        updatedBy: jane@example.com
        deletedBy: null
        createdAt: '2025-06-02T15:40:00.000Z'
        updatedAt: '2025-06-02T15:45:10.000Z'
        deletedAt: null
        versionIndex: 3
        promptCustomTags: []
        message:
          id: 9c8b7a6f-5e4d-4c3b-a2f1-0e9d8c7b6a5f
          role: system
          content: >-
            You are a contract analyst. Summarize the key clauses of
            {{document}}.
          markdownContent: null
          promptVersionId: 76065caa-c519-441a-8fe2-cc43e29664ab
          index: 0
          createdBy: jane@example.com
          updatedBy: jane@example.com
          createdAt: '2025-06-02T15:40:00.000Z'
          updatedAt: '2025-06-02T15:40:00.000Z'
          deletedAt: null
        messages:
          - id: 9c8b7a6f-5e4d-4c3b-a2f1-0e9d8c7b6a5f
            role: system
            content: >-
              You are a contract analyst. Summarize the key clauses of
              {{document}}.
            markdownContent: null
            promptVersionId: 76065caa-c519-441a-8fe2-cc43e29664ab
            index: 0
            createdBy: jane@example.com
            updatedBy: jane@example.com
            createdAt: '2025-06-02T15:40:00.000Z'
            updatedAt: '2025-06-02T15:40:00.000Z'
            deletedAt: null
    EnvironmentPromptVersionMessage:
      type: object
      description: One message of a prompt version, ordered by `index`.
      properties:
        id:
          type: string
          format: uuid
        role:
          type: string
          description: Message role (for example `system`, `user`, `assistant`).
        content:
          type: string
          nullable: true
        markdownContent:
          type: string
          nullable: true
        promptVersionId:
          type: string
          format: uuid
        index:
          type: integer
        createdBy:
          type: string
        updatedBy:
          type: string
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
        deletedAt:
          type: string
          format: date-time
          nullable: true
      required:
        - id
        - role
        - content
        - markdownContent
        - promptVersionId
        - index
        - createdBy
        - updatedBy
        - createdAt
        - updatedAt
        - deletedAt
  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'
    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.