Skip to main content

Queue a workflow run

POST /projects/:projectid/workflows/:workflowid/run

Queues a workflow execution and returns an invocation ID without waiting for the workflow result. Use Get run status to follow it to completion.

Authentication and permissions​

Send the complete project key in Authorization, without Bearer. Starting the run requires workflows.run on the target workflow. If the same caller will poll the result, also grant workflows.read on that workflow.

Request​

Replace :projectid and :workflowid with the project and workflow IDs. Send Content-Type: application/json.

FieldTypeRequiredBehaviour
inputsObjectNoValues keyed by the workflow's Input names. Defaults to null when omitted.
runEventStringNoDefaults to "run" for Start. Use a custom name only for a matching Event entry point.

Use {} as the body when no inputs or custom event are needed. This example uses the Quickstart environment variables and a workflow that accepts name:

export INTELLECTIBLE_WORKFLOW_ID="YOUR_WORKFLOW_ID"

curl --include --request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--header "Content-Type: application/json" \
--data '{"inputs":{"name":"Ada"}}' \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/workflows/${INTELLECTIBLE_WORKFLOW_ID}/run"

This starts real work. Check the workflow's actions before calling it.

Accepted response​

200 OK returns an acceptance response, not the workflow's outputs. The fields your application needs are:

{
"success": true,
"invocationId": "example-invocation-id"
}

This example shows the relevant fields only. The response also includes runtimeDataRootPath, which is runtime bookkeeping; use invocationId, not that path, to retrieve status.

Save the invocation ID together with its project and workflow IDs. Then call:

GET /projects/:projectid/workflows/:workflowid/run/:invocationId

Do not submit another POST simply because the workflow has not finished yet.

Errors and retry safety​

  • 401: missing or invalid project credential.
  • 403: no run permission on the workflow.
  • 429: request-rate, workflow-start, or concurrent-run limits prevented admission. The response may be plain text or JSON with success: false, error, and message.
  • Other failures may occur before a usable invocation ID is returned. Inspect the HTTP status and body.

A lost response leaves the outcome uncertain: the run may already have been accepted. The endpoint does not deduplicate repeated requests or support an idempotency key. Make important workflow actions safe to repeat, or reconcile the original operation before resubmitting it.

Retrieve and keep the result​

Poll Get run status at a measured interval. Queue acceptance does not establish that the workflow is valid or that its actions succeeded.

Status is retained temporarily. Collect results promptly and store important business outputs outside the status endpoint. See Errors, limits and retries for polling and timeout guidance.