Workflow Drafts

Draft workspaces for workflows, mirroring agent drafts. Every save commits an immutable version onto a parent chain; publishing copies a version out into a **new** published workflow carrying draft lineage. Draft saves are validation-lenient — an incomplete DAG is allowed while editing. Publishing validates the definition strictly, using the same rules as creating a published workflow version.

List workflow drafts

GET

/v1/workflow-drafts

Drafts visible to the caller, most recently updated first. Pass mine=true for the library view: only the caller's own.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Query Parameters

mine

Type

boolean

Default

false

Responses

Successful Response

Content-Type

application/json

{

  

"items": [

  

  

{

  

  

  

"agent_names": [

  

  

  

  

[

  

  

  

  

]

  

  

  

],

  

  

  

"connector_providers": [

  

  

  

  

[

  

  

  

  

]

  

  

  

],

  

  

  

"created_at": "string",

  

  

  

"created_by": "string",

  

  

  

"created_by_name": "string",

  

  

  

"cron_expression": "string",

  

  

  

"cron_timezone": "string",

  

  

  

"head_version_id": "string",

  

  

  

"icon_name": "string",

  

  

  

"id": "string",

  

  

  

"name": "string",

  

  

  

"next_version_number": 0,

  

  

  

"node_count": 0,

  

  

  

"org_id": "string",

  

  

  

"team_ids": [

  

  

  

  

"string"

  

  

  

],

  

  

  

"trigger_kinds": [

  

  

  

  

[

  

  

  

  

]

  

  

  

],

  

  

  

"updated_at": "string",

  

  

  

"visibility": "string"

  

  

}

  

]

}

Samples

Create a workflow draft

POST

/v1/workflow-drafts

Create a draft workspace and mint its first version. Pass at most one of
source_workflow_id or source_version_id to seed it from existing work;
either returns 404 when the source is missing or unreadable.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Request Body

application/json

Default""

Default"zap"

Default""

Any of

Format"uuid"

Any of

Format"uuid"

Format"uuid"

Valid values"personal""team_level""org_level""community""universal"

Default"personal"

Responses

Successful Response

Content-Type

application/json

{

  

"agent_names": [

  

  

[

  

  

]

  

],

  

"connector_providers": [

  

  

[

  

  

]

  

],

  

"created_at": "string",

  

"created_by": "string",

  

"created_by_name": "string",

  

"cron_expression": "string",

  

"cron_timezone": "string",

  

"has_webhook_token": false,

  

"head_version_id": "string",

  

"icon_name": "string",

  

"id": "string",

  

"name": "string",

  

"next_version_number": 0,

  

"node_count": 0,

  

"org_id": "string",

  

"runs_url": "string",

  

"team_ids": [

  

  

"string"

  

],

  

"trigger_kinds": [

  

  

[

  

  

]

  

],

  

"updated_at": "string",

  

"versions": [

  

  

{

  

  

  

"created_at": "string",

  

  

  

"created_by": "string",

  

  

  

"definition": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"description": "string",

  

  

  

"draft_id": "string",

  

  

  

"icon_name": "string",

  

  

  

"id": "string",

  

  

  

"name": "string",

  

  

  

"node_count": 0,

  

  

  

"parent_version_id": "string",

  

  

  

"title": "string"

  

  

}

  

],

  

"visibility": "string",

  

"webhook_token_redacted": "string",

  

"webhook_url": "string"

}

Samples

Delete a workflow draft

DELETE

/v1/workflow-drafts/{draft_id}

Delete a draft and every version in its chain. Workflows already published from
it are unaffected.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Samples

Get a workflow draft

GET

/v1/workflow-drafts/{draft_id}

Get a draft with the summaries of every version in its chain.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Content-Type

application/json

