---
title: "Update Play Orchestration Session"
method: POST
path: "/api/plays/{play_id}/orchestration-sessions/{session_id}"
tags: ["plays"]
---

# Update Play Orchestration Session

`POST /api/plays/{play_id}/orchestration-sessions/{session_id}`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/plays/{play_id}/orchestration-sessions/{session_id}`
- Auth: one of:
  - HTTP bearer and API key in header `x-flage-org-id`
  - HTTP bearer and API key in header `x-flage-org-slug`

## Path parameters

- `play_id` string, required
- `session_id` string, required

## Request body

- PlayOrchestrationSessionUpdate: Idempotent lifecycle update for one local authoring-orchestration session.
  - `action` 'start' | 'heartbeat' | 'complete' | 'fail', required: Lifecycle transition to apply to the authoring session.
  - `local_run_id` string, nullable: Optional local workflow run id associated with the session.

## Response `200`

Successful Response

- PlayOrchestrationSessionResponse: Current durable local-orchestration session state.
  - `local_run_id` string, nullable, required: Associated local workflow run id when provided.
  - `play_id` string, required: Canonical Play id owning the session.
  - `session_id` string, required: Stable orchestration session id.
  - `status` 'running' | 'completed' | 'failed', required: Current session lifecycle state.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract.md) - [All operations](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/llms.txt) - [OpenAPI document](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/revisions/c80e903ef8f3?raw)