API

Everything you do in the dashboard can be done through the API: create apps, deploy from CI, change variables or manage domains.

BasicsCopy Anchor Link

• Base URL: https://api.teral.dev
• Authentication: an API key as a bearer token, Authorization: Bearer <key>
• Style: every operation is a POST to /v1/<group>.<operation> with a JSON body, also when it only reads.
• Identifiers: where a request names a project, app or environment, you can pass its ID (proj_…, app_…, env_…) or its slug.
• Times are Unix timestamps in milliseconds.
• Permissions: each operation lists the permissions the key needs. A permission with * covers every resource of that type, one with an ID only that resource.

curl -X POST https://api.teral.dev/v1/deployments.createDeployment \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web",
    "environment": "production",
    "git": { "branch": "main" }
  }'

ResponsesCopy Anchor Link

A successful response has the result in data, and meta.requestId:

{
  "meta": { "requestId": "req_2v8…" },
  "data": { "deploymentId": "d_7k2…" }
}

List operations take limit and cursor. When pagination.hasMore is true, send pagination.cursor as cursor to get the next page.

ErrorsCopy Anchor Link

A failed request returns an HTTP error status and a JSON body:

{
  "meta": { "requestId": "req_2v8…" },
  "error": {
    "title": "Not Found",
    "detail": "Project 'shop' was not found.",
    "status": 404,
    "type": "https://docs.teral.dev/errors/teral/data/project_not_found"
  }
}

type links to the page for that error and identifies it. Use it rather than detail when your code needs to react to a specific error. detail is meant for people and can change. Validation errors also list each problem in errors. See Errors for every error.

Include meta.requestId when you contact support.

License and source codeCopy Anchor Link

Teral is a modified version of Unkey and is licensed under the GNU Affero General Public License v3 (AGPL-3.0). The complete source code of every deployed version, of the API and the rest of Teral, is available at teral-source.s3.eu-central-1.amazonaws.com.

Every API response names the license and links to the source of the exact version that answered it:

The OpenAPI spec says the same in its info section.

ReferenceCopy Anchor Link

Every operation, with its fields, permissions and an example:

Operations under deploy.* are internal and can change without notice. Use deployments.* instead.