Environments

Every app has the environments production and preview. Settings and variables changed here apply from the next deployment. See Environments.

List environmentsCopy Anchor Link

POST /v1/environments.listEnvironments

Returns an app's environments with their settings.

Permissions: the key needs environment.*.read_environment.

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/environments.listEnvironments \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web"
  }'

ResponseCopy Anchor Link

On success the status is 200 OK. The fields in data:

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.

Get an environmentCopy Anchor Link

POST /v1/environments.getEnvironment

Returns one environment with its build, runtime and region settings.

Permissions: the key needs one of environment.*.read_environment, environment.<environment_id>.read_environment.

RequestCopy Anchor Link

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

ResponseCopy Anchor Link

On success the status is 200 OK. The fields in data:

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.

Update settingsCopy Anchor Link

POST /v1/environments.updateSettings

Changes an environment's build, runtime and region settings. Fields you leave out stay as they are. Send null to clear a field that allows it. The changes apply from the next deployment.

Permissions: the key needs one of environment.*.update_environment, environment.<environment_id>.update_environment.

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/environments.updateSettings \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web",
    "environment": "production",
    "memoryMib": 1024,
    "healthcheck": {
      "method": "GET",
      "path": "/health",
      "intervalSeconds": 15
    }
  }'

ResponseCopy Anchor Link

On success the status is 200 OK.

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.

List variablesCopy Anchor Link

POST /v1/environments.listEnvironmentVariables

Returns an environment's variables, a page at a time. Values of sensitive variables are never returned.

Permissions: the key needs one of environment.*.read_environment_variables, environment.<environment_id>.read_environment_variables.

RequestCopy Anchor Link

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

ResponseCopy Anchor Link

On success the status is 200 OK. The fields in data:

When pagination.hasMore is true, pass pagination.cursor as cursor to get the next page.

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.

Set variablesCopy Anchor Link

POST /v1/environments.setEnvironmentVariables

Creates or overwrites variables. Variables not in the list stay as they are, unless prune is true. The whole call succeeds or fails together. Running deployments keep their old values until the next deployment.

Permissions: the key needs one of environment.*.set_environment_variables, environment.<environment_id>.set_environment_variables.

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/environments.setEnvironmentVariables \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web",
    "environment": "production",
    "variables": [
      {
        "key": "DATABASE_URL",
        "value": "postgres://…"
      },
      {
        "key": "LOG_LEVEL",
        "value": "info",
        "kind": "recoverable"
      }
    ]
  }'

ResponseCopy Anchor Link

On success the status is 200 OK.

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.

Remove variablesCopy Anchor Link

POST /v1/environments.removeEnvironmentVariables

Deletes variables by name. Names that don't exist are skipped. The whole call succeeds or fails together.

Permissions: the key needs one of environment.*.remove_environment_variables, environment.<environment_id>.remove_environment_variables.

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/environments.removeEnvironmentVariables \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web",
    "environment": "production",
    "variables": [
      "LOG_LEVEL"
    ]
  }'

ResponseCopy Anchor Link

On success the status is 200 OK.

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.