Check a promotion without making it

POST

/v1/deployments/{deploymentId}/promotions/check

curl --request POST \
  --url https://example.com/v1/deployments/example/promotions/check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "toProjectId": "example" }'

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

Runs every check a promotion makes and writes nothing: what would move, the next environment, and each value with a problem in the target (where a promotion refuses with promotion-values-not-ready). Refused as the promotion is for every other check. Needs read on the deployment’s project and admin on the target.

Authorizations

• bearerAuth

Parameters

Path Parameters

deploymentId

required

string

>= 1 characters

The deployment to promote: one serving an environment of an order.

Request Body^required

Media typeapplication/json

object

toProjectId

required

The next environment of the deployment’s order.

string

>= 1 characters

Example^generated

{
  "toProjectId": "example"
}

Responses

200

What a promotion would move, and the values not ready in the target.

Media typeapplication/json

object

moves

required

object

packId

string

imageDigest

required

string

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

agents

required

Array<object>

object

id

required

string

version

string

carried

Carried with the build: an edit of a version it ships. Absent for one it ships.

boolean

flows

required

Array<object>

object

id

required

string

version

string

carried

Carried with the build: an edit of a version it ships. Absent for one it ships.

boolean

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

values

required

Each value with a problem in the target; empty when every one is ready.

Array<object>

object

name

required

The secret’s or env value’s name; for a model key, the key’s secret name, or any provider when none is registered.

string

kind

required

secret, env, model-key or pack-env; a later runtime may add kinds, so treat an unknown one as a value not yet named.

string

neededBy

required

object

type

required

tool, agent, provider or pack; a later runtime may add kinds, so treat an unknown one as a need not yet named.

string

id

required

string

version

string

foundAt

Where a run finds it, when it is set: the project, else its org, else the tenant.

string

Allowed values: project org tenant

problem

Why it isn’t ready; absent when it is. One of a fixed list; a later runtime may add problems, so treat an unknown one as a reason not yet named. missing: set nowhere a run looks. secret-not-yet: a pack env name set only as a secret, which isn’t given into a pack service’s environment yet. ambiguous: a pack env name set both as a secret and as a plain value. revoked: a tool’s secret revoked where it’s recorded, or a model key revoked where a run looks first (a run refuses rather than read a wider one). no-provider: an agent that runs on any provider (it names none, or names one that isn’t registered), with no provider registered in the tenant, so a run has none to call.

string

nextEnvironment

required

object

projectId

required

string

position

required

Its place in the order, from 0 (the first, which takes builds).

integer

>= 1

envName

The env this runtime serves, which a run in the target reads its values under: a value is set there (--env=<envName> with --scope=project:<id>). Absent when the runtime names none, and each value is then listed unread.

string

leftBehind

Edits of the build’s agents and flows that would stay behind; absent when none.

Array<object>

object

kind

required

agent or flow; a later runtime may add kinds, so treat an unknown one as an item not yet named.

string

id

required

string

version

required

string

from

required

The version its chain of edits starts from.

string

Example

{
  "moves": {
    "agents": [
      {
        "carried": true
      }
    ],
    "flows": [
      {
        "carried": true
      }
    ]
  },
  "values": [
    {
      "foundAt": "project"
    }
  ]
}

400

Malformed body (bad-input). Or signature-invalid: the deployment’s signature doesn’t verify over the fields it keeps.

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"
  }
}

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"
  }
}

403

No admin on the target project. Or key-project-mismatch: the API key or session is limited to a project, which a promotion’s check is refused as the promotion is. Or signer-not-trusted: the key that signed the build is no longer trusted.

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

deployment-not-found: no deployment with that id in this tenant, or one in a project you don’t read.

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"
  }
}

409

promotion-not-next-environment, deployment-superseded, or a suspension of the source or the target, as on the promotion.

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"
  }
}

413

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

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"
  }
}

500

Server error (unmapped domain code or framework crash).

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

• GET /v1/deployments/{deploymentId}: Fetch a signed deployment record
• GET /v1/deployments/{deploymentId}/pack-env: Show where each name a deployment's pack declares is set
• POST /v1/deployments/{deploymentId}/secrets: Sync secrets against a deployment
• GET /v1/deployments/{deploymentId}/values: List the values a deployment needs in a project
• Error code bad-input
• Error code deployment-not-found
• Error code deployment-superseded
• Error code key-project-mismatch
• Error code promotion-not-next-environment
• Error code request-too-large
• Error code signature-invalid
• Error code signer-not-trusted
• Every error code