Flows

Replace a flow with a merged graph, keeping the replaced version in history.

This is the deliberate half of the conflict dialog, and it is still guarded. The caller sends the token it reviewed, not the stale one it was refused on and not nothing at all: writing unconditionally here would silently discard a fourth writer who landed while the dialog was open, reopening the lost update the whole feature exists to close. So the meaning is "replace the version I just looked at", and a flow that moved again is refused with a fresh 409.

The archived entry is attributed to whoever last wrote the flow rather than to the caller, because it is their work being replaced -- attributing it here would put the caller's name on someone else's version and defeat the point of keeping it.

The write right is claimed before anything is archived. Archiving first and letting the refusal roll it back does not work: version entries are written in a begin_nested() savepoint that survives the outer rollback, so a refused overwrite left an orphan version in someone's history. Claiming first means a stale caller is turned away before a single row is written.

post/api/v1/flows/{flow_id}/overwrite

Request

  • The document declares no server URL.
  • Auth
    • OAuth 2
      Password
      Token URL: api/v1/login
    • or API key in query parameter x-api-key
    • or API key in header x-api-key

Path parameters

flow_idstring uuid required

Headers

If-Matchstring nullable

Request body

dataobject required

Response

Successful Response

a2a_card_overridesobject nullable

User overrides for the generated A2A agent card (skill description, examples, tags)

a2a_enabledboolean nullable

Can be exposed as an A2A agent (only meaningful when flow_type=agent)

access_type'PRIVATE' | 'PUBLIC'
action_descriptionstring nullable

The description of the action associated with the flow

action_namestring nullable

The name of the action associated with the flow

dataobject nullable
descriptionstring nullable
endpoint_namestring nullable
flow_type'workflow' | 'agent'
folder_idstring uuid nullable required
gradientstring nullable
iconstring nullable
icon_bg_colorstring nullable
idstring uuid required
is_componentboolean nullable
lockedboolean nullable
mcp_enabledboolean nullable

Can be exposed in the MCP server

namestring required
name_keystring nullable

Stable i18n key derived from the original English name

tagsstring[] nullable

The tags of the flow

updated_atstring date-time nullable
user_idstring uuid nullable required
version_tokenstring uuid nullable

Token identifying the version this response carries

webhookboolean nullable

Can be used on the webhook endpoint

workspace_idstring uuid nullable

Changes