List signed deployments
const url = 'https://example.com/v1/deployments?limit=25';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/v1/deployments?limit=25' \ --header 'Authorization: Bearer <token>'Cursor-paginated. Sort order: activatedAt descending (binding-defined tiebreak on deploymentId). Only the deployments in projects the caller reads are listed (a deployment naming no project is the Default project’s), so a page can hold fewer than limit with hasMore true: page by nextCursor, not by count. Optional ?imageRefPrefix= narrows to deployments whose imageRef starts with the prefix; ?signerKeyId= narrows to a specific signing key (useful for revocation audits); ?projectId= to one environment (the Default also finds those naming no project); ?packId= to one pack.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”1..100. Default 25.
Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.
Prefix match on Deployment.imageRef.
Filter to deployments signed by this key id.
Filter to one environment’s deployments. The tenant’s Default project also finds those that name no project. Needs read on that project.
Filter to one pack’s deployments (packId).
Responses
Section titled “Responses”Page of deployments.
object
object
Full digest-pinned OCI reference: <host>/<repo>@sha256:<hex>.
Idempotency key. Extracted from imageRef after the @.
Issuer-supplied YYYYMMDD.N — matches what was signed.
Sha256 of the canonicalised /app/index.json inside the image.
Base64 of the raw Ed25519 public key bytes (32 bytes → 44 chars).
Base64 of the raw Ed25519 signature (64 bytes → 88 chars).
Issuer-supplied timestamp inside the signed envelope.
Server-side ledger timestamp — when the register call succeeded.
The project the deploy named, which its primitives were registered into. Absent for a tenant-wide deploy (the tenant’s Default project).
The names the pack service reads from its process environment, as the image’s index.json declares them (env), each list in name order. Names only, never a value. On a deployment: absent when it declares none, and from older servers.
object
Names the pack service needs, set and non-empty, to be ready.
Names the pack reads when present.
When this deployment was made by promoting another into the next environment of its order: the deployment it was promoted from. Absent for one deployed directly.
The pack’s id, from the image’s index. Absent from a runtime that doesn’t keep it.
Its pack service’s status, when the server routes each pack call to the deployment that shipped the tool (KINDGI_PACK_ROUTING=per-deployment). Absent otherwise. pending: no pack service yet, and calls to its tools fail (pack-endpoint-pending) rather than go to another deployment. ready: calls go to its own pack service. cleared: its pack service was taken down, and calls fail (pack-endpoint-cleared); it carries waiting or retired to say whether it comes back. Carries no URL and no token.
object
When the status last changed.
While the deployment waits for a pack service (pending, or cleared and waiting): the last reason recorded while it waited. A ready endpoint has none, nor a retired one. A fixed code, never free text.
object
One of a fixed list; a later runtime may add codes, so treat an unknown one as a reason not yet named. The server refused the endpoint it was given: endpoint-url-invalid (not https, or with user info or a path), endpoint-host-not-allowed (the host isn’t on the operator’s allowlist), endpoint-name-mismatch (the host doesn’t name this deployment’s service), endpoint-unreachable (the pack service didn’t answer), endpoint-info-mismatch (it answered as another pack or version), image-not-allowed (the image is outside the tenant’s repository). The pack service couldn’t be created: tenant-not-provisioned (the tenant has nowhere to run pack services yet), capacity-unavailable (no room for another pack service just now), service-start-failed (the image was deployed but didn’t start). It can’t be given its declared environment (GET /v1/deployments/{deploymentId}/pack-env names the names): pack-env-ambiguous, pack-env-secret-not-yet, pack-env-missing, pack-env-secret-unreadable (a name’s secret can’t be read for a reason the platform fixes, not the owner; it’s tried again). It can’t be given its secrets: pack-env-secrets-unaudited (the runtime has nowhere to audit a secret it gives out; the platform fixes it, and it’s tried again), pack-env-secret-too-large (a secret’s value is over 32768 bytes, the most a pack service can be given), pack-env-secret-capacity (a name is set only as a secret, and there’s no room just now for a pack service that can be given one, apart from other projects’; it’s tried again).
When it was recorded.
cleared only: a pack service is wanted for it again, as once a suspension that took its service down is lifted, and it lists as needing one; problem says why it isn’t back yet. A cleared endpoint carries this or retired, never both. Absent from older servers, which send neither.
cleared only: why no pack service is wanted for it now. superseded is for good: newer deployments ship every tool version and check it does, so no new call reaches it; a tool call a step made on it still goes back to it when the step runs again, and fails closed (pack-endpoint-cleared). tenant-closing, tenant-suspended, project-suspended and pack-suspended last until the tenant, project or pack is restored. A later runtime may add reasons, so treat an unknown one as a reason not yet named. A cleared endpoint carries this or waiting, never both. Absent from older servers, which send neither.
ready only: the pack service runs on the values it was last given, because the newest can’t be given to it (a required one was removed, say, or a secret can’t be given), or didn’t start (pack-env-update-failed). Gone once they can, or do. For a name that can’t be given, GET /v1/deployments/{deploymentId}/pack-env names it. Absent from older servers.
object
Why a ready pack service runs on the values it was last given: a PackEnvProblemCode, so the newest can’t be given to it; pack-env-update-failed: they were given, and its new revision with them didn’t start, so the last ready one serves. That revision is tried again for an hour after it’s first recorded; setting the values again is a new revision, tried again too. The orchestrator couldn’t give it its secrets: pack-env-secrets-unaudited (the runtime has nowhere to audit a secret it gives out, so it gives none; the platform fixes it), pack-env-secret-too-large (a secret’s value is over 32768 bytes, the most a pack service can be given), pack-env-secret-redeploy (a name is now set only as a secret, and this pack service was made where no secret can be given to it; a new deployment’s can be, from a new build of the pack). A service held as pack-env-secret-unreadable or pack-env-secrets-unaudited is listed by GET /v1/system/pack-env every time, with its held, as the revision doesn’t move when the platform fixes it. A later runtime may add codes, so treat an unknown one as a reason not yet named.
When it was recorded.
object
object
object
Absent for guardrails, which have no version.
object
Absent for guardrails, which have no version.
object
The version the agent is registered as.
The version the agent’s or flow’s definition names, present when it differs from version: that version was registered already with other pins or content, and versions never change, so the deploy registered the next free version in its line (or an earlier deploy did).
Why version differs from authoredVersion: pins-changed (a tool or agent it uses has a new version), unpinned (authoredVersion was published before pins existed), version-taken (authoredVersion is registered with other content).
true: this deploy registered version; false: an earlier deploy did.
For pins-changed: the pins that differ from authoredVersion’s.
One pin that differs between two versions of an agent or a flow.
object
The earlier version’s pin; absent when it had none.
The later version’s pin; absent when it has none.
object
The version the agent is registered as.
The version the agent’s or flow’s definition names, present when it differs from version: that version was registered already with other pins or content, and versions never change, so the deploy registered the next free version in its line (or an earlier deploy did).
Why version differs from authoredVersion: pins-changed (a tool or agent it uses has a new version), unpinned (authoredVersion was published before pins existed), version-taken (authoredVersion is registered with other content).
true: this deploy registered version; false: an earlier deploy did.
For pins-changed: the pins that differ from authoredVersion’s.
One pin that differs between two versions of an agent or a flow.
object
The earlier version’s pin; absent when it had none.
The later version’s pin; absent when it has none.
The project on every page of a list asked for with ?projectId=, an empty one too: it holds only that environment’s deployments. Absent from a runtime before Kindgi 0.1.9, which ignores projectId and lists them all.
The pack on every page of a list asked for with ?packId=, an empty one too: it holds only that pack’s deployments. Absent from a runtime before Kindgi 0.1.9, which ignores packId and lists them all.
Example
{ "data": [ { "endpoint": { "status": "pending", "waiting": true, "packEnvProblem": { "code": "pack-env-ambiguous" } }, "contents": { "agents": [ { "reason": "pins-changed", "pinChanges": [ { "kind": "tool" } ] } ], "flows": [ { "reason": "pins-changed", "pinChanges": [ { "kind": "tool" } ] } ] } } ]}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}No read on the tenant, or a projectId naming a project the caller doesn’t read, or one that isn’t there (the tenant admin too, so it tells no one what exists).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}List failed inside the caller-plugged binding.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}