{

  

"agent_names": [

  

  

[

  

  

]

  

],

  

"connector_providers": [

  

  

[

  

  

]

  

],

  

"created_at": "string",

  

"created_by": "string",

  

"created_by_name": "string",

  

"cron_expression": "string",

  

"cron_timezone": "string",

  

"has_webhook_token": false,

  

"head_version_id": "string",

  

"icon_name": "string",

  

"id": "string",

  

"name": "string",

  

"next_version_number": 0,

  

"node_count": 0,

  

"org_id": "string",

  

"runs_url": "string",

  

"team_ids": [

  

  

"string"

  

],

  

"trigger_kinds": [

  

  

[

  

  

]

  

],

  

"updated_at": "string",

  

"versions": [

  

  

{

  

  

  

"created_at": "string",

  

  

  

"created_by": "string",

  

  

  

"definition": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"description": "string",

  

  

  

"draft_id": "string",

  

  

  

"icon_name": "string",

  

  

  

"id": "string",

  

  

  

"name": "string",

  

  

  

"node_count": 0,

  

  

  

"parent_version_id": "string",

  

  

  

"title": "string"

  

  

}

  

],

  

"visibility": "string",

  

"webhook_token_redacted": "string",

  

"webhook_url": "string"

}

Samples

Update a workflow draft

PATCH

/v1/workflow-drafts/{draft_id}

Update the draft's visibility and team scope. Applies to the whole workspace,
not to individual versions. Omitted fields are left unchanged.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Request Body

application/json

Any of

Format"uuid"

Any of

Valid values"personal""team_level""org_level""community""universal"

Responses

Successful Response

Content-Type

application/json

{

  

"agent_names": [

  

  

[

  

  

]

  

],

  

"connector_providers": [

  

  

[

  

  

]

  

],

  

"created_at": "string",

  

"created_by": "string",

  

"created_by_name": "string",

  

"cron_expression": "string",

  

"cron_timezone": "string",

  

"has_webhook_token": false,

  

"head_version_id": "string",

  

"icon_name": "string",

  

"id": "string",

  

"name": "string",

  

"next_version_number": 0,

  

"node_count": 0,

  

"org_id": "string",

  

"runs_url": "string",

  

"team_ids": [

  

  

"string"

  

],

  

"trigger_kinds": [

  

  

[

  

  

]

  

],

  

"updated_at": "string",

  

"versions": [

  

  

{

  

  

  

"created_at": "string",

  

  

  

"created_by": "string",

  

  

  

"definition": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"description": "string",

  

  

  

"draft_id": "string",

  

  

  

"icon_name": "string",

  

  

  

"id": "string",

  

  

  

"name": "string",

  

  

  

"node_count": 0,

  

  

  

"parent_version_id": "string",

  

  

  

"title": "string"

  

  

}

  

],

  

"visibility": "string",

  

"webhook_token_redacted": "string",

  

"webhook_url": "string"

}

Samples

Suggest a description for a workflow draft

POST

/v1/workflow-drafts/{draft_id}/description:generate

Writes a one-sentence description of the draft's head version and RETURNS it without saving. Fill the field with it and let the author edit before they commit.

The source is the version's own name and its steps in order — a workflow holds no instructions of its own, so the steps are what there is to describe.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Content-Type

application/json

{

  

"description": "string"

}

Samples

Test a single node

POST

/v1/workflow-drafts/{draft_id}/nodes/{node_id}/test

Execute one node of the draft's head version in isolation against an input you
supply. Nothing is persisted — no run and no steps are created.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

node_id*

Type

string

Required

Request Body

application/json

Responses

Successful Response

Content-Type

application/json

{

  

"cost": 0,

  

"duration_ms": 0,

  

"output": "string",

  

"token_usage": {

  

  

"additionalProperties": "string"

  

}

}

Samples

Publish a draft

POST

/v1/workflow-drafts/{draft_id}/publish

Publish a version as a new workflow. Publishing never mutates an existing
workflow; the result carries draft lineage back to the version it came from.

The definition is validated strictly, using the same rules as creating a
published workflow version: 422 with one message per violation when it fails,
and 409 when the version has no name.

