Versions and environments

A Canvas has many versions, but only the ones published to an environment 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.

cURL

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" }
    }'

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.

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" }
    }'

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()

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.

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" }
    }'

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()

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 returns the version Production serves and Get environment version 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.

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.

HTTP body

{
    "canvas_id": "95cec438-6080-44fe-8275-28b16bd40178",
    "variables": { "document": "Document content" },
    "override": {
        "type": "chat",
        "temperature": 0
    }
}

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.

Get started

Build

Test

Operate

Integrate

Versions and environments

Production by default

Targeting another environment

Pinning a version

Knowing which version ran

Overriding model settings for one request

​Production by default

​Targeting another environment

​Pinning a version

​Knowing which version ran

​Overriding model settings for one request

Production by default

Targeting another environment

Pinning a version

Knowing which version ran

Overriding model settings for one request