LIGHTCLOUD
DOCS
Documentation menu

Environment endpoints - list, create, update settings and variables, scale, deploy, read logs and metrics, and password-protect.

Environments

An environment is one branch of one application, with its own URL, variables, and scaling. Every application has a production environment from birth; the rest you create.

With an API key the organisation is inferred. Session tokens must add targetOrganisationId to every body.

List environments#

POST/api/environments

Every environment of one application. Returns an array, not a paginated envelope.

permission
read:projects

Parameters

applicationIdstringrequired
The application to read
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/environments \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app_4kQ2"}'
200ResponseEnvironments
[
  {
    "id": "env_7Tz",
    "application_id": "app_4kQ2",
    "name": "production",
    "github_branch": "main",
    "is_production": true,
    "status": "healthy",
    "url": "https://main-shop-acme.light-cloud.io",
    "custom_domain": "shop.example.com",
    "created_at": "2026-08-01T09:14:00.000Z",
    "updated_at": "2026-08-28T07:02:00.000Z"
  }
]

Retrieve an environment#

POST/api/environments/get

One environment, including its environment_vars.

permission
read:projects

Parameters

environmentIdstringrequired
The environment to read
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/environments/get \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environmentId": "env_7Tz"}'
200ResponseAn environment
{
  "id": "env_7Tz",
  "application_id": "app_4kQ2",
  "name": "production",
  "github_branch": "main",
  "is_production": true,
  "status": "healthy",
  "url": "https://main-shop-acme.light-cloud.io",
  "environment_vars": { "NODE_ENV": "production" },
  "min_instances": 0,
  "max_instances": 5
}

Retrieve status#

POST/api/environments/status

Cheaper than retrieve. Poll this while a deploy runs.

permission
read:projects

Parameters

environmentIdstringrequired
The environment to poll
targetOrganisationIdstringsession only
Required when using a session token
until [ "$(curl -sS -X POST https://api.light-cloud.com/api/environments/status \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"environmentId\":\"$ENV_ID\"}" | jq -r .status)" = "healthy" ]; do
  sleep 10
done
200ResponseCurrent status
{ "id": "env_7Tz", "status": "deploying" }

Create an environment#

POST/api/environments/create

Adds a branch environment to an application. See preview environments for what the platform creates on its own.

permission
create:projects

Parameters

applicationIdstringrequired
The application to add it to
namestringrequired
Becomes part of the URL
githubBranchstringrequired
The branch this environment tracks
isProductionbooleandefault false
Whether this is the production environment
autoDeploybooleanoptional
Deploy on every push to the branch
buildCommandstringdefault inherited
Falls back to the application's
outputDirectorystringdefault inherited
Falls back to the application's
environmentVarsobjectoptional
String values only
containerPortnumberoptional
Container only
memorystringoptional
Container only
cpustringoptional
Container only
minInstancesnumberdefault 0
0 to 5
maxInstancesnumberdefault 10
1 to 100, plan-capped
customDomainstringoptional
Can be added later
curl -X POST https://api.light-cloud.com/api/environments/create \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_4kQ2",
    "name": "staging",
    "githubBranch": "develop",
    "autoDeploy": true,
    "environmentVars": { "NODE_ENV": "staging" }
  }'
201ResponseThe created environment
{
  "id": "env_2Bd",
  "application_id": "app_4kQ2",
  "name": "staging",
  "github_branch": "develop",
  "is_production": false,
  "status": "pending"
}

Update an environment#

POST/api/environments/update

Changes settings or variables. Variables take effect on the next build, so deploy afterwards.

permission
update:projects

Parameters

