Deployment endpoints - list an environment's history, retrieve one deployment with its logs, and roll back to an earlier release.
Deployments
A deployment is one commit, built and released to one environment. Each environment keeps its last 20; the last 10 successful ones stay available as rollback targets.
With an API key the organisation is inferred. Session tokens must add targetOrganisationId to every body.
List deployments#
/api/deploymentsAn environment's deploy history, newest first.
- permission
- read:projects
Parameters
environmentIdstringrequired- The environment to read
limitnumberdefault 20- How many to return
offsetnumberdefault 0- Skip this many
targetOrganisationIdstringsession only- Required when using a session token
curl -X POST https://api.light-cloud.com/api/deployments \
-H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"environmentId": "env_7Tz", "limit": 5}'[
{
"id": "dep_9f2a",
"environment_id": "env_7Tz",
"status": "healthy",
"deployment_stage": "released",
"commit_sha": "9f3c1ab",
"commit_message": "Fix cart total rounding",
"started_at": "2026-08-28T07:00:12.000Z",
"completed_at": "2026-08-28T07:02:40.000Z"
},
{
"id": "dep_7c11",
"environment_id": "env_7Tz",
"status": "failed",
"commit_sha": "2b8e004",
"commit_message": "Bump image deps",
"started_at": "2026-08-27T16:41:03.000Z",
"completed_at": "2026-08-27T16:43:55.000Z"
}
]Retrieve a deployment#
/api/deployments/getOne deployment with its build logs. status moves through pending, building, deploying, then settles on healthy or failed; deployment_stage is the finer step within that.
- permission
- read:projects
Parameters
deploymentIdstringrequired- The deployment to read
targetOrganisationIdstringsession only- Required when using a session token
curl -X POST https://api.light-cloud.com/api/deployments/get \
-H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"deploymentId": "dep_9f2a"}'{
"id": "dep_9f2a",
"environment_id": "env_7Tz",
"status": "healthy",
"deployment_stage": "released",
"commit_sha": "9f3c1ab",
"commit_message": "Fix cart total rounding",
"started_at": "2026-08-28T07:00:12.000Z",
"completed_at": "2026-08-28T07:02:40.000Z",
"deployment_logs": [
"Building container image...",
"Pushing to registry...",
"Released to production"
]
}Tip
Poll environment status rather than this endpoint while a deploy runs. It is cheaper, and it is what the console does.
Roll back#
/api/deployments/rollbackRe-releases an earlier deployment's existing artifact. Nothing is rebuilt, so it takes seconds and the result is byte-identical to what ran before. Only the last 10 successful deployments are eligible.
- permission
- update:projects
Parameters
environmentIdstringrequired- The environment to roll back
deploymentIdstringrequired- The deployment to return to
targetOrganisationIdstringsession only- Required when using a session token
API=https://api.light-cloud.com
AUTH=(-H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" -H "Content-Type: application/json")
# The newest healthy deployment that is not the one currently released
last_good=$(curl -sS -X POST "$API/api/deployments" "${AUTH[@]}" \
-d "{\"environmentId\":\"$ENV_ID\",\"limit\":10}" \
| jq -r '[.[] | select(.status == "healthy")][1].id')
curl -sS -X POST "$API/api/deployments/rollback" "${AUTH[@]}" \
-d "{\"environmentId\":\"$ENV_ID\",\"deploymentId\":\"$last_good\"}"{
"id": "dep_7c11",
"environment_id": "env_7Tz",
"status": "deploying",
"commit_sha": "2b8e004"
}Errors
| Status | Cause |
|---|---|
400 | The deployment is older than the rollback window, or never succeeded |
{ "message": "This deployment can no longer be rolled back to. Only the last 10 successful deployments are kept as rollback targets." }
Note
A rollback does not change which branch the environment tracks. The next push to that branch deploys forwards again, over the rollback.