---
title: "Publish Agent Play Revision"
method: POST
path: "/api/plays/revisions/agent"
tags: ["plays"]
---

# Publish Agent Play Revision

`POST /api/plays/revisions/agent`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/plays/revisions/agent`
- 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

- AgentPlayRevisionRequest: Publish one immutable Agent Play revision under an idempotent identity or CAS guard.
  - `agent` AgentExecutorRequest, required: Complete immutable execution contract for an Agent Play revision.
    - `budget` AgentBudget: Runtime ceilings frozen into an immutable Agent Play revision.
      - `maximum_branches` integer: Maximum delegated child branches admitted during one occurrence.
      - `maximum_tokens` integer, nullable: Total durable model-token ceiling, or null for no token ceiling.
      - `timeout_seconds` integer: Maximum wall-clock lifetime of one occurrence, 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.
    - `input_schema` object: Draft 2020-12 JSON Schema for occurrence input. An empty object accepts any JSON object; schema-defined properties remain revision owned.
    - `output_schema` object: Draft 2020-12 JSON Schema for the final result. An empty object leaves the result unconstrained; schema-defined properties remain revision owned.
    - `state_policy` union: Durable continuation scope for scheduled and event occurrences.
      - AgentPlayStatePolicy: One durable state stream shared by every occurrence of the Play.
        - `mode` 'play': Share one durable state stream across all occurrences.
      - AgentIsolatedStatePolicy: No durable state is carried between Play occurrences.
        - `mode` 'none', required: Give every occurrence isolated state.
      - AgentTriggerStatePolicy: One durable state stream for each trigger identity.
        - `mode` 'trigger', required: Partition durable state by trigger identity.
      - AgentPartitionStatePolicy: One durable state stream for each value at an occurrence-input path.
        - `input_key` string, required: Dotted occurrence-input field path whose value identifies the state partition, for example account.domain.
        - `mode` 'partition', required: Partition durable state by an input value.
    - `task` string, required: Complete repeatable business outcome for each Play occurrence.
  - `idempotency_key` string, required: Stable retry identity reused only for this exact publication.
  - `play` union, required: New identity or exact existing-revision target.
    - NewAgentPlay: Catalog identity and presentation fields for a new Agent Play.
      - `description` string, nullable: Optional human-facing explanation of the Play.
      - `kind` 'new', required: Create a new canonical Play identity.
      - `slug` string, required: Stable workspace slug for the new Play.
      - `title` string, required: Human-facing title for the new Play.
      - `visibility` 'visible' | 'local_only': visible publishes the Play in the workspace catalog; local_only keeps it available only through explicit identity.
    - ExistingAgentPlay: Compare-and-set identity for publishing a new revision of an existing Agent Play.
      - `expected_revision_id` string, required: Exact current revision required by the compare-and-set publication.
      - `kind` 'existing', required: Revise an existing canonical Play.
      - `play_id` string, required: Canonical Play id to revise.

## Response `200`

Successful Response

- AgentPlayRevisionResponse: Immutable Agent Play publication receipt.
  - `digest` string, required: SHA-256 of the canonical Agent Play revision contract.
  - `play_id` string, required: Canonical Play id created or revised.
  - `revision_id` string, required: Immutable Agent Play revision now stored for 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)