When the published version's trigger kinds include webhook, a secret is minted
or a draft-minted one is transferred. webhook_token carries the plaintext
once, and only when newly minted — a transferred secret omits it, since it
was already shown when the draft generated it.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Request Body

application/json

Format"uuid"

Responses

Successful Response

Content-Type

application/json

{

  

"active_version_id": "string",

  

"active_version_number": 0,

  

"agent_names": [

  

  

[

  

  

]

  

],

  

"can_write": true,

  

"connector_providers": [

  

  

[

  

  

]

  

],

  

"created_at": "string",

  

"created_by": "string",

  

"created_by_name": "string",

  

"cron_expression": "string",

  

"cron_timezone": "string",

  

"delist_listing_id": "string",

  

"description": "string",

  

"graph_shape": {

  

  

"edges": [

  

  

  

[

  

  

  

]

  

  

],

  

  

"nodes": [

  

  

  

{

  

  

  

  

"type": "string"

  

  

  

}

  

  

]

  

},

  

"has_webhook_token": false,

  

"icon_name": "string",

  

"id": "string",

  

"last_run_at": "string",

  

"listing_source_id": "string",

  

"name": "string",

  

"node_count": 0,

  

"org_name": "string",

  

"pinned": false,

  

"run_count": 0,

  

"runs_url": "string",

  

"source_draft_id": "string",

  

"team_ids": [

  

  

"string"

  

],

  

"trigger_kinds": [

  

  

[

  

  

]

  

],

  

"updated_at": "string",

  

"visibility": "string",

  

"webhook_token": "string",

  

"webhook_token_redacted": "string",

  

"webhook_url": "string"

}

Samples

List draft runs

GET

/v1/workflow-drafts/{draft_id}/runs

List the runs of the draft's carrier workflow. Paginated and filterable.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Query Parameters

page

Type

integer

Default

1

Minimum

1

page_size

Type

integer

Default

20

Maximum

100

Minimum

1

status

version_id

sort

Type

string

Default

"created_at"

order

Type

string

Default

"desc"

Responses

Successful Response

Content-Type

application/json

{

  

"items": [

  

  

{

  

  

  

"completed_at": "string",

  

  

  

"created_at": "string",

  

  

  

"created_by": "string",

  

  

  

"created_by_name": "string",

  

  

  

"duration_ms": 0,

  

  

  

"failed_count": 0,

  

  

  

"id": "string",

  

  

  

"input": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"node_count": 0,

  

  

  

"run_number": 0,

  

  

  

"source_draft_id": "string",

  

  

  

"source_draft_version_id": "string",

  

  

  

"started_at": "string",

  

  

  

"status": "string",

  

  

  

"succeeded_count": 0,

  

  

  

"total_cost": 0,

  

  

  

"total_tokens": 0,

  

  

  

"trigger_type": "string",

  

  

  

"version_number": 0,

  

  

  

"workflow_id": "string",

  

  

  

"workflow_name": "string"

  

  

}

  

],

  

"page": 0,

  

"page_size": 0,

  

"total": 0

}

Samples

Trigger a draft run

POST

/v1/workflow-drafts/{draft_id}/runs

Start a test run of the draft's head version on its carrier workflow, so the
graph can be exercised before it is published.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Request Body

application/json

Any of

Any of

Format"uuid"

Responses

Successful Response

Content-Type

application/json

{

  

"completed_at": "string",

  

"created_at": "string",

  

"created_by": "string",

  

"created_by_name": "string",

  

"id": "string",

  

"input": {

  

  

"additionalProperties": "string"

  

},

  

"started_at": "string",

  

"status": "string",

  

"version_id": "string",

  

"version_number": 0,

  

"workflow_id": "string"

}

Samples

Get Draft Active Run

GET

/v1/workflow-drafts/{draft_id}/runs/active

Most recent non-terminal run for this draft, if any — lets the editor
resume tracking a run's progress after a page refresh.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Content-Type

application/json

