# Fetch a signed deployment record

GET

/v1/deployments/{deploymentId}

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

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/v0.1.8/reference/api.md#bearerauth)**

## Parameters

### Path Parameters

**deploymentId**

required

string

\>= 1 characters

Deployment id assigned by the ledger at register time.

## Responses

### 200

Deployment record.

application/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

```json
{
  "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.

application/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

##### Examplegenerated

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

### 404

No deployment with that id under this tenant.

application/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

##### Examplegenerated

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

## See also

- [`POST /v1/deployments/{deploymentId}/secrets`: Sync secrets against a deployment](https://docs.kindgi.com/v0.1.8/reference/api/operations/deploymentssyncsecrets.md)
- [Organize work by org and project](https://docs.kindgi.com/v0.1.8/guides/projects/organize-by-org-and-project.md)
- [Every error code](https://docs.kindgi.com/v0.1.8/reference/errors.md)