Skip to main content
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

​
Authentication

Every request needs an API key in the Authorization header:
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 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 and Creating tasks via API guides walk through each option, and the Workstation Events 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:

​
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 for what each input accepts.