Deployments
Deploy a service
Service name within the environment.
Optionally pins an exact image ref; omit to deploy the service's configured source image ref.
Unique identifier of this deployment.
Identifier of the service this deployment belongs to.
Monotonic version number of the deployment within its service.
Resolved container image reference deployed by this release.
Identifier of the build that produced this image, when built from source.
Git branch this release was built from, when built from a git source.
Resolved commit SHA this release was built from, when built from a git source.
The uploaded build-context archive this release was built from (`koo up`).
Pipeline state, a fixed linear sequence: `queued` = accepted, waiting; `building` = the image builder is running (source builds only); `built` = image built and pushed, awaiting apply; `applied` = the release is applied to the platform — the pipeline is DONE (this is not a health verdict: the service may still be starting or unhealthy — see the service status); `failed` = the build or apply failed (see `errors`); `superseded` = a newer deployment replaced this one before it applied. Image deploys skip the build phases (queued → applied).
Live builder stage caption while `building` (e.g. "cloning", "building") — best-effort display detail; the authoritative build state is `status` + the timestamps.
Fatal pipeline failures (populated when `status` is `failed`).
Non-fatal pipeline notes.
When the deployment was created (= entered `queued`).
When the image build started (source builds only).
When the image finished building and was pushed (source builds only).
When the release was applied to the platform.
When the applied release was first observed running (runtime healthy). Absent while the rollout is still in progress — and for releases that never reached healthy.
When the deployment terminally failed or was superseded.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/deploy \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{}'{ "id": "dep_01example0000000000000000x", "serviceId": "svc_01example0000000000000000x", "version": 3, "image": "example", "buildId": "bld_01example0000000000000000x", "branch": "example", "commit": "example", "archiveRef": "example", "status": "queued", "buildStage": "example", "errors": [ { "message": "example", "at": "2026-01-01T00:00:00.000Z", "stage": "build" } ], "warnings": [ { "message": "example", "at": "2026-01-01T00:00:00.000Z", "stage": "build" } ], "createdAt": "2026-01-01T00:00:00.000Z", "buildStartedAt": "2026-01-01T00:00:00.000Z", "builtAt": "2026-01-01T00:00:00.000Z", "appliedAt": "2026-01-01T00:00:00.000Z", "healthyAt": "2026-01-01T00:00:00.000Z", "finishedAt": "2026-01-01T00:00:00.000Z"}Request a presigned upload URL for a build-context archive
Step 1 of `koo up`: returns a short-lived presigned PUT URL to upload a gzipped tarball of the working directory to, plus the `archiveRef` to pass to deploy-from-archive. The upload is namespaced to this service.
Service name within the environment.
Size of the gzipped archive in bytes (advisory; the server may cap uploads).
Presigned URL to PUT the gzipped build-context tarball to.
Opaque reference to the uploaded archive; pass it to deploy-from-archive.
HTTP method to use for the upload.
Exact Content-Type header the upload must send (signed into the URL).
Lifetime of the presigned URL in seconds.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/uploads \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{}'{ "uploadUrl": "https://example.com", "archiveRef": "example", "method": "PUT", "contentType": "example", "expiresInSeconds": 0}Deploy a previously-uploaded build-context archive
Step 2 of `koo up`: builds an image from the uploaded archive (`archiveRef` from the uploads endpoint) and ships it as a new deployment. The builder fetches + extracts the archive as the build context — no git clone.
Service name within the environment.
The archive reference returned by POST …/uploads.
Unique identifier of this deployment.
Identifier of the service this deployment belongs to.
Monotonic version number of the deployment within its service.
Resolved container image reference deployed by this release.
Identifier of the build that produced this image, when built from source.
Git branch this release was built from, when built from a git source.
Resolved commit SHA this release was built from, when built from a git source.
The uploaded build-context archive this release was built from (`koo up`).
Pipeline state, a fixed linear sequence: `queued` = accepted, waiting; `building` = the image builder is running (source builds only); `built` = image built and pushed, awaiting apply; `applied` = the release is applied to the platform — the pipeline is DONE (this is not a health verdict: the service may still be starting or unhealthy — see the service status); `failed` = the build or apply failed (see `errors`); `superseded` = a newer deployment replaced this one before it applied. Image deploys skip the build phases (queued → applied).
Live builder stage caption while `building` (e.g. "cloning", "building") — best-effort display detail; the authoritative build state is `status` + the timestamps.
Fatal pipeline failures (populated when `status` is `failed`).
Non-fatal pipeline notes.
When the deployment was created (= entered `queued`).
When the image build started (source builds only).
When the image finished building and was pushed (source builds only).
When the release was applied to the platform.
When the applied release was first observed running (runtime healthy). Absent while the rollout is still in progress — and for releases that never reached healthy.
When the deployment terminally failed or was superseded.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/deploy-from-archive \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{ "archiveRef": "example" }'{ "id": "dep_01example0000000000000000x", "serviceId": "svc_01example0000000000000000x", "version": 3, "image": "example", "buildId": "bld_01example0000000000000000x", "branch": "example", "commit": "example", "archiveRef": "example", "status": "queued", "buildStage": "example", "errors": [ { "message": "example", "at": "2026-01-01T00:00:00.000Z", "stage": "build" } ], "warnings": [ { "message": "example", "at": "2026-01-01T00:00:00.000Z", "stage": "build" } ], "createdAt": "2026-01-01T00:00:00.000Z", "buildStartedAt": "2026-01-01T00:00:00.000Z", "builtAt": "2026-01-01T00:00:00.000Z", "appliedAt": "2026-01-01T00:00:00.000Z", "healthyAt": "2026-01-01T00:00:00.000Z", "finishedAt": "2026-01-01T00:00:00.000Z"}Roll back a service to a prior deployment version
Redeploys a prior retained version — its image and the service configuration captured with it — as a NEW deployment. History stays immutable. Bounded by your plan’s deployment history depth.
Service name within the environment.
The prior deployment version to roll back to (must be within your plan’s history depth).
Unique identifier of this deployment.
Identifier of the service this deployment belongs to.
Monotonic version number of the deployment within its service.
Resolved container image reference deployed by this release.
Identifier of the build that produced this image, when built from source.
Git branch this release was built from, when built from a git source.
Resolved commit SHA this release was built from, when built from a git source.
The uploaded build-context archive this release was built from (`koo up`).
Pipeline state, a fixed linear sequence: `queued` = accepted, waiting; `building` = the image builder is running (source builds only); `built` = image built and pushed, awaiting apply; `applied` = the release is applied to the platform — the pipeline is DONE (this is not a health verdict: the service may still be starting or unhealthy — see the service status); `failed` = the build or apply failed (see `errors`); `superseded` = a newer deployment replaced this one before it applied. Image deploys skip the build phases (queued → applied).
Live builder stage caption while `building` (e.g. "cloning", "building") — best-effort display detail; the authoritative build state is `status` + the timestamps.
Fatal pipeline failures (populated when `status` is `failed`).
Non-fatal pipeline notes.
When the deployment was created (= entered `queued`).
When the image build started (source builds only).
When the image finished building and was pushed (source builds only).
When the release was applied to the platform.
When the applied release was first observed running (runtime healthy). Absent while the rollout is still in progress — and for releases that never reached healthy.
When the deployment terminally failed or was superseded.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/rollback \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{ "version": 3 }'{ "id": "dep_01example0000000000000000x", "serviceId": "svc_01example0000000000000000x", "version": 3, "image": "example", "buildId": "bld_01example0000000000000000x", "branch": "example", "commit": "example", "archiveRef": "example", "status": "queued", "buildStage": "example", "errors": [ { "message": "example", "at": "2026-01-01T00:00:00.000Z", "stage": "build" } ], "warnings": [ { "message": "example", "at": "2026-01-01T00:00:00.000Z", "stage": "build" } ], "createdAt": "2026-01-01T00:00:00.000Z", "buildStartedAt": "2026-01-01T00:00:00.000Z", "builtAt": "2026-01-01T00:00:00.000Z", "appliedAt": "2026-01-01T00:00:00.000Z", "healthyAt": "2026-01-01T00:00:00.000Z", "finishedAt": "2026-01-01T00:00:00.000Z"}Build logs for one deployment (from-source deploys)
The builder output for a from-source deployment: the persisted snapshot after the build finishes, or a live tail while it runs (`live: true` — poll again). Image deploys have no build and 404. Runtime logs are a separate endpoint (`…/services/:name/logs`).
Deployment version within the service.
Service name within the environment.
The deployment version these logs belong to.
The build output text. Empty when the build has not produced output yet.
True when the log was tail-capped (the most recent output is kept).
True when the text was proxied from the still-running builder (it may grow — poll again); false when it is the persisted terminal snapshot.
When this text was read.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/deployments/:version/build-logs \ -H "Authorization: Bearer kc_your_api_token"{ "version": 3, "logs": "example", "truncated": true, "live": true, "retrievedAt": "2026-01-01T00:00:00.000Z"}Deployment history, newest first
Opaque cursor (page.nextCursor).
Page size (1–100, default 20).
Service name within the environment.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/deployments \ -H "Authorization: Bearer kc_your_api_token"{ "data": [ { "id": "acct_01example0000000000000000x", "serviceId": "svc_01example0000000000000000x", "version": 3, "image": "example", "buildId": "bld_01example0000000000000000x", "branch": "example", "commit": "example", "archiveRef": "example", "status": "queued", "buildStage": "example", "errors": [ { "message": "example", "at": "2026-01-01T00:00:00.000Z", "stage": "build" } ], "warnings": [ { "message": "example", "at": "2026-01-01T00:00:00.000Z", "stage": "build" } ], "createdAt": "2026-01-01T00:00:00.000Z", "buildStartedAt": "2026-01-01T00:00:00.000Z", "builtAt": "2026-01-01T00:00:00.000Z", "appliedAt": "2026-01-01T00:00:00.000Z", "healthyAt": "2026-01-01T00:00:00.000Z", "finishedAt": "2026-01-01T00:00:00.000Z" } ], "page": { "nextCursor": "example", "hasMore": true }}