Resource shape
The list returnsWorkflowSummary rows and get returns the Workflow detail; both carry the same allowlisted identity fields (id, name, description, ownerId, owningOrgUnitId, timestamps, and so on). The list adds readable run counts; the detail adds the active version, deployment, and readable recent runs. The name is the dispatch key. Each read decides the workflow at its home org unit: the caller needs workflows:read there, and a workflow it cannot read answers 404 or is left out of the list.
Workflow ownership (External Apps and Personal keys)
Organization-owned External Apps can create empty drafts at their owning unit or a covered factory. Drafts recordexternalApp:<id> as their owner/creator attribution and persist the chosen home directly. 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 factory must be one the key may read), stamped with the owner. A platform API key cannot create. Draft updates use the caller’s read and write grants at the stored home; app ownership alone lends no authority. The list/detail readers retain their existing owner/creator strings, while the draft DTO omits those stamps.
Operations
Draft writes:POST /api/v3/workflows— createPATCH /api/v3/workflows/{workflowId}/draft— updateDraft
workflows:write scope and home grants for workflows:write plus workflows:read. Publishing is a lifecycle write.
Draft graph reads and edits (structure and content only; agent, worker, person, recipient, channel, credential, vault, tool, procedure, model and sandbox settings stay in Console):
GET /api/v3/workflows/{workflowId}/draft-graph— getDraftGraph — read the draft’s nodes and edges, at most 200 and 400, withmeta.partialPOST /api/v3/workflows/{workflowId}/draft-nodes— createDraftNodePATCH /api/v3/workflows/{workflowId}/draft-nodes/{nodeId}— updateDraftNodeDELETE /api/v3/workflows/{workflowId}/draft-nodes/{nodeId}— deleteDraftNodePOST /api/v3/workflows/{workflowId}/draft-edges— createDraftEdgePATCH /api/v3/workflows/{workflowId}/draft-edges/{edgeId}— updateDraftEdgeDELETE /api/v3/workflows/{workflowId}/draft-edges/{edgeId}— deleteDraftEdge
workflows:read at the workflow’s home; the six edits need the workflows:write scope and home grants for workflows:write plus workflows:read.
Draft validation:
GET /api/v3/workflows/{workflowId}/draft-validation— validateDraft — the Console validator’s findings and publishability for the draft, read-only, underworkflows:readat the workflow’s home
GET /api/v3/workflows/{workflowId}/versions— listVersions — page the workflow’s published versions, newest firstGET /api/v3/workflow-versions/{versionId}— getVersion — read one published versionGET /api/v3/workflow-versions/{versionId}/graph— getVersionGraph — read one version’s frozen nodes and edges, at most 200 and 400, withmeta.partial
workflows:read at the workflow’s home.
Workflow lifecycle (see Workflow lifecycle):
POST /api/v3/workflows/{workflowId}/publish-draft— publishDraft — publish the draft as a new active versionPOST /api/v3/workflows/{workflowId}/test-run-draft— testRunDraft — start a test run of the draftPOST /api/v3/workflow-versions/{versionId}/activate— rollback — make a superseded version active againPOST /api/v3/workflows/{workflowId}/reset-draft— resetDraft — replace the draft with a published version, discarding its editsGET /api/v3/workflow-capability-readiness— getCapabilityReadiness — whether each Agent node’s agent holds what the node needsGET /api/v3/workflows/{workflowId}/agent-readiness— getAgentReadiness — whether each Run-as-Agent node’s agent can be dispatchedGET /api/v3/workflows/{workflowId}/run-cost-forecast— getRunCostForecast — the next run’s expected cost
workflows:manage at the workflow’s home; a same-key purge retry returns the recorded result and never purges twice):
POST /api/v3/workflows/{workflowId}/retire— retire — stop a workflow from being launchedPOST /api/v3/workflows/{workflowId}/unretire— unretire — allow a retired workflow to be launched againPOST /api/v3/workflows/{workflowId}/trash— trash — soft-delete a workflowPOST /api/v3/workflows/{workflowId}/restore— restore — undo a trashPOST /api/v3/workflows/{workflowId}/purge— purge — delete a trashed workflow and everything it ownsPOST /api/v3/workflows/{workflowId}/set-tags— setTags — replace a workflow’s tagsPOST /api/v3/workflows/{workflowId}/set-owning-org-unit— setOwningOrgUnit — move a workflow to another owning org unitPOST /api/v3/workflows/{workflowId}/replace-asset— replaceAsset — bind a platform file to a workflow’s asset inputPOST /api/v3/workflows/create-from-template— createFromTemplate — instantiate a workflow templateGET /api/v3/workflows/{workflowId}/assets— listAssets — the files bound to a workflow’s asset inputsGET /api/v3/workflow-templates— listTemplates — the workflow templatesGET /api/v3/workflow-lookup— getByName — look a workflow up by its nameGET /api/v3/workflows/{workflowId}/bundle-export— exportBundle — export a workflow and its dependencies as a portable bundle
GET /api/v3/workflows/{workflowId}/architect-status— getArchitectStatus — whether the draft has a live Architect conversation and whether a person’s decision is pending, with the Console link, underworkflows:readat the workflow’s homeGET /api/v3/workflows/{workflowId}/architect-plan— getArchitectPlan — the pending plan and the human task a person decides it on, underworkflows:readat the workflow’s homeGET /api/v3/workflows/{workflowId}/architect-progress— getArchitectProgress — the build manifest and synthesis drive, at most 200 rows each withmeta.partial, underworkflows:readat the workflow’s homeGET /api/v3/workflows/{workflowId}/synthesis-confirmation— getSynthesisConfirmation — the pending synthesis batch with its specs and estimates, underworkflows:writeat the workflow’s homeGET /api/v3/workflows/{workflowId}/architect-decisions— getArchitectDecisions — the resolved plans and batches, newest first, underworkflows:readat the workflow’s homeGET /api/v3/workflows/{workflowId}/architect-jit-mode— getArchitectJitMode — the conversation’s and the workspace’s just-in-time synthesis modes, underworkflows:readat the workflow’s homePOST /api/v3/runs/{runId}/ask-architect-to-fix— askArchitectToFixRun — open a failed run’s failure in an Architect conversation, underworkflows:writeat the run’s workflow’s homePOST /api/v3/workflows/create-from-chat-task— createFromChatTask — save a completed Personal Agent task as a workflow, Personal key onlyPOST /api/v3/workflows/{workflowId}/set-architect-jit-mode— setArchitectJitMode — turn just-in-time synthesis on or off, for the draft’s author or aplatform:manageholderPOST /api/v3/workflows/start-architect-conversation— startArchitectConversation — create a workflow from a brief and start the Architect’s first turn, Personal key onlyPOST /api/v3/workflows/{workflowId}/architect-messages— sendArchitectMessage — send the next message and start its turn, Personal key only; refused while a turn is in progressGET /api/v3/workflows/{workflowId}/architect-messages— listArchitectMessages — one transcript page and the turn’s state to poll, underworkflows:writeat the workflow’s homePOST /api/v3/workflows/{workflowId}/cancel-architect-turn— cancelArchitectTurn — ask a running turn to stop, underworkflows:writeat the workflow’s homePOST /api/v3/workflows/{workflowId}/reset-architect-conversation— resetArchitectConversation — archive the conversation so the next message starts fresh, underworkflows:writeat the workflow’s home
GET /api/v3/workflows/{workflowId}/debug-options— getDebugOptions — a draft node and the production runs to debug it againstPOST /api/v3/workflows/{workflowId}/debug-attempts— prepareDebugAttempt — freeze a draft node and plan a debug attempt, Personal key onlyPOST /api/v3/workflow-debug-attempts/{attemptId}/launch— launchDebugAttempt — run a prepared attempt, Personal key onlyGET /api/v3/workflow-debug-attempts/{attemptId}— getDebugAttempt — one of your attempts and, once run, its outputPOST /api/v3/workflow-debug-attempts/{attemptId}/cancel— cancelDebugAttempt — stop a queued or running attemptGET /api/v3/workflow-debug-attempts/{attemptId}/history— listDebugAttemptHistory — your earlier attempts of the same nodeGET /api/v3/workflow-debug-attempts/{attemptId}/comparison— compareDebugAttempts — an attempt beside an earlier finished oneGET /api/v3/workflow-debug-attempts/{attemptId}/files— listDebugFiles — the files an attempt read and wroteGET /api/v3/workflow-debug-attempts/{attemptId}/file-urls/{fileId}— getDebugFileUrl — a bearer download link for one of themGET /api/v3/workflow-debug-attempts/{attemptId}/tool-calls— listDebugToolCalls — an attempt’s tool calls, newest first, a page at a time (limit1–200, default 50)GET /api/v3/workflow-versions/{versionId}/debug-preview-options— getDebugPreviewOptions — a published version’s nodes and source runsGET /api/v3/workflow-versions/{versionId}/debug-slice-preview— previewDebugSlice — the historical inputs a published slice would readGET /api/v3/procedures/{procedureId}/repin-preview— previewProcedureRepin — what re-pinning a procedure’s draft callers changes, underworkflows:readPOST /api/v3/workflows/{workflowId}/repin-procedure— repinProcedure — re-pin procedure nodes of one draft, underworkflows:writeat its homePOST /api/v3/workflows/test-route-condition— testRouteCondition — evaluate a route condition against a sample input, underworkflows:read
GET /api/v3/workflows— listWorkflows — list published workflow definitionsGET /api/v3/workflows/{workflowId}— getWorkflow — fetch a single workflow definition by IDGET /api/v3/workflows/{workflowId}/input-schema— getInputSchema — fetch the active (or a named published) version’s input-schema shape for typed UI renderingGET /api/v3/workflows/{workflowId}/draft— getDraft — read the workflow’s editable draft: identity, metadata and canonical input contractGET /api/v3/workflows/{workflowId}/triggers— listTriggers — list the workflow’s schedules and other triggersGET /api/v3/workflow-triggers/{triggerId}— getTrigger — read one triggerGET /api/v3/workflow-triggers— listScheduleRoster — every trigger the caller may read, across workflows, with its latest runPOST /api/v3/workflows/{workflowId}/triggers— createTrigger — schedule a workflow (cron or one-shot)PATCH /api/v3/workflow-triggers/{triggerId}— updateTrigger — change a schedulePOST /api/v3/workflow-triggers/{triggerId}/pause— pauseTrigger — stop a schedule firingPOST /api/v3/workflow-triggers/{triggerId}/resume— resumeTrigger — resume a paused scheduleDELETE /api/v3/workflow-triggers/{triggerId}— deleteTrigger — delete a triggerPOST /api/v3/workflows/{workflowId}/ingress-triggers— createIngressTrigger — create an inbound URL; returns its token oncePOST /api/v3/workflow-triggers/{triggerId}/set-ingress-status— setIngressStatus — pause or resume an inbound URLPOST /api/v3/workflow-triggers/{triggerId}/rotate-ingress-token— rotateIngressToken — mint a new token; returns it oncePATCH /api/v3/workflow-triggers/{triggerId}/ingress-config— updateIngressConfig — change an inbound URL’s configGET /api/v3/fiscal-calendars— listFiscalCalendars — list fiscal calendarsGET /api/v3/fiscal-calendars/{calendarName}— getFiscalCalendar — read one fiscal calendarPOST /api/v3/fiscal-calendars— createFiscalCalendar — create a fiscal calendarPATCH /api/v3/fiscal-calendars/{calendarName}— updateFiscalCalendar — change a fiscal calendarDELETE /api/v3/fiscal-calendars/{calendarName}— deleteFiscalCalendar — delete a fiscal calendar no published version citesGET /api/v3/workflow-steps— listSteps — browse the step libraryPOST /api/v3/workflow-steps— createStep — add a step library entryPATCH /api/v3/workflow-steps/{stepId}— updateStep — change a step library entryDELETE /api/v3/workflow-steps/{stepId}— deleteStep — remove a step library entryGET /api/v3/workflow-triggers/{triggerId}/ingress-invocations— listIngressInvocations — pages an ingress trigger’s requests, newest first
POST /api/v3/workflows/dispatch— dispatch — trigger a run by workflow name or id with input arguments; withworkflowId,versionIdruns one of its published versions
Schedules and other triggers
A workflow can be started by a schedule (cron), a single scheduled fire (one_shot), a capability URL (ingress) or a routed email (email). listTriggers and getTrigger read them: kind, timing, whether each follows the active version or pins one, the org unit its fires run at, and when it fires next. A trigger is visible only when the caller holds workflows:read at both the workflow’s home and the trigger’s orgUnitId, because the runs a trigger starts are recorded at its orgUnitId. The owner, creator, stored inputs and ingress material are never returned.
listIngressInvocations reads an ingress trigger’s requests under the same rule, and listScheduleRoster lists every trigger the caller may read across workflows, with each one’s latest run when the caller may read runs there.
The trigger writes run the Console’s own commands and need workflows:manage where the Console decides it: at the workflow’s home and the new trigger’s org unit for a create, and at the trigger’s org unit and the platform scope for every other write. A trigger runs a published version, so its agents and bound companies are decided for the caller as at a publish. A Personal key’s trigger belongs to its owner’s worker seat; an External App’s or platform API key’s belongs to the app or key and stops when it loses workflows:manage. An ingress token and its URL are returned once, at create and rotate, and never stored. An email trigger is changed with its email route.
Fiscal calendars
Fiscal calendars name the fiscal-year start month thatfiscalPeriod() expressions and derived launch inputs use. Machine credentials with workflows:read can list the deployment-wide catalog or read one calendar by its lowercase slug. The response omits row ids and the people who created or changed each calendar.
Creating, changing and deleting a calendar, and the step library’s writes, need workflows:manage held at the platform scope (the elevated workflows:manage scope; Forge agents can never hold it), plus the workflows:read scope because each answers what it wrote. A calendar’s name never changes, and a calendar an active published version cites cannot be deleted. Each change is audited with the credential (a Personal key as its owner).
Step library
The step library holds reusable steps: a command with its inputs, outputs and success criteria. listSteps browses it underworkflows:read at the platform scope, never returning a step’s author. createStep, updateStep and deleteStep change it under workflows:manage; a step’s author is always the caller. Deleting a step does not change workflows already built from it, which keep their own copy of its command. With an Idempotency-Key, the library’s writes replay under the workflow library rule.
Workflow lifecycle
Publishing a draft, test-running it, rolling back to a version and resetting the draft needworkflows:manage held at the platform scope, as the Console decides it (the elevated workflows:manage scope; Forge agents can never hold it), plus the workflows:read scope because each success answers a read, and the workflow must be readable at its home. A Personal key acts as its owner, narrowed by its scopes; an External App or platform API key acts as itself. Each change is stored and audited with that actor under the Console’s own audit events.
Publishing and rolling back decide the version’s agents and bound companies for the caller as at a Console publish: agents:use for the agents it runs and credentials:use at each bound company. The workflows:manage scope carries both, and each is still decided at its own home. Publish and rollback require expectedActiveVersionId, so two callers never publish over each other. Validate a draft with validateDraft before publishing it. A test run is a run: read and cancel it with the runs routes.
The three reads need workflows:read at the workflow’s home. With an Idempotency-Key, publish, rollback and reset replay under the workflow lifecycle rule, and a test run under the workflow dispatch rule.
Driving the Architect from the API
A Personal key runs the same loop a person runs in the Architect drawer. Each turn acts for the key’s owner, never with more than the key’s scopes carry, and each start or send spends one of the key’s Architect turns (60 an hour, burst 10;429 rate_limited with Retry-After past that).
1
Start the conversation
POST /api/v3/workflows/start-architect-conversation with your brief. The answer names the new workflow and its draft, with turn.state: "running".2
Poll until the turn is idle
GET /api/v3/workflows/{workflowId}/architect-messages no faster than every 2 seconds until turn.state is "idle", then read the new architect items. A turn ends within 9 minutes.3
Let a person decide a plan or batch
When the Architect proposes a plan,
getArchitectPlan returns it with its humanTaskId. A person confirms it with POST /api/v3/governance-human-tasks/{humanTaskId}/complete (which needs approvals:write:decide) or in the Console; a pending synthesis batch works the same way through getSynthesisConfirmation.4
Continue
POST /api/v3/workflows/{workflowId}/architect-messages with the next message once the turn is idle. A message sent while a turn is running, queued or stopping is refused with 409 and nothing is queued.cancelArchitectTurn stops a running turn at its next step, and resetArchitectConversation archives a conversation that cannot continue. An External App or a platform API key can read, cancel and reset, but not start or send.
Draft debugging
Draft debugging runs one node of a workflow’s draft against the inputs of a past production run, as the Console builder’s Debug does. Find the node and a source run with getDebugOptions, prepare an attempt (the node is frozen, its inputs resolved, each side effect planned as simulated or real), launch it with itsplanHash, and poll getDebugAttempt for its output.
- Who. The debug routes need
workflows:use, and the credential’s scopes must also reachworkflows:read; both are decided at the workflow’s home. A missing, trashed, unhomed or unreachable workflow is a404. - The source run’s companies. An attempt carries the source run’s historical values, so preparing from a run and reading an attempt also need
workflows:useat every company the run carries; otherwise it is the same404. Once the source run has been deleted, its attempts are404too. - Debugging is personal. As in the Console, you debug drafts you created and read attempts you started. A Personal key is its owner; an External App or a platform API key is its own creator. Another person’s attempt is the same
404as a missing one. - Running needs a person. Preparing and launching run the node as the attempt’s creator: governance and
credentials:useare decided for them. So these two routes need a Personal key; any other credential is403withpersonRequired: true. - The flag. When draft debugging (
workflow_debug_execution) is off for you (a Personal key’s owner) or for the deployment (an app or platform API key), every debug route answers409 conflict. - What never crosses. An attempt’s agent thread and creator, a file’s storage handle, and a tool call’s agent. A file’s download link is a bearer link, recorded before it exists.
- Published previews read a version, not an attempt: they are not personal. The slice preview returns the source run’s historical values, so it also needs
workflows:useat every company the run carries. - Retries. With an
Idempotency-Key, the attempt writes replay under the workflow debug rule; a launch’s key is also the launch’s own.
Reading the input schema
Integrations that render typed input forms before dispatch (Slack/workflow modals, custom dashboards, the Forge Console dispatch dialog) call GET /api/v3/workflows/{workflowId}/input-schema to retrieve the input shape for the workflow’s active version. Add versionId to read one published version’s contract instead (the form for re-running a specific version). The response carries two parallel fields:
workflowInputSchemais the input contract. Array-of-objects so order is preserved across the wire. Each entry declaresname,type("string"·"number"·"boolean"·"object"·"file"·"string[]"·"number[]"·"file[]"),required: boolean, and optionaldefault,description,validation(enum·min·max·pattern).
[] rather than storing a hole — so a version whose workflowInputSchema is an empty array declares no inputs. It is not a version whose contract lives somewhere else: there is nowhere else left for it to live.
workflowInputSchema: null has two meanings, and version tells them apart:
Treating the second row as the first renders a launchable-looking workflow whose dispatch then fails, which is why the discriminator is worth reading rather than checking
workflowInputSchema alone. A 404 indicates the workflow id does not exist or is malformed.
Dispatch validation
The dispatch endpoint validatesruntimeArgs against workflowInputSchema strictly — no type coercion. A "42" string supplied for a type: "number" field is rejected with a 400 bad_request, not silently coerced. Required fields missing from runtimeArgs produce a 400 listing the missing field name. Validation constraints (enum, min, max, pattern) are enforced server-side. Unknown args (keys that name no declared field) are rejected to keep the contract bidirectional.
workflowInputSchema is the only representation dispatch reads, and there is no legacy fallback at validation time. Every writer persists it, and an empty array is how “declares no inputs” is spelled. A version carrying no canonical array at all has an unreadable contract, not an empty one, and there is no backfill left to wait for. Dispatch refuses it before validating arguments, so the failure is never blamed on the caller’s runtimeArgs:
POST /api/v3/workflows/dispatch→503,error.code: "internal_error", messageThis workflow's input contract is unreadable; it must be republished before it can be dispatched.- Signed ingress →
503, reason prefixedworkflow contract unavailable: workflowV2/contract-unmigrated:.
workflows:read.
Dispatch callbacks
POST /api/v3/workflows/dispatch accepts an optional callback object. When supplied, the run’s terminal state produces exactly one signed POST to your URL, so an integration can wait for a result without polling GET /api/v3/runs/{runId}.
Who can use it
External Application callers only. The delivery is signed with the calling app’s signing secret; a platform API key that belongs to no app has none, and Forge will not deliver an unsigned POST to a caller-supplied URL — at the receiver that is indistinguishable from a forgery. A caller with no owning app gets422.
Validation at dispatch time
The URL is checked before the dispatch is accepted, not at delivery time twenty minutes later:What gets delivered
One POST at terminal run state, through the same pipeline that carries webhook subscriptions: 3 attempts with 5s / 10s / 20s backoff, a 10-second timeout,redirect: "error" (a redirect is a delivery failure, not something to follow), and the dead-letter queue on exhaustion.
The body is always the v2 envelope — there is no v1 callback shape:
type is workflow.completed only for a genuinely completed run. failed and cancelled both map to workflow.failed — a caller waiting on a result cares that it did not get one. The exact terminal status is on data.status.
id is deterministic (callbackevent_<runId>), so all three delivery attempts carry the same event id and your dedupe key holds. It is deliberately not an event-log id: a callback is point-to-point and is not written to the canonical log, so GET /api/v3/events will not resolve it.Verifying a callback
Callbacks are signed with a callback signing secret — one per External App, a different key fromclient_secret. It is minted lazily the first time the app uses a callback, revealed once, and rotatable via POST /api/v3/external-apps/{externalAppId}/rotate-callback-secret.
The header and algorithm are identical to webhook subscriptions:
v1 is the HMAC-SHA256 over t + "." + body, keyed by the callback signing secret. The timestamp is inside the signed message, so a captured delivery cannot have its t refreshed without the key. Reject deliveries whose t is more than 5 minutes from now, in either direction — without that check the timestamp buys you nothing. Retries are re-signed with a fresh t, so a legitimate retry never trips your window.
Sign over the bytes you received, not a re-serialization: a JSON.parse → JSON.stringify round trip can reorder keys or reformat numbers and will break verification.
X-Forge-Event (the event type), X-Forge-Delivery (stable across all attempts of the same delivery), and X-Forge-Signature-V2.
Known limitation: one callback per run row
The delivery id is derived from the run id, which is what makes the callback exactly-once. The consequence is that a workflow rerun on the same run row does not re-arm the callback — the enqueue finds the row already present and returns without scheduling a second POST. A rerun is an operator action against an existing run, not a second dispatch, and the caller that asked for a completion signal has already been given one. If you need a signal per attempt, dispatch again rather than rerunning.Starting a run without a credential
Senders that cannot hold an OAuth token — GitHub, Linear, Zapier, vendor “notify this URL” fields — use signed workflow ingress instead: an unauthenticated capability URL scoped to one workflow, with optional per-trigger HMAC verification, idempotency, and a rate limit. Ingress has no callback; the run is observed through the Runs API or a webhook subscription.Common workflows
Discover a workflow, read its input schema, and trigger a run:Related
- Workflows overview — conceptual background on graph orchestration
- Workflow node types — agent, router, join, human, publish
- Native HTTP quickstart — call these endpoints with
fetchand a bearer token

