Skip to main content
POST
Prepare a debug attempt
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/prepareDebugAttempt Prepares a debug attempt of a draft node: the node is frozen, its inputs are resolved from the source run (and your explicitMappings), and each side effect is planned as simulated or real. A prepared attempt carries the planHash to launch it; a blocked one lists its blockers (for example an input to map by hand). Pass a blocked attemptId to prepare it again. An attempt never carries its agent thread or its creator. Preparing and launching run the node as a person: debug execution decides governance and credential access (credentials:use) for the attempt’s creator. So these need a Personal key; an External App or a platform key is 403 with personRequired: true.

Authentication

Personal key, External App credential or platform API key. Requires permission workflows:use, and the credential’s scopes must also reach workflows:read (a 403 naming it otherwise). Both are decided at the workflow’s home org unit. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator (externalApp:<id>, apiKey:<id>). When draft debugging (workflow_debug_execution) is off for you (a Personal key’s owner) or for the deployment (an app or platform key), the route answers 409 conflict.

Headers

string
Optional. A same-key retry within 24 hours returns the recorded answer without writing again, only while you still own the attempt it names and may debug its workflow at its home; otherwise 409 idempotency_result_unavailable. The same key with a different body is 422. See Idempotency.

Body

string
required
The workflow id.
string
required
The draft node to debug (a produce or procedure node).
string
required
A completed or failed production run of the workflow.
object[]
required
Inputs mapped by hand to an upstream output (inputKey, sourceNodeId, outputKey); [] for none.
string
A blocked attempt of yours to prepare again.

Responses

201 with the attempt (data.attemptId, data.status, data.planHash, data.blockers, data.resolvedInputs, data.effectPlan and the frozen data.targetSnapshot).

Errors

Example

Authorizations

Authorization
string
header
required

A Personal key (fmcp_…), bound to the person who created it, or an interactive MCP sign-in that resolves to one. Pass as Authorization: Bearer <key>. It acts for that person, under their role grants narrowed by its scopes; an operation that acts for a person admits only this kind.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

workflowId
string
required

The workflow id; its draft holds the node.

Minimum string length: 1

Body

application/json
nodeId
string
required

The draft node to debug (a produce or procedure node).

Minimum string length: 1
sourceRunId
string
required

A terminal production run of the workflow to take inputs from.

Minimum string length: 1
explicitMappings
object[]
required

Inputs mapped by hand to an upstream node's output; [] when none.

Maximum array length: 100
attemptId
string

A blocked attempt of yours to prepare again.

Minimum string length: 1

Response

The prepared or blocked attempt

data
object
required
meta
object
required