Check a deploy's blocks against what runs
const url = 'https://example.com/v1/deployments/check';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"projectId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","agents":["example"],"blocks":[{"id":"example","version":"example"}],"replace":[{"blockId":"example","reason":"example"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/deployments/check \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "agents": [ "example" ], "blocks": [ { "id": "example", "version": "example" } ], "replace": [ { "blockId": "example", "reason": "example" } ] }'What POST /v1/deployments answers about the pack’s data blocks against what runs, with nothing written: kindgi deploy asks it before it builds the image. For each block, the newest version that runs in a project of one of agents (a project’s own version, or a segment pin inside one; every project, whoever asks) is compared with the body’s: a newer one stops the deploy unless replace names the block. Equal passes, a newer one in the files passes, and a block that runs nowhere passes. It takes the deploy’s own right: admin on projectId, else on the workspace.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
The project the deploy goes into: the check takes the deploy’s own right, admin on it. Absent: the workspace’s default project, admin on the workspace. Every project of the pack’s agents counts, whichever this is.
The pack’s agents, by id: the image index’s.
The pack’s blocks, each at its version in the files; a block named once.
object
As the deploy’s replace: a block named once.
object
Why the older version goes back: 1 to 500 characters, no control characters.
Examplegenerated
{ "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "agents": [ "example" ], "blocks": [ { "id": "example", "version": "example" } ], "replace": [ { "blockId": "example", "reason": "example" } ]}Responses
Section titled “Responses”The deploy can go: the blocks it puts back on purpose, and the ones replace names that need none.
object
The blocks replace names that a newer version runs for: the deploy puts each back, and records it.
object
The newest version that runs now.
The files’ version.
The blocks replace names that nothing newer runs for: nothing to replace.
Examplegenerated
{ "replaced": [ { "blockId": "example", "from": "example", "to": "example" } ], "notNeeded": [ "example" ]}bad-input: a body that isn’t { projectId?, agents, blocks, replace? }, a block named twice, a version that isn’t one, or a replace reason that isn’t 1 to 500 characters with no control characters (details.issues).
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" }}No admin on projectId (forbidden), or a key limited to another project; without it, no admin on the workspace.
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" }}deploy-would-put-back-older-blocks, as POST /v1/deployments answers it: each block in details.blocks (DeployCheckStop).
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" }}runs-in-unsupported: this runtime doesn’t read the agents’ pins and Latest, or the agent versions that pin each block, so it can’t check; its deploys aren’t checked either.
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" }}