Skip to main content
Three calls cover most integrations: find the input a workflow reads, start a run, and read the run until it has finished. Base URL https://api.hitl.sh/v1, with your API key as a Bearer token.
1

See what the workflow reads

fields lists each {{trigger.body.<path>}} its steps use: amount, currency, customer.email, customer.name, order_id, reason. List your workflows and their ids with GET /api/workflows.
2

Start a run

202 Accepted with the execution. A draft or paused workflow answers 409.
3

Wait for the answer

?wait=60 holds each call until the run finishes or a minute passes.

Instead of polling

  • Pass "callback_url": "https://your.app/hitl" when you start the run and HITL POSTs the finished run there, signed.
  • Or subscribe to execution.finished for a workflow, to hear about every run however it started.
Both are explained, with signature verification code, in Webhooks.

TypeScript client

@hitl-sh/core is the typed client the CLI and MCP server are built on.

Errors and limits

Every answer is {"error": false, "msg": "...", "data": ...} or {"error": true, "msg": "..."}. See Errors. Runs take up to 64 KB of input, and /workflows and /executions allow 1,000 requests an hour per key.