Runtime API

Overview#

The runtime API lets external applications invoke deployed blueprints without console access. Authenticate with a bearer API key (Authorization: Bearer ... or x-api-key header).

Base path: /api/runtime

Scopes#

Scope	Access
runtime	Limited to an explicit set of blueprint IDs configured on the key
runtime-all	Every deployed blueprint

Issue keys in API Keys with the appropriate scope.

Endpoints#

Method	Path	Description
GET	/workflows	List accessible workflows
GET	/workflows/:workflowId	Workflow detail
GET	/workflows/:workflowId/versions	Version history
GET	/workflows/:workflowId/runs	List runs (paginated)
GET	/workflows/:workflowId/runs/:runId	Run detail + pending human request
POST	/workflows/:workflowId/runs	Start execution → 202 Accepted
POST	/workflows/:workflowId/runs/:runId/respond	Submit human-in-the-loop answer

Starting a run#

curl -X POST "https://your-instance.example.com/api/runtime/workflows/$WORKFLOW_ID/runs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Summarize the attached report"}],
    "actorId": "external-user-123",
    "overrides": {}
  }'

Response (202):

{
  "runId": "...",
  "workflowId": "...",
  "versionId": "...",
  "status": "running",
  "message": "Workflow execution started. Poll GET .../runs/:runId for status."
}

Execution runs asynchronously — poll the run endpoint until status is terminal or phase is waiting_human.

Human responses#

When pendingHumanRequest is present, collect answers from your user and POST to /respond:

{
  "requestId": "...",
  "response": { "answers": [...] },
  "respondedByUserId": "optional-external-id"
}

Requirements#

• Workflow must have a deployed version (deployedVersionId set, version status deployed)
• API key user must have provider access for the workflow’s cloud provider
• For runtime scope, workflow ID must be in the key’s allow list

Related#

• API Keys
• Human-in-the-loop