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

# Versions and environments

> Choose which version of the Canvas a request runs: Production, another environment or a pinned version

A Canvas has many versions, but only the ones [published to an environment](https://docs.tela.com/en/craft/publishing.md) are reachable through the API. Every request runs exactly one version, and which one depends on how you identify the Canvas in the body.

| You send | What runs |
| - | - |
| `canvas_id` | The version currently published to **Production**. |
| `canvas_id` + `environment_name` | The version currently published to that environment. |
| `version_id` | That exact version, whatever is published. |

## Production by default

With only a `canvas_id`, the request runs the version published to **Production**, the environment every Canvas has. Whenever someone clicks **Publish** to Production, the next request picks up the new version at once.

```sh cURL theme={null}
curl -X POST https://api.tela.com/v2/chat/completions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TELA_API_KEY" \
    -d '{
        "canvas_id": "95cec438-6080-44fe-8275-28b16bd40178",
        "variables": { "document": "Document content" }
    }'
```

> [!WARNING]
>
> Publishing to an environment replaces the version that environment serves, and API calls targeting it change behavior immediately. If a teammate publishes a draft of the prompt to Production, your integration runs it on the next call. The two sections below are how you protect yourself from that.

## Targeting another environment

Besides Production, a Canvas can have custom environments such as `staging`, created in the **Publish version** dialog with **+ New environment**. To run the version published to one of them, add `environment_name` next to `canvas_id`.

```sh cURL theme={null}
curl -X POST https://api.tela.com/v2/chat/completions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TELA_API_KEY" \
    -d '{
        "canvas_id": "95cec438-6080-44fe-8275-28b16bd40178",
        "environment_name": "staging",
        "variables": { "document": "Document content" }
    }'
```

```typescript TypeScript (fetch) theme={null}
const response = await fetch('https://api.tela.com/v2/chat/completions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.TELA_API_KEY}`,
    },
    body: JSON.stringify({
        canvas_id: process.env.TELA_CANVAS_ID,
        environment_name: 'staging',
        variables: { document: 'Document content' },
    }),
})

const completion = await response.json()
```

```python Python (requests) theme={null}
import os
import requests

response = requests.post(
    "https://api.tela.com/v2/chat/completions",
    headers={"Authorization": f"Bearer {os.getenv('TELA_API_KEY')}"},
    json={
        "canvas_id": os.getenv("TELA_CANVAS_ID"),
        "environment_name": "staging",
        "variables": {"document": "Document content"},
    },
)

completion = response.json()
```

Rules for `environment_name`:

* It is the name you gave the environment: lowercase letters, digits and single hyphens between segments, at most 64 characters. `production` is the name of the Production environment.
* It only goes with `canvas_id`. It cannot be combined with `version_id` or `application_id`.
* The request fails with `404` when the environment does not exist or has no published version.

A common setup is one integration pointing at `staging` in your test system and the same code pointing at Production in your live system, with the environment name coming from configuration. You publish a version to `staging`, test it through the API, and only then publish it to Production.

## Pinning a version

To run one specific version no matter what gets published, send `version_id` instead of `canvas_id`. The rest of the request (variables, messages, streaming, async, webhooks) is the same.

```sh cURL theme={null}
curl -X POST https://api.tela.com/v2/chat/completions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TELA_API_KEY" \
    -d '{
        "version_id": "76065caa-c519-441a-8fe2-cc43e29664ab",
        "variables": { "document": "Document content" }
    }'
```

```typescript TypeScript (fetch) theme={null}
const response = await fetch('https://api.tela.com/v2/chat/completions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.TELA_API_KEY}`,
    },
    body: JSON.stringify({
        version_id: '76065caa-c519-441a-8fe2-cc43e29664ab',
        variables: { document: 'Document content' },
    }),
})

const completion = await response.json()
```

```python Python (requests) theme={null}
import os
import requests

response = requests.post(
    "https://api.tela.com/v2/chat/completions",
    headers={"Authorization": f"Bearer {os.getenv('TELA_API_KEY')}"},
    json={
        "version_id": "76065caa-c519-441a-8fe2-cc43e29664ab",
        "variables": {"document": "Document content"},
    },
)

completion = response.json()
```

You find the ID of a version in the **Version History** of the Canvas (the version button next to **Publish**), where each version shows its ID. Through the API, [Get promoted version](https://docs.tela.com/api-reference/prompt-version/get-prompt-id-promoted-version.md) returns the version Production serves and [Get environment version](https://docs.tela.com/api-reference/environment/get-environment-version.md) returns the version of any environment.

Pinning trades convenience for control: a pinned integration never changes behavior unexpectedly, but it also does not receive fixes until you update the `version_id` in your code. Use an environment when you want the team to publish without a deploy on your side, and a pinned version when the integration must be reviewed before any change.

## Knowing which version ran

Every run records the version it used, so you can confirm your setup:

* The result of an asynchronous run has a `prompt_version_id`.
* A completion run listed with `GET /v1/completion-run` has `promptVersionId`, and when the request used `environment_name` its `metadata.requestedEnvironmentName` holds the name you sent.

See [Listing past runs](https://docs.tela.com/en/completion-api/async-and-webhooks.md#listing-past-runs).

## Overriding model settings for one request

The optional `override` object replaces some settings of the version for that request only, without publishing anything. Its `type` is required (`chat` or `completion`); the other fields are optional:

| Field | What it replaces |
| - | - |
| `type` | Whether a chat or a completion model is used. Required. |
| `model` | The model configured in the Canvas. |
| `temperature` | Randomness of the output, between 0 and 1. |
| `functions` | Functions the model can call, each with `name`, `description` and JSON Schema `parameters`. |
| `structured_output` | `enabled` and a JSON `schema` describing the output. |

```json HTTP body theme={null}
{
    "canvas_id": "95cec438-6080-44fe-8275-28b16bd40178",
    "variables": { "document": "Document content" },
    "override": {
        "type": "chat",
        "temperature": 0
    }
}
```

> [!NOTE]
>
> Overrides are not stored in the Canvas. The `raw_input.override` of the run records what was sent. If you need a change for every call, publish a new version instead.


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