Save the draft of a flow, also an invalid one (tenant:flows:write|admin; scoped flows the owning module's manage)
PUT /api/flows/v1/flows/{id}/draft
Module: Flows · operationId: saveFlowDraft · Tag: Flows · Auth: access token (Authorization: Bearer <accessToken>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes |
Request body
application/json (required)
version(integer, required): The draft's version you editedyaml(string, required): The draft definition (YAML)
Example:
{
"version": 5,
"yaml": "schemaVersion: 1\nkey: kritische-tickets-zusammenfassen\nname: Kritische Tickets zusammenfassen\ntriggers:\n - { id: neues_ticket, kind: event, event: desk.item.created, filter: \"trigger.data.priority in ['hoch', 'kritisch']\" }\nnodes:\n ticket:\n kind: action\n name: Ticket lesen\n action: desk.item.get\n params: { ref: \"{{ trigger.data.itemId }}\" }\nedges:\n - neues_ticket -\u003e ticket\n"
}
Responses
- 200 The saved draft with its findings (
application/json) - 400 Invalid input (
invalid);fieldnames the first invalid field,details.fieldsevery one. (application/json) - 401 Missing, invalid or expired token (no body).
- 403 The token lacks the permission or has no active tenant (
forbidden). Also:person_required(a service-account key on personal flows or the task inbox),live_test_forbidden,forbidden_grant,starter_excluded. (application/json) - 404 The record does not exist in the token's tenant – or it belongs to a scope the caller may not view (a scoped flow stays hidden). (
application/json) - 409 The state does not allow it: version_conflict (reload), no_changes, archived, key_taken, flow_disabled, flow_tripped, task_closed, run_finished. (
application/json) - 503 A dependency is not available:
scope_unavailable(the module that owns a flow's scope did not answer who may see and manage it – nothing of a scoped flow is shown or changed),identity_unavailable(HR),ai_unavailable,ai_failed. (application/json)
Fields of the 200 answer:
diagnostics(array of Diagnostic): Findings of the validator for the draftcode(string, required): Stable code, e.g.unknown_port,invalid_assignee,mail_option_not_allowed(a mail node setsmandatoryormailChannelin a personal or scoped flow)message(string, required): Human-readable explanationseverity(string, required): Errors block publishing (one oferror,warning)col(integer): Column in the YAML (1-based)line(integer): Line in the YAML (1-based)nodeId(string): The node the finding is aboutparams(object):mail_option_not_allowed:option(mandatoryormailChannel)path(string): Dotted path in the definition
updatedAt(string (date-time)): When the draft was saved lastupdatedBy(string): E-mail of who saved the draft lastversion(integer): Optimistic-lock version of the draft; send it with the next saveyaml(string): The draft definition (YAML)
Example 200 answer:
{
"diagnostics": [],
"updatedAt": "2026-11-17T10:45:12Z",
"updatedBy": "sophie.huber@muster-it.example",
"version": 6,
"yaml": "schemaVersion: 1\nkey: kritische-tickets-zusammenfassen\nname: Kritische Tickets zusammenfassen\ntriggers:\n - { id: neues_ticket, kind: event, event: desk.item.created, filter: \"trigger.data.priority in ['hoch', 'kritisch']\" }\nnodes:\n ticket:\n kind: action\n name: Ticket lesen\n action: desk.item.get\n params: { ref: \"{{ trigger.data.itemId }}\" }\n info:\n kind: mail\n name: Systemadministration informieren\n to: [\"person:jonas.bauer@muster-it.example\"]\n subject: \"Kritisches Ticket {{ trigger.data.number }}\"\n text: \"{{ nodes.ticket.output.title }}\"\nedges:\n - neues_ticket -\u003e ticket\n - ticket -\u003e info\n"
}
Example request
curl -X PUT 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/draft' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"version":5,"yaml":"schemaVersion: 1\nkey: kritische-tickets-zusammenfassen\nname: Kritische Tickets zusammenfassen\ntriggers:\n - { id: neues_ticket, kind: event, event: desk.item.created, filter: \"trigger.data.priority in ['\''hoch'\'', '\''kritisch'\'']\" }\nnodes:\n ticket:\n kind: action\n name: Ticket lesen\n action: desk.item.get\n params: { ref: \"{{ trigger.data.itemId }}\" }\nedges:\n - neues_ticket -\u003e ticket\n"}'