Skip to main content
PATCH
Update workflow draft metadata and inputs
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

PATCH /api/v2/workflows/updateDraft Requires workflows:write and workflows:read: the credential’s scopes must reach both, and its grants must hold both at the target workflow home. The Console builder observes the committed draft immediately. The strict body requires workflowId and accepts optional name, description, workflowInputSchema, runtimeContract (outcomesV1), notificationPolicy (operatorUserIds and requiredSlackTargets), outputPolicy (the completion callback: disabled, fixed with url and appId, or caller), defaultValidatorAgent and defaultRouterAgent (agent ids). workflowOutputs stays Console-only. Inputs replace the whole canonical contract; read getDraft before editing. Success is 200 with the same allowlisted draft DTO returned by that read. Missing, trashed, draftless, unhomed and unreadable/unwritable workflows all answer the same 404. A fixed output callback needs apps:manage at the application’s home, and changing the required Slack targets needs connections:manage, each granted and reached by the credential’s scopes: either refusal is 403 naming the key, and nothing is written. A notification recipient or Slack target the workflow’s home cannot use answers 422, and so does an invalid fixed callback (its URL, or an inactive or out-of-home application), naming the reason. Names are trimmed. Empty names, unknown keys, malformed JSON and wrong field types answer 400 bad_request. A duplicate (factoryId, name) answers409 conflict, including a clash in another home, matching Console uniqueness. Canonical input authoring errors, including unknown fiscal calendars, answer 422 unprocessable with the canonical message. Refusals make no draft-domain changes. Send Idempotency-Key for a stable intent. Within its original 24-hour claim, repeat the identical body and key: the recorded 201/200 result is disclosed only if the caller still holds route permission and can read the original draft at its stored home. A withheld result or unknown outcome answers409 and does not write again. Reconcile authorized draft state before a new intent; after retention a repeat can execute again. Static External App companion keys do not support keyed replay. Publishing (publishDraft), versions, graph editing, workflow outputs, credentials, vaults and live execution stay outside this operation. No person identity or principal field can be supplied.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Path Parameters

workflowId
string
required
Minimum string length: 1

Body

application/json
name
string
description
string
workflowInputSchema
object[]
runtimeContract
enum<string>

Opt the draft into the outcomes run contract.

Available options:
outcomesV1
notificationPolicy
object
outputPolicy
object

fixed needs apps:manage at the application's home; caller sends to the dispatching app's callback.

defaultValidatorAgent
string

The agent that validates node outputs by default, by agent id.

Minimum string length: 1
defaultRouterAgent
string

The agent that routes by default, by agent id.

Minimum string length: 1

Response

Workflow draft saved

data
object
required

GET /api/v2/workflows/getDraft: the workflow's editable draft. name, description and factoryId are the workflow's; the rest is the draft's. No output, notification, vault, credential or person field is returned.

meta
object
required