Record where a deployment's pack service runs
const url = 'https://example.com/v1/system/tenants/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/deployments/example/endpoint';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"url":"example","auth":"google-id-token","token":"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/endpoint \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "url": "example", "auth": "google-id-token", "token": "example" }'Records the endpoint, once every check passes: the URL is https://<host> (endpoint-url-invalid); its host is on the operator’s allowlist (endpoint-host-not-allowed); its host names the deployment’s own service, packServiceName(tenantId, deploymentId) then - or . (endpoint-name-mismatch); the image is in the tenant’s repository (image-not-allowed); the pack service answers /v1/info, with the kindgi-tenant-id header, as this deployment (endpoint-unreachable, endpoint-info-mismatch, with the names of the fields that differed). A refusal is also recorded as the endpoint’s problem, which the tenant sees as a code. The deployment’s endpoint is then ready. Refused for a closing or suspended tenant, project or pack, so a sweep can’t recreate a service another one retired. Takes system:deployments. The same body twice records it once.
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
https://<host>: no user info, path, query or fragment. Its host must be on the operator’s allowlist (KINDGI_PACK_ENDPOINT_HOSTS) and begin with the deployment’s own service name (packServiceName), then - or ..
How the server calls it: google-id-token adds an ID token for the URL (Cloud Run’s invoker check) to the pack token; token sends the pack token only.
The pack service’s token (KINDGI_PACK_SERVICE_TOKEN), printable ASCII without spaces. Stored wrapped; never returned, logged or recorded.
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). Carries no URL and no token.
object
When the status last changed.
With pending only: the last reason the deployment has no pack service yet, gone once the status changes. 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).
When it was recorded.
Example
{ "status": "pending"}A malformed body (bad-input), or a URL that isn’t https://<host> (endpoint-url-invalid).
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" }}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 or suspended (tenant-closing, tenant-suspended), or the project or pack is (project-suspended, pack-suspended); the image is outside the tenant’s repository (image-not-allowed).
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" }}The host isn’t allowed (endpoint-host-not-allowed) or doesn’t name the deployment’s service (endpoint-name-mismatch, with details.expected); the pack service didn’t answer (endpoint-unreachable) or answered as another pack or version (endpoint-info-mismatch, with details.differs).
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 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
DELETE /v1/system/tenants/{tenantId}/deployments/{deploymentId}/endpoint: Clear a deployment's endpointGET /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-host-not-allowed - Error code
endpoint-info-mismatch - Error code
endpoint-name-mismatch - Error code
endpoint-unreachable - Error code
endpoint-url-invalid - Error code
image-not-allowed - Error code
pack-suspended - Error code
project-suspended - Error code
request-too-large - Error code
system-principal-required - Error code
system-scope-missing - Error code
tenant-closing - Error code
tenant-not-found - Error code
tenant-suspended - Every error code