Skip to main content
POST
Dispatch a workflow run
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

Dispatch launches the active published version of an existing workflow, unless a launch by workflowId 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 with factoryId to scope the lookup to a factory.
  • workflowId — the id from List workflows. factoryId is not accepted with workflowId.
With 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 answers 200 with the run’s durable identity, in this order:

Send an Idempotency-Key with every launch

Dispatch is a mutating operation, so it accepts an Idempotency-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

A file or file[] input takes the fileId of a file you staged with POST /api/v2/files:
  1. Upload the file and keep the returned fileId.
  2. Put that fileId in the input slot of runtimeArgs, for example { "report": "files_7d0c…" }.
A launch whose 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

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

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.

Required string length: 1 - 255

Body

application/json
name
string
required

Kebab-case workflow name to dispatch. Provide exactly one of name or workflowId.

Minimum string length: 1
factoryId
string

Optional factory scope for a launch by name; not accepted with workflowId.

Minimum string length: 1
workflowId
string

Workflow id from GET /api/v2/workflows/list. Provide exactly one of name or workflowId.

Minimum string length: 1
versionId
string

Optional, with workflowId only: run this published version (active or superseded) instead of the active one. A version that is not the workflow's answers 404.

Minimum string length: 1
runtimeArgs
object

Workflow input arguments matching the workflow's input contract. A file or file[] input takes fileId values from POST /api/v2/files.

callback
object

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.

customerId
string

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.

data
object
required

The durable identity of a launched run: the run, its engine instance, the workflow and the exact version launched. versionId is null only when no version is reported.

meta
object
required