Skip to main content
POST
Delete procedure versions
A hard delete cannot be undone. With force, workflows that pin a deleted version fail validation and dispatch until they are repointed. List them first with List what references a procedure.
Hard-deletes up to 200 versions (items, each {procedureId, version} once), as Console’s delete and bulk-delete actions do. Each version is decided on its own, in request order, and the request answers 200 with one result per item:
  • deleted: true.
  • reason: "not_found": missing, not one you manage, or already removed earlier in the same request as an orphaned sibling.
  • reason: "refused": the delete rule refused it. Built-in procedures are never deleted. Without force, only an unused provisional draft is deleted; deprecate an active version instead.
Deleting a family’s last active version also removes its deprecated and archived siblings, so the whole lineage goes with it. In-flight drafts are left alone.

Who may delete

You need procedures:manage at each version’s home org unit. A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. Each deletion is audited (procedure_hard_deleted) with that actor and, for an app or platform key, who granted it.

Idempotency

With an Idempotency-Key, a same-key repeat within 24 hours returns the recorded result only while you still hold procedures:manage at the home of every version it names (for a deleted version, at its surviving siblings’ homes, else the platform scope); otherwise 409 idempotency_result_unavailable. Nothing is deleted twice for one key.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Body

application/json
items
object[]
required

The versions to delete, 1-200, each once.

Required array length: 1 - 200 elements
force
boolean

Delete versions that are active, approved or used. Workflows that pin them fail until repointed. Built-in procedures are never deleted.

Response

Success

data
object
required

Each requested version's outcome, in request order. not_found: missing, or not one the caller may manage (also a version an earlier deletion in the same request removed as an orphaned sibling). refused: the delete rule refused it (built-in, or without force anything but an unused provisional draft).

meta
object
required