Completion API overview

The Completion API is the way your own systems run a Canvas. One request to POST /v2/chat/completions sends the inputs of a run (variables, files, chat history) and gets back what the Canvas produced, either in the same response or later through polling or a callback. The same endpoint also runs a published Workflow, and creates a task in a Workstation App when you pass an application_id instead of a canvas_id. This section covers every way to call it:

Variables and files

Fill the Canvas variables with text, file URLs, base64 content or uploaded files

Messages

Send a chat history along with the variables

Versions and environments

Control which version of the Canvas runs

Streaming

Receive the answer as it is generated

Async and webhooks

Run in the background, poll the result or get a callback, and list past runs

Errors and retries

Status codes, the error body and what is safe to retry

Prerequisites

A published Canvas. Only versions published to an environment can be run through the API, and a Draft must be moved into a Project first.
An API key, created in your Workspace settings under API Keys. Keep it on your server. See Authentication.
The Canvas ID, from Connect via API.

Open Connect via API

Click the … button next to your Canvas title at the top left of the page and select Connect via API.

Copy the Canvas ID and a snippet

The dialog shows your Canvas ID and a ready-to-use snippet in the language of your choice. The snippet already lists the variables of the Canvas.

SDK or HTTP

You can call the API with the Tela SDKs (@meistrari/tela-sdk-js for TypeScript and JavaScript, tela for Python) or with any HTTP client. The SDKs map the request fields to camelCase (canvasId, applicationId) and add helpers such as createFile. Over HTTP you send the fields exactly as they appear in the API reference, in snake_case. Every HTTP request goes to https://api.tela.com, with Content-Type: application/json and Authorization: Bearer YOUR_API_KEY.

Minimal request

With only a canvas_id and the variables, the call runs the version published to Production and waits for the result.

import { createTelaClient } from '@meistrari/tela-sdk-js'

const tela = createTelaClient({
    apiKey: process.env.TELA_API_KEY,
})

const completion = await tela.completions.create<{ document: string }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: 'Document content',
    },
})

console.log(completion.choices[0].message.content)

import { createTelaClient } from '@meistrari/tela-sdk-js'

const tela = createTelaClient({
    apiKey: process.env.TELA_API_KEY,
})

const completion = await tela.completions.create({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: 'Document content',
    },
})

console.log(completion.choices[0].message.content)

import os
from tela import create_tela_client

TELA_CANVAS_ID = os.getenv("TELA_CANVAS_ID")
TELA_API_KEY = os.getenv("TELA_API_KEY")

client = create_tela_client(
    api_key=TELA_API_KEY,
)

completion = client.completions.create(
    canvas_id=TELA_CANVAS_ID,
    variables={
        "document": "Document content",
    },
)

print(completion.choices[0].message.content)

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

The response

A synchronous call answers with a chat.completion object. The result is in choices[0].message.content: an object with the fields of your Output Format when the Canvas has one, or the text of the answer otherwise.

{
    "id": "crsv-i52z8vnqekc",
    "object": "chat.completion",
    "created": 1728399621,
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": {
                    "rationale": "The content of the PDF is not provided, so a summary cannot be generated.",
                    "message": "No summary can be generated."
                }
            }
        }
    ]
}

{
    "id": "crsv-i52z8vnqekc",
    "object": "chat.completion",
    "created": 1728399621,
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": {
                    "text": "The content of the PDF is not provided, so a summary cannot be generated."
                }
            }
        }
    ]
}

The response looks different when you stream (stream: true) or run in the background (async: true or webhook_url). Those shapes are described in Streaming and Async and webhooks.

Request fields

Field	Type	What it does
`canvas_id`	string	Runs the Canvas. By default, the version published to Production.
`version_id`	string	Runs one exact version instead of a Canvas.
`application_id`	string	Creates a task in a Workstation App instead of a completion.
`environment_name`	string	With `canvas_id`, runs the version published to that environment.
`variables`	object	Values for the variables of the Canvas: text or files.
`messages`	array	Chat history sent along with the variables.
`stream`	boolean	Streams the answer as it is generated.
`async`	boolean	Returns at once and lets you poll for the result.
`webhook_url`	string	Makes the run asynchronous and POSTs the result to this URL.
`tags`	array of strings	Labels stored with the run, merged with the tags of the Canvas.
`override`	object	Replaces model settings of the Canvas for this request only.

Exactly one of canvas_id, version_id or application_id identifies what to run. stream and async are only available with canvas_id and version_id: tasks always run asynchronously.

Tags sent in the request are merged with the tags configured in the Canvas and can be used to filter past runs. See Tags for the syntax, including dynamic tags such as type-$output.category.

Completions or tasks?

A completion is a stateless run: you send the inputs, you get the output, and the run is recorded in the Canvas Usage. Use it when your system is the one that consumes the result. A task is a run created inside a Workstation App, where your team reviews, edits and approves the output before it is used. Use it when a person must check each result, or when you want the approved results to feed Test Cases. To create one, pass the application_id of the App instead of the canvas_id; the rest of the request is the same. Tasks are always asynchronous and are read back through the /task endpoints. See Creating tasks via API.

Running a Workflow

A published Workflow is run the same way as a Canvas: connect it via the API, send its Inputs as variables and read the result the same way. To follow each step of a run, use the Workflow Run API.

Get started

Build

Test

Operate

Integrate

Completion API overview

Variables and files

Messages

Versions and environments

Streaming

Async and webhooks

Errors and retries

Prerequisites

SDK or HTTP

Minimal request

The response

Request fields

Completions or tasks?

Running a Workflow

Variables and files

Messages

Versions and environments

Streaming

Async and webhooks

Errors and retries

​Prerequisites

​SDK or HTTP

​Minimal request

​The response

​Request fields

​Completions or tasks?

​Running a Workflow

Prerequisites

SDK or HTTP

Minimal request

The response

Request fields

Completions or tasks?

Running a Workflow