environmentIdstringrequired
The environment to update
namestringoptional
Renaming changes the URL
buildCommandstringoptional
Command that produces the build
outputDirectorystringoptional
Static only
environmentVarsobjectoptional
Replaces the whole set — see the warning below
containerPortnumberoptional
Container only
memorystringoptional
Container only
cpustringoptional
Container only
minInstancesnumberoptional
0 to 5
maxInstancesnumberoptional
1 to 100, plan-capped
regionstringoptional
See Limits
customDomainstringoptional
Attached hostname
autoDeploybooleanoptional
Deploy on every push
API=https://api.light-cloud.com
AUTH=(-H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" -H "Content-Type: application/json")

# Read, merge, write — sending a partial map deletes the rest
current=$(curl -sS -X POST "$API/api/environments/get" "${AUTH[@]}" \
  -d "{\"environmentId\":\"$ENV_ID\"}")

vars=$(echo "$current" | jq '.environment_vars + {"FEATURE_CHECKOUT_V2":"true"}')

curl -sS -X POST "$API/api/environments/update" "${AUTH[@]}" \
  -d "{\"environmentId\":\"$ENV_ID\",\"environmentVars\":$vars}"

curl -sS -X POST "$API/api/environments/deploy" "${AUTH[@]}" \
  -d "{\"environmentId\":\"$ENV_ID\"}"
200ResponseThe updated environment
{ "id": "env_7Tz", "environment_vars": { "NODE_ENV": "production", "FEATURE_CHECKOUT_V2": "true" } }

Warning

environmentVars replaces the whole set, it does not merge. Send only the keys you want and every variable you left out is deleted. Read the environment first, merge, then send it all back.

Scale#

POST/api/environments/scale

Changes the instance range without a rebuild. Sending neither bound is a 400.

permission
update:projects

Parameters

environmentIdstringrequired
The environment to scale
minInstancesnumberone of two
0 to 5. Above 0 keeps instances warm
maxInstancesnumberone of two
1 to 100, plan-capped
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/environments/scale \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environmentId": "env_7Tz", "minInstances": 1, "maxInstances": 20}'
200ResponseThe updated environment
{ "id": "env_7Tz", "min_instances": 1, "max_instances": 20 }

Deploy#

POST/api/environments/deploy

Builds the environment's branch at its current head and releases it. Returns as soon as the deployment starts.

permission
update:projects

Parameters

environmentIdstringrequired
The environment to deploy
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/environments/deploy \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environmentId": "env_7Tz"}'
200ResponseThe deployment that just started
{ "id": "dep_9f2a", "environment_id": "env_7Tz", "status": "pending" }

Delete an environment#

POST/api/environments/delete

Removes the environment and everything running in it. The production environment goes only with its application.

permission
delete:projects

Parameters

environmentIdstringrequired
The environment to delete
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/environments/delete \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environmentId": "env_2Bd"}'
200ResponseDeletion accepted
{ "message": "Environment deleted" }

Read logs#

POST/api/environments/logs

Runtime logs, kept 7 days. Returns an array of log lines.

permission
read:projects

Parameters

environmentIdstringrequired
The environment to read
filters.startTimestringoptional
RFC 3339 timestamp
filters.endTimestringoptional
RFC 3339 timestamp
filters.severitystring[]optional
Severity names, OR-ed together
filters.textSearchstringoptional
Substring match on the message
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/environments/logs \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"environmentId\": \"env_7Tz\",
    \"filters\": {
      \"startTime\": \"$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ)\",
      \"severity\": [\"ERROR\", \"CRITICAL\"],
      \"textSearch\": \"checkout\"
    }
  }"
200ResponseLog lines
[
  "2026-08-28T09:41:02Z ERROR checkout: payment intent expired",
  "2026-08-28T09:41:02Z ERROR checkout: returning 502 to client"
]

For a live tail there is a server-sent events stream:

GET /api/environments/:targetOrganisationId/:environmentId/logs/stream

Read detailed metrics#

POST/api/environments/metrics/detailed

Time series for one environment. Omitting metrics returns all of them.

permission
read:projects

Parameters

environmentIdstringrequired
The environment to measure
timeRangestringrequired
1h, 6h, 24h or 7d
metricsstring[]optional
cpu, memory, requestCount, latency, instanceCount, bandwidthOut, bandwidthIn
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/environments/metrics/detailed \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environmentId": "env_7Tz",
    "timeRange": "24h",
    "metrics": ["cpu", "memory", "requestCount"]
  }'
200ResponseSeries per metric
{
  "environmentId": "env_7Tz",
  "deploymentType": "container",
  "timeRange": {
    "startTime": "2026-08-27T09:00:00.000Z",
    "endTime": "2026-08-28T09:00:00.000Z"
  },
  "metrics": {
    "cpu": [{ "t": "2026-08-28T08:00:00.000Z", "v": 0.34 }],
    "requestCount": [{ "t": "2026-08-28T08:00:00.000Z", "v": 1284 }]
  }
}

There is also POST /api/environments/metrics/sparkline, which takes environmentIds (an array) and returns small series for several environments at once, for list views.

Read activity#

POST/api/environments/activity

Settings and variable changes, without the values.

permission
read:projects

Parameters

environmentIdstringrequired
The environment to read
limitnumberoptional
How many entries to return
offsetnumberoptional
Skip this many
curl -X POST https://api.light-cloud.com/api/environments/activity \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environmentId": "env_7Tz", "limit": 20}'
200ResponseActivity entries
[
  {
    "id": "act_5Wq",
    "action": "environment_vars_updated",
    "actor_email": "you@example.com",
    "created_at": "2026-08-28T07:00:00.000Z"
  }
]

Password protection#

POST/api/environments/password

Puts a password wall in front of the environment's URL. enabled must be a boolean, not a string.

permission
update:projects

Parameters

environmentIdstringrequired
The environment to protect
enabledbooleanrequired
Turns the wall on or off
passwordstringdefault when enabling
The password visitors must enter
curl -X POST https://api.light-cloud.com/api/environments/password \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environmentId": "env_2Bd", "enabled": true, "password": "preview-only"}'
200ResponseProtection state
{ "id": "env_2Bd", "password_protected": true }

Visitors exchange the password for access at POST /api/environments/unlock, with body environmentId and password. That endpoint takes no bearer token — it is what the wall itself calls, and it is rate limited per address.

Domains#

check-domain, add-domain, and retry-domain also exist under /api/environments, with the same bodies as their application counterparts, addressed by environmentId.

Related#

ApplicationsThe parent resource.DeploymentsWhat a deploy produced.Environment variablesBuild-time versus runtime.