Scheduled promotion versions: timeline and lifecycle actions (release, unschedule, cancel, reconfirm).
List a promotion's version timeline
Returns all versions ordered by effective_from. Active and scheduled versions are returned by default; pass include=all to include drafts and archived versions.
path Parameters
idEntity UUID
Entity UUID
query Parameters
includeSet to 'all' to include draft and archived versions
Set to 'all' to include draft and archived versions
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List a promotion's version timeline › Responses
OK
Cancel a scheduled or draft promotion version
Archives the version and stamps cancelled_at so it never goes active. Cancellation is only available before the version has been applied. The version is addressed by its number - the same key the version reads return.
path Parameters
idEntity UUID
Entity UUID
versionVersion number
Version number
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Cancel a scheduled or draft promotion version › Responses
OK
Reconfirm a stale promotion version
Clears warnings on a scheduled version after the operator has acknowledged that an upstream change does not invalidate the scheduled payload. Use PUT/PATCH to amend the payload itself. The version is addressed by its number - the same key the version reads return.
path Parameters
idEntity UUID
Entity UUID
versionVersion number
Version number
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Reconfirm a stale promotion version › Responses
OK
Release a MANUAL scheduled promotion version now
Fires a manual-release scheduled version immediately: the row is retargeted onto the automatic flip path (effective now), so the next ticker pass promotes it through the full pre-flip pipeline (timeline rebase, renumbering, window chaining, post-flip cascades). The row flips within one tick interval. The version is addressed by its number - the same key the version reads return.
path Parameters
idEntity UUID
Entity UUID
versionVersion number
Version number
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Release a MANUAL scheduled promotion version now › Responses
OK
Unschedule a pending promotion version
Reverts a scheduled version back to draft, clearing effective_from so it leaves the timeline. Only callable while the version has not yet been applied. The version is addressed by its number - the same key the version reads return.
path Parameters
idEntity UUID
Entity UUID
versionVersion number
Version number
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Unschedule a pending promotion version › Responses
OK