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

# Completion API overview

> Run a published Canvas or Workflow from your code with POST /v2/chat/completions

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](https://docs.tela.com/en/completion-api/variables-and-files.md)**
>
> Fill the Canvas variables with text, file URLs, base64 content or uploaded files

> **[Messages](https://docs.tela.com/en/completion-api/messages.md)**
>
> Send a chat history along with the variables

> **[Versions and environments](https://docs.tela.com/en/completion-api/versions-and-environments.md)**
>
> Control which version of the Canvas runs

> **[Streaming](https://docs.tela.com/en/completion-api/streaming.md)**
>
> Receive the answer as it is generated

> **[Async and webhooks](https://docs.tela.com/en/completion-api/async-and-webhooks.md)**
>
> Run in the background, poll the result or get a callback, and list past runs

> **[Errors and retries](https://docs.tela.com/en/completion-api/errors-and-retries.md)**
>
> Status codes, the error body and what is safe to retry

## Prerequisites

* A [published Canvas](https://docs.tela.com/en/craft/publishing.md). 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](https://docs.tela.com/api-reference/introduction.md#authentication).
* The Canvas ID, from **Connect via API**.

**1. Open Connect via API**

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

![Canvas menu with Connect via API](https://mintcdn.com/meistrari/jZ7VrspVjrdqJJQA/images/guides/integrating-api/deploy-focus.png?fit=max\&auto=format\&n=jZ7VrspVjrdqJJQA\&q=85\&s=264580f71708d8c97863aaaaa5b7ebda)

**2. 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.

![Connect via API modal](https://mintcdn.com/meistrari/jZ7VrspVjrdqJJQA/images/guides/integrating-api/api-connect-focus.png?fit=max\&auto=format\&n=jZ7VrspVjrdqJJQA\&q=85\&s=012c183afdda1e581e9c9c3ecaf301fd)

## 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](https://docs.tela.com/api-reference/completion/create.md), 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.

```typescript TypeScript Tela SDK theme={null}
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)
```

```javascript JavaScript Tela SDK theme={null}
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)
```

```python Python Tela SDK theme={null}
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)
```

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

## 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](https://docs.tela.com/en/craft/output-format.md) when the Canvas has one, or the text of the answer otherwise.

```json With Output Format theme={null}
{
    "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."
                }
            }
        }
    ]
}
```

```json Plain text theme={null}
{
    "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](https://docs.tela.com/en/completion-api/streaming.md) and [Async and webhooks](https://docs.tela.com/en/completion-api/async-and-webhooks.md).

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

> [!TIP]
>
> Tags sent in the request are merged with the tags configured in the Canvas and can be used to filter past runs. See [Tags](https://docs.tela.com/en/tags.md#sending-tags-via-api) 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](https://docs.tela.com/en/creating-tasks.md).

## Running a Workflow

A [published Workflow](https://docs.tela.com/en/creating-your-first-workflow.md#running-testing-and-publishing) 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](https://docs.tela.com/api-reference/workflow-run/get-workflow-runs.md).


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