Skip to main content

Workflows overview

Use the workflow API to call your project's reusable logic from a module, backend, or external integration. Your caller supplies inputs; the workflow performs its configured actions and returns named outputs.

Prepare a callable workflow​

  1. Define Input nodes for the values your application will send.
  2. Connect the actions that should execute from Start, or from a deliberately configured named Event.
  3. Use Set Output nodes to return values. They must be on an event path that actually executes.
  4. Test the workflow with a small, known input before connecting it to production callers.

For example, a workflow with an Input named name and an output named greeting could accept {"inputs":{"name":"Ada"}} and return {"greeting":"Hello Ada"} within its result. These names are defined by your workflow, not built-in API fields.

See Calling workflows through the API for workflow preparation.

Choose how to run it​

ApproachResponseBest suited to
Run synchronouslyHolds the request open and returns the workflow result.Work that fits comfortably within your caller's HTTP timeout.
Queue a runReturns an invocationId; use Get run status to retrieve the result.Longer or variable-duration work and callers that should not keep a connection open.

Both start real workflow executions and accept the same input structure. Queue acceptance is not completion, and neither approach makes repeated submissions safe by itself.

Authenticate and select the workflow​

Use a project API key in the Authorization header without a Bearer prefix. The key needs:

  • workflows.run on the target workflow to execute it.
  • workflows.read on the target workflow to retrieve queued-run status or include it in List workflows.

Grant access to individual workflows where possible. Run permission allows the workflow's configured actions to execute; the key does not need separate API permissions for each service the workflow uses internally.

Use the project and workflow IDs from the app URL, rather than their display names. Endpoint examples assume the environment variables from the Quickstart, including a base URL ending in /api/publicv1.

Inputs, events, and outputs​

Send a JSON object with optional inputs and runEvent fields. Input keys match the workflow's named Input nodes. Omit inputs when none are needed.

The default runEvent is "run", which triggers Start. Supply a custom name only when the workflow has a matching Event entry point. A custom event does not automatically execute the Start path.

Synchronous results expose named outputs at result.outputs. Completed queued runs expose the same result envelope under output, so named outputs are at output.result.outputs.

Always inspect the workflow result's success flag. HTTP 200 can carry a workflow failure, and a queued run with state: "completed" can contain output.success: false.

Observe and retain results​

Open Logs → API on the workflow to inspect API-triggered executions. These runs do not populate the editor's stored node outputs.

Queued-run status and output are retained temporarily. Poll while the work is running, collect the result promptly, and persist important outcomes in your application or project storage.

A timeout or lost response does not prove that a workflow did not run. Avoid blindly resubmitting actions that could create duplicate records or notifications. See Errors, limits and retries.

Endpoints​