Calling workflows through the API
Use the public API when an application needs to start a workflow and consume its result. A module can use a workflow as a backend function; an external service can call the same interface.
Prepare the workflow and key
Define named Input nodes for the values your caller will send, and Set Output nodes for the values it should receive. Ensure the output nodes are on an event path that actually executes.
Create a project API key with permission to run the target workflow (workflows.run). If your application will poll queued runs, it also needs permission to read that workflow (workflows.read). Restrict access to the resources it needs; see API permissions.
Send the raw project key in the Authorization header, without a Bearer prefix. Keep it in trusted server-side code or environment configuration, not in browser JavaScript or a public repository. See Using project services from modules for module-specific guidance.
Wait for a result
Send a JSON request to:
POST {API_BASE}/projects/{projectId}/workflows/{workflowId}/runsync
API_BASE is the public API base URL for your environment, including its public API path. Use the same base as your other project API calls.
For example, a workflow with an Input named message can receive:
{
"inputs": {
"message": "Hello from my application"
}
}
The normal entry event is run, which triggers Start. For a workflow deliberately built around a named Event node, supply the corresponding runEvent in the request. A custom entry event needs its own matching graph path; it is not automatically the same as the Start path.
Successful results contain the workflow's named outputs under result.outputs. A workflow that returns greeting might produce:
{
"success": true,
"statusCode": 200,
"result": {
"outputs": {
"greeting": "Hello from my application"
}
}
}
Check both the HTTP response and the JSON success field. A workflow failure can be returned in a response with HTTP status 200; the response body carries the execution outcome. Do not treat receipt of a response as proof that the business action succeeded.
Queue work and retrieve it later
For work that should not hold a request open, use:
POST {API_BASE}/projects/{projectId}/workflows/{workflowId}/run
Send the same input shape. The response supplies an invocationId; save it and poll:
GET {API_BASE}/projects/{projectId}/workflows/{workflowId}/run/{invocationId}
Queue acceptance is not completion. Check the returned state, such as waiting, active, completed, or failed. A completed invocation's output contains the workflow result envelope, including its success flag and named outputs. Inspect that envelope too. A failed queue execution may include failedReason.
Use a reasonable polling interval and collect the result promptly: invocation status is retained temporarily, not as a permanent application record. Persist important business results in your own database or project storage.
Test the integration
Send a small known input, inspect the response, and check the workflow's Logs → API view. API runs do not populate the editor's stored node outputs, so use their responses and logs to inspect them.
Allow for authentication errors, missing permissions, execution limits, timeouts, and workflow failures. Be careful with retries after an uncertain outcome: a lost response does not necessarily mean the workflow did not run. Make actions such as creating records or sending notifications safe to repeat where possible.
Detailed endpoint references: run synchronously, queue a run, and read run status.