Playbooks

Upgrade a case

Moves a case to another version of its playbook: the playbook's current version, or the version named, an earlier one included. Values carry over by node ID, and every node's state is read against the new version: a node added is open, a node removed leaves the structure while its entries stay, a node whose input reads another field is stale, and a value its input's new schema refuses is missing again. The cascade then runs what became runnable. With wait: true it answers once every execution queued, and every one those queue, has settled or parked. Each upgrade is recorded with what moved; the version the case is already on records nothing.

An execution running is 409 PLAYBOOK_CASE_BUSY; one queued but not started settles superseded. An upgrade made with a credential the case's own work runs as is 403 PLAYBOOK_SELF_WRITE.

post/v1/projects/{project_id}/playbook-cases/{case_id}/upgrade

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/playbook-cases/{case_id}/upgrade
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

case_idstring required
Example:pbk_case_V1StGXR8Z5jdHi6B

The case ID

Request body

versioninteger

The version to move the case to; the playbook's current one when omitted

waitboolean

Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away

Example request

{
  "version": 2
}

Response

The case on its new version

idstring
project_idstring
playbook_idstring
playbook_versioninteger

The version the case was created on and is evaluated against

subjectstring
revisioninteger

The case's revision counter; every entry takes the next value

automation_status'idle' | 'running' | 'waiting' | 'paused'

paused while a pause of the case or of its project stands, else running while an execution is queued or runs its executor, else waiting while every execution in flight waits on a workflow task or orchestration run it started, else idle

pause_requested_atstring date-time nullable

When the case was paused; null while it runs

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "pbk_case_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "playbook_id": "pbk_V1StGXR8Z5jdHi6B",
  "playbook_version": 1,
  "nodes": [
    {
      "id": "regime",
      "run": {
        "id": "task_V1StGXR8Z5jdHi6B"
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.