Pin a version for a scope
const url = 'https://example.com/v1/flows/example/pinned/pin';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"version":"example","scope":{"kind":"tenant"},"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/flows/example/pinned/pin \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "version": "example", "scope": { "kind": "tenant" }, "reason": "example" }'Pins version for scope (the tenant, an org or a project), or moves the scope’s pin to it. A run that names no flow version takes the version pinned for its project (the project’s own pin, then its org’s, then the tenant’s), else the newest version the project reaches. A run that names its version isn’t affected, and a run already started keeps its version. The version must be registered and active. Pinning the version the scope already pins changes nothing and answers the change that set it. Every change is recorded, with who asked and why. Needs pin on the flow.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”FlowId — dotted namespace (acme.ingest-invoice).
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). A request whose key store can’t be read before it runs is answered 503 idempotency-store-unavailable with Retry-After: nothing ran, so retry with the same key (from 0.3.0).
Request Bodyrequired
Section titled “Request Bodyrequired”object
The version to pin (registered, active).
Responses
Section titled “Responses”Pinned.
One change of a scope’s pin, kept for good: what was pinned before, what is after, who asked and why.
object
The scope’s own pin before; null when it had none.
The scope’s own pin after; null after an unpin.
Who pinned or unpinned: a user, or a service token.
object
Example
{ "scope": { "kind": "tenant" }, "action": "pin", "requestedBy": { "kind": "user" }}Malformed request body. Or scope-invalid: a segment scope, since flows pin per project, org or tenant. Or reference-out-of-scope: a project scope whose project doesn’t reach the version (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" }}flow-not-found: no flow with that id, or the version isn’t registered or was unregistered.
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" }}Idempotency-Key was reused with a different body. Or pin-scope-spans-environments: the flow has a project in an environment order, and a tenant- or org-wide pin would act in every environment of the order at once; pin it per project instead. Or registry-read-only: this registry takes no writes (under kindgi dev, the pack’s files are the source); the message says what to do instead.
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" }}flow-gone: the flow has no active version left.
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" }}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 Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable), so nothing was changed; Retry-After (whole seconds) says when to try again with the same key.
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
GET /v1/flows/{flowId}: Fetch the latest version of a flowGET /v1/flows/{flowId}/versions: List versions of a flowGET /v1/flows/{flowId}/versions/{version}: Fetch a specific flow versionPOST /v1/flows/{flowId}/versions/{version}/unregister: Unregister a specific flow version- Error code
flow-gone - Error code
flow-not-found - Error code
idempotency-store-unavailable - Error code
pin-scope-spans-environments - Error code
reference-out-of-scope - Error code
registry-read-only - Error code
request-too-large - Error code
scope-invalid - Every error code