--- title: "Commit Workflow Revision" method: POST path: "/workflows/revisions/commit" tags: ["Workflows"] --- # Commit Workflow Revision `POST /workflows/revisions/commit` The human and SDK route: no write scope, the caller owns the whole revision. ## Query parameters - `workflow_variant_id` string, uuid, nullable ## Request body - WorkflowRevisionCommitRequest - `workflow_revision` WorkflowRevisionCommit, required - `workflow_variant_id` string, uuid, nullable - `variant_id` string, uuid, nullable - `workflow_id` string, uuid, nullable - `artifact_id` string, uuid, nullable - `flags` WorkflowFlags — Legacy full workflow flag set. - `is_application` boolean - `is_evaluator` boolean - `is_snippet` boolean - `is_managed` boolean - `is_custom` boolean - `is_llm` boolean - `is_hook` boolean - `is_code` boolean - `is_match` boolean - `is_feedback` boolean - `is_agent` boolean - `is_skill` boolean - `is_chat` boolean - `has_url` boolean - `has_script` boolean - `has_handler` boolean - `is_static` boolean - `tags` object, nullable - `meta` object, nullable - `name` string, nullable - `description` string, nullable - `slug` string, nullable - `data` WorkflowRevisionDataInput - `uri` string, nullable - `url` string, nullable - `headers` object, nullable - `runtime` 'python' | 'typescript' | 'javascript', nullable - `script` string, nullable - `schemas` JsonSchemasInput - `parameters` object, nullable - `inputs` object, nullable - `outputs` object, nullable - `parameters` object, nullable - `message` string, nullable - `revision_id` string, uuid, nullable - `delta` WorkflowRevisionDelta — Delta operations on a workflow revision's data tree. Two forms, never mixed (contract 3): - **legacy** — ``set``: a partial data tree deep-merged onto the base revision's data (nested dicts merge; scalars and lists replace); ``remove``: dotted key paths to delete (e.g. ``parameters.agent.tools``). - **ordered** — ``operations``: the seven verbs, applied in array order, all or nothing. The engine enforces the exclusivity and every operation rule; this model only carries the shapes. Unknown keys beside ``set``/``remove``/``operations`` are refused on the ORDERED arm only, so a caller cannot believe it sent an operation modifier the server never saw. A pure-legacy envelope keeps its shipped tolerance: the server has always ignored stray keys there, and playbooks in the field send them. Neither rule reaches the tree inside ``set``, which stays free-form. - `set` object, nullable - `remove` string[], nullable - `operations` WorkflowRevisionOperation[], nullable - `operation` 'set' | 'merge' | 'remove' | 'edit_text' | 'add_item' | 'replace_item' | 'remove_item', required - `target` unknown[], required - unknown - `value` unknown - `edits` object[], nullable - `match_mode` 'auto' | 'exact', nullable - `base_revision_id` string, uuid, nullable — The revision this change was built on. Omit it to keep today's last-write-wins behavior. Send it on a legacy delta and the commit is refused with `409` when the variant's head has moved since: sending the field is how a caller asks for that check. An ordered delta requires it. ## Response `200` Successful Response - WorkflowRevisionResponse - `count` integer — `1` when a revision is returned, `0` when none matched. - `workflow_revision` WorkflowRevisionOutput - `workflow_variant_slug` string, nullable - `variant_slug` string, nullable - `workflow_slug` string, nullable - `artifact_slug` string, nullable - `workflow_variant_id` string, uuid, nullable - `variant_id` string, uuid, nullable - `workflow_id` string, uuid, nullable - `artifact_id` string, uuid, nullable - `author` string, uuid, nullable - `date` string, date-time, nullable - `message` string, nullable - `flags` WorkflowRevisionFlags - `is_application` boolean - `is_evaluator` boolean - `is_snippet` boolean - `is_managed` boolean - `is_custom` boolean - `is_llm` boolean - `is_hook` boolean - `is_code` boolean - `is_match` boolean - `is_feedback` boolean - `is_agent` boolean - `is_skill` boolean - `is_chat` boolean - `has_url` boolean - `has_script` boolean - `has_handler` boolean - `is_static` boolean - `tags` object, nullable - `meta` object, nullable - `name` string, nullable - `description` string, nullable - `created_at` string, date-time, nullable - `updated_at` string, date-time, nullable - `deleted_at` string, date-time, nullable - `created_by_id` string, uuid, nullable - `updated_by_id` string, uuid, nullable - `deleted_by_id` string, uuid, nullable - `version` string, nullable - `slug` string, nullable - `id` string, uuid, nullable - `data` WorkflowRevisionDataOutput - `uri` string, nullable - `url` string, nullable - `headers` object, nullable - `runtime` 'python' | 'typescript' | 'javascript', nullable - `script` string, nullable - `schemas` JsonSchemasOutput - `parameters` object, nullable - `inputs` object, nullable - `outputs` object, nullable - `parameters` object, nullable - `status` 'committed' | 'no_change', nullable — Commit outcome. `no_change` means the change produced the stored configuration, so no revision was created and `workflow_revision` is the current head. Absent on paths that do not run the checked commit; a reader must treat absent as `committed`. - `warnings` CommitWarning[], nullable — Structured advisories about the commit; never an error. - `code` string, required - `message` string, required - `target` unknown[], nullable - unknown - `operation_index` integer, nullable - `resolution_info` ResolutionInfo - `references_used` object[], required - `depth_reached` integer, required - `embeds_resolved` integer, required - `errors` string[] - `retrieval_info` RetrievalInfo — References actually used to retrieve a revision. For direct retrievals, `references` carries the artifact / variant / revision that was fetched. For environment-backed retrievals, it additionally carries the environment + environment_variant + environment_revision used to look the target up, and `selector` is {the key: path} map inside the environment's references map that selected the target. - `references` object - `selector` object, nullable ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/agenta-ai/apis/agenta-api.md) · [All operations](https://skmtc.net/agenta-ai/apis/agenta-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agenta-ai/agenta-api/versions/ea6421d829f1/schema)