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

# Introduction

> Base URL, authentication and conventions shared by every Tela API endpoint

The Tela API lets you run a published Canvas or Workflow, create tasks in an App, manage versions and environments, and receive Workstation Events in your own systems. Every endpoint in this reference follows the conventions below.

## Base URL

```
https://api.tela.com
```

## Authentication

Every request needs an API key in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

API keys are created in your Workspace settings, under **API Keys**. A key is scoped to the Workspace it was created in, so it can only reach the Canvases, Apps and tasks of that Workspace. Keep it on your server: never ship it in a browser or mobile app.

## Compatibility date

Some endpoints, such as the file upload ones, require an `x-compatibility-date` header with a date in `YYYY-MM-DD` format, for example `2025-07-23`. It pins the behavior of the API to what it was on that date, so later changes do not break your integration. Pick the date you started building and keep it until you are ready to adopt newer behavior.

## Which version runs

A Canvas has many versions, but only the ones published to an **environment** are reachable through the API. By default a call runs the version published to **Production**. To run another environment, or a specific version, pass its identifier in the request. See [Publishing and environments](https://docs.tela.com/en/craft/publishing.md) for how versions reach an environment.

## Sync, async and events

Running a Canvas with `POST /v2/chat/completions` returns the result in the same response. For long documents, pass `async: true` and poll `GET /v2/chat/completions/{id}`, or pass a `webhook_url` to be called when the run finishes. Tasks created in an App always run asynchronously. The [Completion API](https://docs.tela.com/en/completion-api/overview.md) and [Creating tasks via API](https://docs.tela.com/en/creating-tasks.md) guides walk through each option, and the [Workstation Events](https://docs.tela.com/en/workstation/events/overview.md) guide covers the events an App can send to your endpoint.

## Errors

Errors use standard HTTP status codes: `400` for an invalid body, `401` for a missing or invalid key, `403` when the key cannot access the resource, `404` when it does not exist and `5xx` for failures on our side. The body is a JSON object with a `code`, a `message` and the `status`:

```json theme={null}
{
  "code": "NOT_FOUND",
  "message": "Task not found",
  "status": 404,
  "name": "Error"
}
```

## Pagination

List endpoints accept `limit` and `offset` query parameters and return the matching items together with the total count, so you can page through large collections. Each endpoint documents its defaults and maximum page size.

## Files

Files can be sent as a public URL, as base64 content, or uploaded first through the file endpoints and then referenced by the returned identifier. See [Supported file formats](https://docs.tela.com/en/supported-file-formats.md) for what each input accepts.


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