Reference
View as MarkdownEnvironments API
Environments.
5 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes
/environments/{environmentId}Update an environment
| Parameter | In | Type | Description |
|---|---|---|---|
environmentIdrequired | path | string |
Request body · application/json · required
- isProductionboolean
- namestring
Response 200 · OK · application/json
- createdAtstring (date-time)required
- idstringrequired
- isProductionbooleanrequired
- kindenum: standard | previewrequired
- namestringrequired
- parentEnvironmentIdstring | nullrequired
- prNumberinteger (int64) | nullrequired
- prTitlestringrequired
- projectIdstringrequired
- slugstringrequired
401Unauthorized403Forbidden404Not Found422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/environments/{environmentId}Delete an empty environment
Fails with 409 environment_not_empty while the environment still has services.
| Parameter | In | Type | Description |
|---|---|---|---|
environmentIdrequired | path | string |
Response 204 · No Content
No body.
401Unauthorized403Forbidden404Not Found409Conflictenvironment_not_empty422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/environments/{environmentId}/cloneClone an environment
Creates a new, non-production environment in the same project with a staged copy of every service of the source: configuration, variables, the environment's shared variables, volume definitions, links, repository links and canvas layout. Slugs are kept, so references such as ${{postgres.DATABASE_URL}} point at the cloned siblings. Secrets are copied sealed and generated values are generated again. Databases are created new and empty: restore a dump into them. Volumes are new and empty. Domains are dropped (default) or cloned with a suffix; 409 domain_conflict when a suffixed hostname is taken. Route services and Compose stacks are skipped and listed. Nothing runs until the services are deployed. dryRun returns the plan and changes nothing.
| Parameter | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | Client-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours. |
environmentIdrequired | path | string |
Request body · application/json · required
- domainSuffixstringDefault: -<new environment slug>
- domainsenum: drop | suffixdrop (default) clones no domain; suffix clones each public domain with domainSuffix added to its first label
- dryRunbooleanReport what the clone would do and change nothing
- namestringrequired
- serverIdstringPlace every cloned service on this server (default: each service keeps its server)
Response 200 · OK · application/json
- CloneDomainOutcome[] | nullrequired
- dryRunbooleanrequired
- CloneEnvironmentRef
- linksinteger (int64)required
- ReferenceFinding[] | nullrequired
- ServiceView
- ClonedService[] | nullrequired
- sharedVariablesinteger (int64)required
- CloneSkipped[] | nullrequired
- warningsstring[] | nullrequired
401Unauthorized403Forbidden404Not Found409Conflictdomain_conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/projects/{projectId}/environmentsList a project's environments
| Parameter | In | Type | Description |
|---|---|---|---|
projectIdrequired | path | string |
Response 200 · OK · application/json
- Environment[] | nullrequired
- nextCursorstringPresent when more items exist
401Unauthorized403Forbidden404Not Found422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/projects/{projectId}/environmentsCreate an environment
| Parameter | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | Client-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours. |
projectIdrequired | path | string |
Request body · application/json · required
- isProductionboolean
- namestringrequired
Response 201 · Created · application/json
- createdAtstring (date-time)required
- idstringrequired
- isProductionbooleanrequired
- kindenum: standard | previewrequired
- namestringrequired
- parentEnvironmentIdstring | nullrequired
- prNumberinteger (int64) | nullrequired
- prTitlestringrequired
- projectIdstringrequired
- slugstringrequired
401Unauthorized403Forbidden404Not Found409Conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.