Environments
List the environments in a project
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments \ -H "Authorization: Bearer kc_your_api_token"[ { "id": "acct_01example0000000000000000x", "accountId": "acct_01example0000000000000000x", "projectId": "project_01example0000000000000000x", "name": "my-app", "createdAt": "2026-01-01T00:00:00.000Z" }]Create an environment in a project
Creates the environment with the given immutable identity name (a url-safe word, unique within the project). Services are added separately via the services API.
The immutable identity name (url-safe word, 3-16 chars, unique within the project). Pick carefully — it cannot be renamed.
Unique identifier of the environment.
Id of the account that owns the environment.
Id of the project this environment belongs to.
The environment’s IDENTITY: an immutable, project-unique, url-safe word picked at create (e.g. production, staging). There is no separate display name.
Read-only: when the environment was created.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{ "name": "my-app" }'{ "id": "acct_01example0000000000000000x", "accountId": "acct_01example0000000000000000x", "projectId": "project_01example0000000000000000x", "name": "my-app", "createdAt": "2026-01-01T00:00:00.000Z"}Get an environment with its services + status
Unique identifier of the environment.
Id of the account that owns the environment.
Id of the project this environment belongs to.
The environment’s IDENTITY: an immutable, project-unique, url-safe word picked at create (e.g. production, staging). There is no separate display name.
Read-only: when the environment was created.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId \ -H "Authorization: Bearer kc_your_api_token"{ "id": "acct_01example0000000000000000x", "accountId": "acct_01example0000000000000000x", "projectId": "project_01example0000000000000000x", "name": "my-app", "createdAt": "2026-01-01T00:00:00.000Z"}Delete an environment
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId \ -X DELETE \ -H "Authorization: Bearer kc_your_api_token"Clone an environment into a new one
Creates a new environment in the same project (with a fresh slug, inheriting the source's locations) and copies the source's services — their specs, variables (ordinary values, connections, and aliases), toggles and volume sizes. Sensitive values and volume DATA are NOT copied (the response's `sensitiveVariablesToSet` and `environmentSensitiveVariablesToSet` list the variable names to re-enter), and custom domains are not copied. Managed databases clone as fresh, empty instances. Send an `Idempotency-Key` header to make a retried clone safe (the key is scoped per source environment).
The immutable identity name for the clone (url-safe word, unique within the project).
The newly created environment (a clone of the source).
Per-service sensitive variables whose name was carried to the clone but whose value must be set.
Names of the environment-scoped sensitive variables carried to the clone WITHOUT a value — a sensitive value never leaves its environment (§7); each must be (re-)entered on the clone.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/clone \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{ "name": "my-app" }'{ "environment": { "id": "acct_01example0000000000000000x", "accountId": "acct_01example0000000000000000x", "projectId": "project_01example0000000000000000x", "name": "my-app", "createdAt": "2026-01-01T00:00:00.000Z" }, "sensitiveVariablesToSet": [ { "serviceName": "example", "names": [ "example" ] } ], "environmentSensitiveVariablesToSet": [ "example" ]}Promote a source environment’s services onto this one
Overwrites THIS environment's services, config and images to match the source environment (`sourceId` in the body). This environment's custom domains and its own sensitive values are preserved; the source's variables — ordinary values, connections, and aliases — are promoted, along with its service specs, toggles and image sources. Set `dryRun` to preview exactly what will be created, updated, deleted, and destroyed. `confirmServiceDeletions` is required when the promote would delete a service or destroy a volume.
Id of the source environment whose services are promoted onto this one.
Acknowledge the destructive effects of the promote: services present in this environment but absent from the source are deleted, and any persistent volume the promote removes is destroyed. Required when the promote would delete a service or destroy a volume.
Preview the changes without applying them — returns what would be created, updated, deleted, and destroyed.
Whether this was a preview (no changes applied).
The changes the promote made (or would make, on a dry run).
A deployment target inside a project; its services + domains are fetched separately.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/promote \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{ "sourceId": "source_01example0000000000000000x" }'{ "dryRun": true, "preview": { "services": { "create": [ { "name": "my-app", "type": "web" } ], "update": [ { "name": "my-app", "willRedeploy": true } ], "delete": [ { "name": "my-app", "type": "web" } ] }, "volumesDestroyed": [ { "serviceName": "example", "mountPath": "example", "sizeGb": 1 } ], "domainsOrphaned": [ { "hostname": "example", "serviceName": "example" } ], "sensitiveVariablesSkipped": [ { "serviceName": "example", "names": [ "example" ] } ], "blockers": [ { "serviceName": "example", "reason": "example", "detail": "example" } ] }, "environment": { "id": "acct_01example0000000000000000x", "accountId": "acct_01example0000000000000000x", "projectId": "project_01example0000000000000000x", "name": "my-app", "createdAt": "2026-01-01T00:00:00.000Z" }}