Create Run

Overview#

This is the primary execution endpoint. It accepts a workflow id and an inputs object, validates required inputs, entitlement, and spend caps synchronously, then returns 202 Accepted with a run id and URLs for polling.

Runs are asynchronous. A successful response means the request was accepted, not that the run finished. Always follow statusUrl until the run reaches a terminal state, then read outputs from the same response or from GET /runs/{id}/events for step-level progress.

Build inputs from the selected workflow's current inputSchema; there is no universal field such as topic. Every key must match either one published nodeId or its exact input name. Unknown keys are rejected so spelling mistakes cannot be silently ignored. Send an Idempotency-Key header and reuse it when retrying the same logical POST so a network retry does not create another billable run.

You may use a field's nodeId or name alias. Do not send both with different values: conflicting aliases return 400 invalid_inputs. Sending both is accepted only when their values are identical. When two published fields share a name, that name is ambiguous and you must use their node IDs.

Authorization#

Requires run:execute.

Parameters#

Version resolution#

POST /runs pins each run to one immutable workflow version. The same workflow id can therefore execute different graphs for different callers, and the resolution rules are as follows:

• Explicit pin. When you set version in the request body to an immutable version id you are entitled to, the run executes that exact graph. Owners can select any version in the workflow's history; buyers can select the version their purchase pin already covers.
• Purchase pin. When you omit version and hold a purchase row whose workflow_version_id is non-null, the run executes that pinned version. A creator publishing a newer version does not silently upgrade you.
• Follow active. When you omit version and your purchase pin is null (or you have no purchase row), the run executes the workflow's current active_version_id. Callers who fall in this path float with each publish.

Cache pinnedVersionId, activeVersionId, and updateAvailable from GET /workflows/{id} to reason about drift. When updateAvailable flips to true, review the new version before the next run: input shapes and output shapes can change between versions.

Sending an unknown or forbidden version returns 403 forbidden. The public API never reveals whether an unknown version id belongs to another workflow.

Idempotency#

Use the Idempotency-Key HTTP header. The compatibility field idempotencyKey in the JSON body is also accepted. If both are present they must be identical after surrounding whitespace is removed; otherwise the request returns 400 invalid_request. Header names are case-insensitive under HTTP, while key values are case-sensitive.

Keys may contain any non-empty string up to 255 characters. Uniqueness is scoped to the Edgaze account behind the API key, not to one API key or workflow. Records have no time-based expiry in the current implementation; a key remains reserved while its run record exists.

The request fingerprint covers the workflow, normalized inputs, and requested version. Reusing a key with the same request returns 202 and the original run URLs without creating or charging another run. Reusing it with a different request returns 409 idempotency_conflict. A failed or cancelled run is still the original result for that key. To intentionally retry execution as a new run, use a new key.

Canonical funding and acceptance behavior#

This table is the source of truth for REST run creation. Other billing pages link here instead of redefining the POST /runs timing.

File inputs#

POST /runs accepts JSON, not multipart form data. For an input whose schema type is file, send a JSON-safe WorkflowMedia object under that input's nodeId:

{
  "__workflowMedia": true,
  "kind": "image",
  "url": "https://example.com/input.png",
  "mimeType": "image/png",
  "filename": "input.png"
}

Use an HTTPS URL your workflow can retrieve, or replace url with a raw base64 field. Never put an API key or authorization token in the media URL.

Response#

Only POST /runs is rate-limited (60 req/min per key). Invalid JSON returns 400 invalid_json. Missing workflow returns 400 missing_workflow. Missing, unknown, conflicting, or incorrectly typed workflow inputs return 400 invalid_inputs before a run or billing reservation is created. Reusing an idempotency key with a different workflow, normalized inputs, or requested version returns 409 idempotency_conflict.

Example payloads are in the request/response panel above.

Edge cases#