Skip to main content
POST
Create an empty workflow draft
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

POST /api/v2/workflows/create 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. An organization-owned External App creates at its owning unit: without factoryId, the owning org unit becomes the workflow home, and a supplied factory must already have a home within that unit’s tree. A Personal key creates as its owner, at the home the Console gives that person’s workflow (the factory’s, else the owner’s, else the deployment root); a supplied factory must be one the key may read, and the workflow is stamped with the owner. A platform key cannot create, and neither can an app without a resolvable owning unit: both receive 403. Malformed, missing, unhomed and out-of-reach factories receive the same 404 resource_missing. The strict body accepts name, optional description, optional factoryId, and optional workflowInputSchema. A missing input contract becomes []. Success is 201 with { data: { workflowId, draftId }, meta: { requestId } }. 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, credentials, vaults and live execution stay outside this operation; output and notification settings, default agents and the runtime contract are set with updateDraft. 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

Body

application/json
name
string
required
factoryId
string
Minimum string length: 1
description
string
workflowInputSchema
object[]

Response

Workflow draft saved

data
object
required
meta
object
required