---
title: "Create Workflow Play Code Snapshot"
method: POST
path: "/api/workflow-play-code-snapshots"
tags: ["plays"]
---

# Create Workflow Play Code Snapshot

`POST /api/workflow-play-code-snapshots`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/workflow-play-code-snapshots`
- 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`

## Request body `multipart/form-data`

- BodyWorkflowPlayCodeSnapshotCreate
  - `code_bundle` string, binary, required: Immutable workflow source zip referenced by manifest_json.
  - `expected_code_revision_id` string, nullable: Legacy compare-and-set revision paired with target_play_id.
  - `manifest_json` string, required: JSON-encoded WorkflowPlayCodeManifest. Its digests and archive paths are verified against code_bundle before publication.
  - `publication_json` string, nullable: JSON-encoded new or existing publication target. Current SDK callers use this field instead of the legacy target fields.
  - `target_play_id` string, nullable: Legacy canonical Play target when publication_json is absent.
  - `workflow_slug` string, nullable: Legacy existing-Play lookup slug when publication_json is absent.

## Response `200`

Successful Response

- WorkflowPlayCodeSnapshotResponse: Immutable workflow-code revision receipt after create, retry, or exact adoption.
  - `archive_sha256` string, required: SHA-256 of the exact immutable source archive.
  - `code_revision_id` string, required: Immutable published code revision id.
  - `content_length` integer, required: Compressed source archive size in bytes.
  - `manifest` WorkflowPlayCodeManifest, required: Known immutable code-manifest envelope plus version-specific extension fields.
    - `archive_sha256` string, nullable: SHA-256 of the immutable source archive.
    - `budget` WorkflowPlayCodeBudget: Known workflow-code budget fields with additional JSON metadata retained.
      - `maximum_branches` integer, nullable: Maximum delegated child branches per occurrence.
      - `maximum_tokens` integer, nullable: Total model-token ceiling when one is declared.
      - `timeout_seconds` integer, nullable: Maximum occurrence wall-clock lifetime in seconds.
    - `capability_ceiling` AgentCapabilityCeiling: Exact hosted SDK capabilities admitted by an immutable Agent Play revision.
      - `capabilities` string[]: Canonical hosted SDK capability ids required by the Play. The backend sorts the list and rejects duplicates or unavailable capabilities.
    - `definition_path` string, nullable: Archive-relative workflow definition module.
    - `entrypoint` string, nullable: Archive-relative executable entrypoint.
    - `execution_contract` 'verbiflow.sdk_play.v1', nullable: Hosted execution contract; required by current v3 code bundles.
    - `file_count` integer, nullable: Number of files in the archive.
    - `paths` string[], nullable: Sorted archive-relative file paths.
    - `report_path` string, nullable: Archive-relative report renderer when one is declared.
    - `schema` 'verbiflow.workflow_play_code.v1' | 'verbiflow.workflow_play_code.v2' | 'verbiflow.workflow_play_code.v3', nullable: Code-bundle schema version; absent on the oldest retained revisions.
    - `sdk_version` string, nullable: Python SDK version locked into this revision.
    - `source_hash` string, nullable: Digest of the normalized source inputs.
    - `state_policy` WorkflowPlayCodeStatePolicy: Known workflow-code state policy fields with additional JSON metadata retained.
      - `input_key` string, nullable: Dotted occurrence-input field used by partition mode.
      - `mode` 'play' | 'none' | 'trigger' | 'partition', nullable: Declared state partition strategy when recorded.
    - `synced_at` string, nullable: ISO 8601 publication time.
    - `uncompressed_size_bytes` integer, nullable: Total uncompressed archive size.
    - `workflow_name` string, nullable: Human-readable local workflow name at publication time.
    - `workflow_slug` string, nullable: Workflow slug attached during publication.
  - `object_key` string, required: Internal immutable object-store key for the archive.
  - `play_id` string, required: Canonical Play id created or revised.
  - `schedule_health` WorkflowPlayCodeScheduleHealth[]: Current health for schedules affected by the latest revision change.
    - `authority_grant_version` integer, required: Monotonic authority version currently fencing the schedule.
    - `authority_status` 'unconfigured' | 'active' | 'needs_reauthorization' | 'revoked', required: Current durable execution-authority state.
    - `changed_at` string, nullable, required: ISO 8601 time when the health classification last changed.
    - `health_status` 'healthy' | 'needs_reauthorization' | 'needs_sync' | 'paused_authority' | 'paused_deterministic' | 'paused_transient' | 'paused_unknown_effect', required: Current operator health classification.
    - `reason` string, nullable, required: Sanitized health explanation, or null when healthy.
    - `schedule_id` string, required: Canonical schedule id affected by this revision.
    - `schedule_slug` string, required: Stable human-readable schedule key.
  - `schedule_health_changes` WorkflowPlayCodeScheduleHealth[]: Schedule health projections changed by this publication.
    - `authority_grant_version` integer, required: Monotonic authority version currently fencing the schedule.
    - `authority_status` 'unconfigured' | 'active' | 'needs_reauthorization' | 'revoked', required: Current durable execution-authority state.
    - `changed_at` string, nullable, required: ISO 8601 time when the health classification last changed.
    - `health_status` 'healthy' | 'needs_reauthorization' | 'needs_sync' | 'paused_authority' | 'paused_deterministic' | 'paused_transient' | 'paused_unknown_effect', required: Current operator health classification.
    - `reason` string, nullable, required: Sanitized health explanation, or null when healthy.
    - `schedule_id` string, required: Canonical schedule id affected by this revision.
    - `schedule_slug` string, required: Stable human-readable schedule key.
  - `source_hash` string, required: Digest of the normalized source tree.
  - `synced_at` string, required: ISO 8601 revision publication time.
  - `workflow_slug` string, required: Stable workflow slug bound to the Play.

## 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)