Deployments

See Deployments for the lifecycle and Rollbacks for how promoting and rolling back behave.

To deploy from CI, call deployments.createDeployment, then call deployments.getDeployment every few seconds until status is ready, or one of failed, cancelled, superseded or skipped.

Create a deploymentCopy Anchor Link

POST /v1/deployments.createDeployment

Starts a deployment and returns its ID right away. The build and rollout continue in the background. Send exactly one source: git to build a branch or commit, image to run an image, or deployment to run an earlier deployment again with the current settings.

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

RequestCopy Anchor Link

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"
    }
  }'

ResponseCopy Anchor Link

On success the status is 201 Created. The fields in data:

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

Get a deploymentCopy Anchor Link

POST /v1/deployments.getDeployment

Returns a deployment with its status, source, resources and URLs.

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

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/deployments.getDeployment \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentId": "d_7k2PqXv9"
  }'

ResponseCopy Anchor Link

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

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

List deploymentsCopy Anchor Link

POST /v1/deployments.listDeployments

Returns deployments, newest first, a page at a time. Filter by project, app, environment and status.

Permissions: the key needs environment.*.read_deployment.

RequestCopy Anchor Link

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

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.

Promote a deploymentCopy Anchor Link

POST /v1/deployments.promoteDeployment

Makes a production deployment the live one and ends a rolled-back state, so later pushes take over production again. Returns 202 once the switch is accepted.

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

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/deployments.promoteDeployment \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentId": "d_7k2PqXv9"
  }'

ResponseCopy Anchor Link

On success the status is 202 Accepted.

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

Roll backCopy Anchor Link

POST /v1/deployments.rollbackDeployment

Moves production traffic to an earlier production deployment and keeps it there: new pushes still deploy, but don't take over until you promote one. Returns 202 once the switch is accepted.

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

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/deployments.rollbackDeployment \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentId": "d_3h8LmQw2"
  }'

ResponseCopy Anchor Link

On success the status is 202 Accepted.

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

Stop a deploymentCopy Anchor Link

POST /v1/deployments.stopDeployment

Stops a running preview deployment. Production deployments can't be stopped.

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

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/deployments.stopDeployment \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentId": "d_9t4RkZy1"
  }'

ResponseCopy Anchor Link

On success the status is 202 Accepted.

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

Start a deploymentCopy Anchor Link

POST /v1/deployments.startDeployment

Starts a stopped preview deployment again, without building anything.

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

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/deployments.startDeployment \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentId": "d_9t4RkZy1"
  }'

ResponseCopy Anchor Link

On success the status is 202 Accepted.

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