Record the env revision a deployment's pack service runs
const url = 'https://example.com/v1/system/tenants/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/deployments/example/pack-env';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"revision":"example","held":"pack-env-ambiguous","appliedRevision":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://example.com/v1/system/tenants/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/deployments/example/pack-env \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "revision": "example", "held": "pack-env-ambiguous", "appliedRevision": "example" }'After giving a ready pack service its values: the revision it now runs. Or, with held, that this revision’s values couldn’t be given (a required one was removed, say), or were given and its new revision didn’t start (pack-env-update-failed): the service keeps what it runs, and the tenant sees the code on the endpoint (packEnvProblem) until a later revision is given. The same code for the same revision keeps the time it was first recorded. Compare-and-set: appliedRevision is the one the service was found running, and another recorded since is pack-env-conflict. A new service’s revision goes with its endpoint instead (packEnvRevision). Takes system:pack-env.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The tenant’s id (a UUID).
The deployment’s id, as GET /v1/system/deployments lists it.
Header Parameters
Section titled “Header Parameters”Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).
Request Bodyrequired
Section titled “Request Bodyrequired”object
The revision from GET …/pack-env. Without held: the service now runs its values. With held: they weren’t given, and the service keeps what it runs.
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.
The revision the service was found running, as GET /v1/system/pack-env listed it. Absent: none was recorded. Another revision recorded since is a conflict (pack-env-conflict).
Responses
Section titled “Responses”Recorded: the deployment’s endpoint as its tenant sees 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.
Example
{ "status": "pending", "waiting": true, "packEnvProblem": { "code": "pack-env-ambiguous" }}A malformed body, or a held code not on the list (bad-input).
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:pack-env (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" }}No such tenant (tenant-not-found), or no such deployment in it (deployment-not-found).
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 tenant is closing (tenant-closing); the endpoint isn’t ready (endpoint-not-ready, with details.status); another revision was recorded since (pack-env-conflict, with details.appliedRevision).
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 request body is over the API’s limit (request-too-large; details.maxBytes says how much).
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" }}Server error (unmapped domain code or framework crash).
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 server doesn’t give a pack service its declared env: its pack services take theirs from how they’re run (pack-env-unsupported).
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 operator’s access record can’t be written, so nothing was done (access-record-unavailable).
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" }}See also
GET /v1/system/tenants/{tenantId}/deployments/{deploymentId}/pack-env: Read the env a deployment's pack service is to be givenGET /v1/system/tenants: List tenantsPOST /v1/system/tenants: Create a tenantGET /v1/system/tenants/{tenantId}: Read a tenant- Error code
access-record-unavailable - Error code
bad-input - Error code
deployment-not-found - Error code
endpoint-not-ready - Error code
pack-env-conflict - Error code
pack-env-unsupported - Error code
request-too-large - Error code
system-principal-required - Error code
system-scope-missing - Error code
tenant-closing - Error code
tenant-not-found - Every error code