List deployments that need a pack service, have a ready one, or should lose theirs
const url = 'https://example.com/v1/system/deployments?endpoint=missing&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/system/deployments?endpoint=missing&limit=25' \ --header 'Authorization: Bearer <token>'Across tenants, oldest activatedAt first. endpoint=missing: deployments that need a pack service. Each serves something a call can still ask for, and no newer deployment into its project serves it: a tool, agent or flow version that’s registered or held (a flow or agent version a run can reach pins it, or an unfinished run uses it), a tool deployed without a version, or a pack check a registered guardrail runs in its project (from Kindgi 0.4.0; before, each was the newest into its project with routes for some tool version or pack check, and one whose endpoint an earlier runtime made or last set still needs that too). Each has no endpoint or a cleared one, and nothing about it is closing or suspended. endpoint=ready: deployments whose endpoint is ready and whose pack service stays (no retire reason applies). Both lists say whether each service is warm: keep an instance running. endpoint=retire: deployments with an endpoint whose pack service should go, each with its reason. Name each service packServiceName(tenantId, deploymentId) (@kindgi/api). Takes system:deployments. Each entry carries the tenant’s id and nothing else of it.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”missing: deployments that need a pack service. ready: deployments whose pack service is ready and stays. retire: deployments whose pack service should go.
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.
1..100. Default 25.
Responses
Section titled “Responses”One page of deployments.
object
A deployment as whatever runs its pack service needs it: ids and the image, nothing of the tenant beyond its id. Name the service packServiceName(tenantId, deploymentId) (@kindgi/api). In the missing and ready lists, warm says whether to keep an instance of its service running. In the missing list, problem is the last problem recorded for it (PUT …/endpoint/problem), absent until one is; its since is when that code was first recorded, as recording the same code again keeps it, so a pass can space its tries by it. In the retire list, reason says why the service should go.
object
The pack it deploys (the image index’s packId).
The deployment’s project, as a call routes in it: the one it named, else the tenant’s default. Absent only when the tenant has no default project.
Digest-pinned, as registered: the pack service is created from exactly this.
In the missing and ready lists. true: keep an instance of the deployment’s pack service running, as calls route to it for something always on in its project: a tool version reached from a version a pin holds (an agent’s, a flow’s or a tool’s) or from the Latest of each agent no pin covers there, or a pack check a registered guardrail runs there. false: its service can scale to zero. Absent from a runtime that doesn’t say: not warm.
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-name-too-long (a name set as a secret is too long for the secret it’s kept in, which is named after the pack service; shorten it in the pack), 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.
In the retire list only. superseded: nothing a call can still ask for needs it: for each tool version, pack check, agent and flow version it serves, a newer deployment into its project serves it too, or it’s unregistered and not held (a check: no registered guardrail runs it in its project); and each tool it deployed without a version, a newer deployment into its project deploys without one too (from Kindgi 0.4.0; before, it meant newer deployments into its project shipped every tool version and check it does and deployed each tool it deployed without a version the same way, and was for good). One whose endpoint an earlier runtime made or last set is superseded as well, for good, once newer deployments into its project ship every tool version and check it does and deploy each tool it deployed without a version the same way. Otherwise it’s needed again once something it serves that no newer deployment into its project serves is wanted again: a tool, agent or flow version registered or held again, or a check a newly registered guardrail runs in its project. A tool call a step made on it still goes back to it when the step runs again, and fails closed (pack-endpoint-cleared) once its endpoint is cleared. tenant-closing, tenant-suspended: every deployment of the tenant, routed or not. project-suspended, pack-suspended: every deployment of the project, or this one.
Opaque cursor for the next page. Absent when hasMore: false.
Example
{ "data": [ { "reason": "superseded" } ]}endpoint missing or not one of missing, ready and retire; a limit out of range; a cursor refused.
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" }}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" }}A tenant’s key or session (system-principal-required), or a system key without system:deployments (system-scope-missing).
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" }}The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.
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" }}