Dispatch a workflow run
Launch the active published version of a workflow by name or by id, or one of its published versions by id, and receive the run’s durable identity. Requires permission workflows:use, plus files:read when an input references a staged file.
v2 compatibility notes
Dispatch launches the active published version of an existing workflow, unless a launch byworkflowId names one of its published versions with versionId. The response tells you which version ran.
Choose the workflow
Send exactly one of:name— the workflow’s name, optionally withfactoryIdto scope the lookup to a factory.workflowId— theidfrom List workflows.factoryIdis not accepted withworkflowId.
workflowId only, versionId runs that published version (active or superseded) instead of the active one; read its inputs with getInputSchema and the same versionId. A version that is not the workflow’s answers 404. versionId is not accepted with name.
Sending both, or neither, answers 400 bad_request with Provide exactly one of name or workflowId.
Response
A launch answers200 with the run’s durable identity, in this order:
Send an Idempotency-Key with every launch
Dispatch is a mutating operation, so it accepts anIdempotency-Key header. Send one per logical launch: a retry under the same key never starts a second run. The retry returns the original response, with the same four ids, when the caller still holds workflows:use and runs:read and may currently read the original run at its workflow’s home and companies (see Workflow dispatch replay). Otherwise it answers 403 for a missing permission or 409 idempotency_result_unavailable: the dispatch completed, so reconcile authorized run state rather than dispatching again under a new key. The header is optional, but a launch sent without one has no retry protection. A retry of a dispatch recorded before 2026-09-30 replays that dispatch’s original response, which carries only runId and convexWorkflowId; such a replay stays possible for up to 24 hours after the change.
File inputs
Afile or file[] input takes the fileId of a file you staged with POST /api/v2/files:
- Upload the file and keep the returned
fileId. - Put that
fileIdin the input slot ofruntimeArgs, for example{ "report": "files_7d0c…" }.
runtimeArgs contain any platform file id also needs files:read; without it the answer is 403 with requiredPermission: "files:read". An inline-only launch does not.
You may pass exactly the uploads you could download through GET /api/v2/files/content: the file must be bound to your credential’s org tree (the org unit an upload through the same credential is bound to), and your credential must hold files:read at every company on the file. Isolation is per org tree, not per uploader. Anything else answers 422 with Workflow input "<input>" is not an available file, the same message whether the file does not exist, belongs to another org tree, is only a run output, or sits at a company you cannot read. A raw storage id is refused the same way. A run’s output file cannot be passed straight into another run, even when you may download it: download it and upload it again through POST /api/v2/files.
Errors
Authorizations
Headers
1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.
1 - 255Body
- Option 1
- Option 2
Register a one-shot completion callback. When the run reaches a terminal state Forge sends exactly one signed POST to url carrying the v2 event envelope — workflow.completed for a completed run, workflow.failed otherwise (cancelled included; the exact status is on data.status). Verify it with X-Forge-Signature-V2 against the calling app's callback signing secret. External Application callers only.
Optional. Attribute this run to one of your end customers, so its token spend rolls up under that customer (readable via GET /api/v2/cost/customer).
Ownership-fenced: a customerId that does not exist, or exists but is not linked to the calling application, is rejected with 400 — a caller cannot attribute a run to another tenant's customer. Requires an External-Application credential; a platform-key caller passing customerId also gets 400. Obtain one from POST /api/v2/external/customers/findOrCreate.
Response
Run launched. A same-key retry of a dispatch recorded before the four-field identity (2026-09-30) replays its original { runId, convexWorkflowId } result.

