Authentication

The Tella API uses Bearer token authentication. Send a Tella API key or a WorkOS access token in the Authorization header.

Getting your API key

Sign in to Tella
Navigate to Settings > API Keys
Click Create key
Copy and securely store your key

API keys are shown only once when created. If you lose your key, you’ll need to generate a new one.

Using your API key

Include your API key in the Authorization header of every request:

Authorization: Bearer tella_pk_xxxxx...

Example request

curl -H "Authorization: Bearer tella_pk_your_api_key" \
  https://api.tella.com/v1/videos

WorkOS access tokens

You can also send a WorkOS access token as a Bearer token to /v1 endpoints. A claimed WorkOS agent-registration token authenticates as the Tella user who claimed it, in the workspace identified by its org_id claim. Unclaimed registrations and tokens without a recognized workspace cannot authenticate to the public API. See Tella’s agent authentication guide for the registration and claim flow.

API key format

Tella API keys follow this format:

tella_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Prefix: tella_pk_ (identifies it as a Tella public API key)
Suffix: 32 random alphanumeric characters

Security best practices

Never expose your API key

Don’t commit API keys to version control
Don’t include them in client-side code
Use environment variables to store keys

Use environment variables

# Set the environment variable
export TELLA_API_KEY="tella_pk_your_api_key"

# Use it in your code
curl -H "Authorization: Bearer $TELLA_API_KEY" \
  https://api.tella.com/v1/videos

Rotate keys regularly

Generate new API keys periodically and revoke old ones. This limits the impact if a key is compromised.

Use separate keys for different environments

Create separate API keys for development, staging, and production environments.

Idempotent requests

A request that creates or changes something (POST, PATCH, PUT, DELETE) can be resent safely by sending an Idempotency-Key header: any string of at most 255 characters that is unique for your credential, such as a UUID. If the first attempt completed but its response was lost (timeout, dropped connection), the resend returns the stored outcome instead of applying the change again. For a claimed agent registration, keys remain scoped to the same registration when its access token rotates.

curl -X POST https://www.tella.tv/api/public/v1/videos/vid_abc123/clips \
  -H "Authorization: Bearer $TELLA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sourceId": "src_xyz"}'

The outcome is stored for 24 hours and replayed for an identical request (same method, path, query string and body).
Reusing a key with a different request returns 400 bad_request.
Resending while the first attempt is still running returns 409 conflict; retry after a moment.
429 rate_limited, 409 edit_conflict and pre-execution 503 unavailable outcomes are not stored, so those requests can be retried with the same key.
A generic 500 server_error is stored and replayed because the failure may have happened after the change was applied. Check whether it applied before trying again with a new key.
If the key itself cannot be recorded, the request is not executed and answers 503 unavailable with a Retry-After header; resend it unchanged.
A key whose first attempt ended without recording an outcome (for example, the request was cut off) keeps returning 409 conflict rather than running the request again. If a resend still answers 409 after a few minutes, check whether the change applied, then continue with a new key.

Requests without the header are never deduplicated. MCP tool calls use the same mechanism through _meta.idempotencyKey; see MCP server.

Error responses

401 Unauthorized

Returned when the Bearer credential is missing or invalid:

{
  "error": "unauthorized",
  "description": "Invalid API key"
}

Common causes:

Missing Authorization header
Incorrect API key format
Revoked or expired API key

403 Forbidden

Returned when the API key doesn’t have permission for the requested resource:

{
  "error": "forbidden",
  "description": "Access denied to this resource"
}

409 Conflict

Returned when the request conflicts with the resource’s current state, for example a resend whose first attempt under the same Idempotency-Key is still in progress:

{
  "error": "conflict",
  "message": "A request with this Idempotency-Key is still in progress"
}

503 Service Unavailable

Returned when a dependency refused before the request did anything, for example when an Idempotency-Key could not be recorded. Unlike a 500, nothing was executed: resend the same request after the Retry-After delay.

{
  "error": "unavailable",
  "message": "The Idempotency-Key could not be recorded and the request was not executed; retry it"
}

404 Not Found

Returned when the API path doesn’t exist:

{
  "error": "not_found",
  "message": "API endpoint not found",
  "resolution": "Use the OpenAPI description to find a supported path and method.",
  "docsUrl": "https://api.tella.com/openapi.json"
}

Use the docsUrl value to find the supported endpoint and method.

Revoking API keys

To revoke an API key:

Go to Settings > API Keys
Find the key you want to revoke
Click Revoke

Revoked keys immediately stop working for all requests.

Getting Started

Guides

MCP Tools

API Reference

Webhooks

Authentication

Authentication

Getting your API key

Using your API key

Example request

WorkOS access tokens

API key format

Security best practices

Idempotent requests

Error responses

401 Unauthorized

403 Forbidden

409 Conflict

503 Service Unavailable

404 Not Found

Revoking API keys

​Authentication

​Getting your API key

​Using your API key

​Example request

​WorkOS access tokens

​API key format

​Security best practices

​Idempotent requests

​Error responses

​401 Unauthorized

​403 Forbidden

​409 Conflict

​503 Service Unavailable

​404 Not Found

​Revoking API keys

Authentication

Getting your API key

Using your API key

Example request

WorkOS access tokens

API key format

Security best practices

Idempotent requests

Error responses

401 Unauthorized

403 Forbidden

409 Conflict

503 Service Unavailable

404 Not Found

Revoking API keys