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.
• Pinned access. When you omit version and your access is pinned to a version, the run executes that version. A creator publishing a newer version does not silently upgrade you.
• Current version. When you omit version and your access is not pinned, the run executes the workflow's current active version.

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.

The public v1 API keeps this key optional for backward compatibility. New integrations should treat it as required for every POST /runs: without a key, an ambiguous network retry can create and charge a second run. Edgaze's own first-party run clients are rejected when they omit their attempt key.

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.

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.

Funding and acceptance behavior#

The table below describes behavior visible to an API client.

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. 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#