{

  

"completed_at": "string",

  

"created_at": "string",

  

"created_by": "string",

  

"created_by_name": "string",

  

"id": "string",

  

"input": {

  

  

"additionalProperties": "string"

  

},

  

"started_at": "string",

  

"status": "string",

  

"version_id": "string",

  

"version_number": 0,

  

"workflow_id": "string"

}

Samples

Get the latest draft run

GET

/v1/workflow-drafts/{draft_id}/runs/latest

Get the most recent run of any status on the draft's carrier workflow, or
null when it has never been run.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Content-Type

application/json

{

  

"completed_at": "string",

  

"created_at": "string",

  

"created_by": "string",

  

"created_by_name": "string",

  

"id": "string",

  

"input": {

  

  

"additionalProperties": "string"

  

},

  

"started_at": "string",

  

"status": "string",

  

"version_id": "string",

  

"version_number": 0,

  

"workflow_id": "string"

}

Samples

Validate a definition

POST

/v1/workflow-drafts/{draft_id}/validate

Check a candidate definition against the DAG rules without saving it. The
editor calls this as the graph changes on screen, so the body's definition
need not match any saved version.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Request Body

application/json

Responses

Successful Response

Content-Type

application/json

{

  

"errors": [

  

  

"string"

  

],

  

"issues": [

  

  

{

  

  

  

"code": "string",

  

  

  

"message": "string",

  

  

  

"node_id": "string",

  

  

  

"params": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"severity": "string"

  

  

}

  

],

  

"ok": true,

  

"warnings": [

  

  

"string"

  

]

}

Samples

Commit a draft version

POST

/v1/workflow-drafts/{draft_id}/versions

Commit a version onto the parent chain. This is the save mechanism: every
explicit save posts here.

Draft saves are validation-lenient, so an incomplete DAG is accepted while
editing. Strict validation happens at publish. One rule applies to every save:
an agent step takes a tool agent only, and a step bound to a chat agent returns
422 naming the step.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Request Body

application/json

Any of

Any of

Defaultfalse

Any of

Any of

Format"uuid"

Any of

Max Length256

Responses

Successful Response

Content-Type

application/json

{

  

"version": {

  

  

"created_at": "string",

  

  

"created_by": "string",

  

  

"definition": {

  

  

  

"additionalProperties": "string"

  

  

},

  

  

"description": "string",

  

  

"draft_id": "string",

  

  

"icon_name": "string",

  

  

"id": "string",

  

  

"name": "string",

  

  

"node_count": 0,

  

  

"parent_version_id": "string",

  

  

"title": "string"

  

}

}

Samples

Delete a draft version

DELETE

/v1/workflow-drafts/{draft_id}/versions/{version_id}

Delete a single version and reparent its descendants, keeping the chain
connected.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

version_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Samples

Rename a draft version

PATCH

/v1/workflow-drafts/{draft_id}/versions/{version_id}

Set a custom title on a draft version.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

version_id*

Type

string

Required

Format

"uuid"

Request Body

application/json

Max Length256

Min Length1

Responses

Successful Response

Content-Type

application/json

{

  

"created_at": "string",

  

"created_by": "string",

  

"definition": {

  

  

"additionalProperties": "string"

  

},

  

"description": "string",

  

"draft_id": "string",

  

"icon_name": "string",

  

"id": "string",

  

"name": "string",

  

"node_count": 0,

  

"parent_version_id": "string",

  

"title": "string"

}

Samples

Rotate the draft webhook secret

POST

/v1/workflow-drafts/{draft_id}/webhook-token/rotate

Mint or rotate a webhook secret on the draft, returning the plaintext once.
The secret transfers onto the published workflow at publish. Requires write
access; returns 409 when the head version's trigger kinds do not include
webhook.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Parameters

Path Parameters

draft_id*

Type

string

Required

Format

"uuid"

Responses

Successful Response

Content-Type

application/json

{

  

"created_at": "string",

  

"webhook_token": "string",

  

"webhook_url": "string"

}

Samples