API-created Environments

API-created Environments are branch-based ephemeral Environments without a pull request. You can create them from the UI or authenticated v2 API.

Create from the UI

1. Open Environments.
2. Select New environment.
3. Select an onboarded repository.
4. Select a branch.
5. If a custom name is necessary, enter a DNS-safe name.
6. Select a lifespan.
7. If advanced options are necessary, expand the section:
   • pause the initial deploy
   • track the source branch automatically
   • override environment values
   • select or change service sources
8. Check the summary.
9. Create the Environment.

Lifecycle reads lifecycle.yaml from the selected source and creates the Environment asynchronously. Open its details page to follow Service and deploy status.

Do not put secret values in environment overrides. Use the repository’s supported secret references and your organization’s secret-management workflow.

Create through v2

The caller needs env:write and access to the selected repository:

A new request returns 202 with data shaped like:

The standard v2 envelope wraps the actual response. Repeating the same idempotencyKey with the same caller and request returns the existing Environment with 200. Reusing it for different input returns a conflict.

Poll to completion

Poll the returned statusUrl with env:read. Terminal statuses are:

• deployed
• error
• config_error
• torn_down

Use bounded polling with backoff. Keep request_id from failures so an operator can correlate the request.

Manage an Environment

An extension starts at the greater value: the current time or the current expiry. The administrator’s maximum lifespan limits the result. If the request does not include hours, Lifecycle uses the configured extension increment.

Use GET /api/v2/environments/policy to get the current default, maximum, and extension values.

Teardown and reuse

Deletion queues teardown and returns 202. Continue polling while the details route returns 200. A subsequent 404 means teardown is complete. You can then reuse its vanity name.

Pull-request inactivity cleanup and keep labels do not change API leases. See Environment expiration and cleanup.

Troubleshooting

• 403: The administrator disabled API Environments, the key lacks env:write, or the repository does not match its constraint.
• 404 repo_not_onboarded: onboard the repository before creating the Environment.
• 409 name_conflict: select a different vanity name or wait for teardown.
• 422 auto_track_pinned_source: do not set autoTrack: true with an immutable sha.

See API overview for response and retry conventions.