Fetch a signed deployment record

GET

/v1/deployments/{deploymentId}

curl --request GET \
  --url https://example.com/v1/deployments/example \
  --header 'Authorization: Bearer <token>'

• Same-origin — path relative to the deployment root.

Authorizations

• bearerAuth

Parameters

Path Parameters

deploymentId

required

string

>= 1 characters

Deployment id assigned by the ledger at register time.

Responses

200

Deployment record.

Media typeapplication/json

object

deploymentId

required

string

>= 1 characters

tenantId

required

string format: uuid

imageRef

required

Full digest-pinned OCI reference: <host>/<repo>@sha256:<hex>.

string

imageDigest

required

Idempotency key. Extracted from imageRef after the @.

string

/^sha256:[0-9a-f]{64}$/

artifactVersion

required

Issuer-supplied YYYYMMDD.N — matches what was signed.

string

/^\d{8}\.\d+$/

indexHash

required

Sha256 of the canonicalised /app/index.json inside the image.

string

/^sha256:[0-9a-f]{64}$/

signerKeyId

required

string

>= 1 characters

signerPublicKey

required

Base64 of the raw Ed25519 public key bytes (32 bytes → 44 chars).

string

signature

required

Base64 of the raw Ed25519 signature (64 bytes → 88 chars).

string

publishedAt

required

Issuer-supplied timestamp inside the signed envelope.

string format: date-time

activatedAt

required

Server-side ledger timestamp — when the register call succeeded.

string format: date-time

projectId

The project the deploy named, which its primitives were registered into. Absent for a tenant-wide deploy (the tenant’s Default project).

string format: uuid

endpoint

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

status

required

string

Allowed values: pending ready cleared

since

required

When the status last changed.

string format: date-time

problem

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

code

required

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).

string

since

required

When it was recorded.

string format: date-time

primitives

required

object

tools

required

integer

guardrails

required

integer

agents

required

integer

flows

required

integer

contents

required

object

tools

required

Array<object>

object

id

required

string

version

Absent for guardrails, which have no version.

string

guardrails

required

Array<object>

object

id

required

string

version

Absent for guardrails, which have no version.

string

agents

required

Array<object>

object

id

required

string

version

required

The version the agent is registered as.

string

authoredVersion

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).

string

reason

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).

string

Allowed values: pins-changed unpinned version-taken

newVersion

true: this deploy registered version; false: an earlier deploy did.

boolean

pinChanges

For pins-changed: the pins that differ from authoredVersion’s.

Array<object>

One pin that differs between two versions of an agent or a flow.

object

kind

required

string

Allowed values: tool prompt setting agent

id

required

string

from

The earlier version’s pin; absent when it had none.

string

to

The later version’s pin; absent when it has none.

string

flows

required

Array<object>

object

id

required

string

version

required

The version the agent is registered as.

string

authoredVersion

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).

string

reason

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).

string

Allowed values: pins-changed unpinned version-taken

newVersion

true: this deploy registered version; false: an earlier deploy did.

boolean

pinChanges

For pins-changed: the pins that differ from authoredVersion’s.

Array<object>

One pin that differs between two versions of an agent or a flow.

object

kind

required

string

Allowed values: tool prompt setting agent

id

required

string

from

The earlier version’s pin; absent when it had none.

string

to

The later version’s pin; absent when it has none.

string

Example

{
  "endpoint": {
    "status": "pending"
  },
  "contents": {
    "agents": [
      {
        "reason": "pins-changed",
        "pinChanges": [
          {
            "kind": "tool"
          }
        ]
      }
    ],
    "flows": [
      {
        "reason": "pins-changed",
        "pinChanges": [
          {
            "kind": "tool"
          }
        ]
      }
    ]
  }
}

401

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

No deployment with that id under this tenant.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also

• POST /v1/deployments/{deploymentId}/secrets: Sync secrets against a deployment
• Organize work by org and project
• Every error code