Developer documentation

The callable human API.

hitl.ph exposes a managed human workforce as a simple REST API and CLI. Send a task, a person owns it end to end, and a structured result comes back. This is the intended integration shape during early access — request a key to get the current reference and your credentials.

Early access · API shape may evolve · request a key to start

Authentication

Every request is authenticated with an API key sent as a bearer token. Keys are issued during onboarding — there is no self-serve signup yet.

Authorization: Bearer $HITL_API_KEY

Base URL · https://api.hitl.ph/v1

Create a task

POST /tasks with the task type, a plain-language brief, any context the person needs, and how you want the result returned (webhook or poll).

curl https://api.hitl.ph/v1/tasks \
  -H "Authorization: Bearer $HITL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "document.review",
    "brief": "Does clause 7 of this contract waive liability? Yes/no + the reason.",
    "context": { "url": "https://files.example.com/contract-1042.pdf" },
    "return": { "mode": "webhook", "url": "https://your-app.com/hooks/hitl" }
  }'

Request

{
  "id": "task_8sJ2k0Lm",
  "type": "document.review",
  "status": "routing",
  "created_at": "2026-06-14T02:11:09Z"
}

Response · the task is now routing to the floor

Task types

The type field accepts five values, each a different kind of human work:

task.type	What a human does
`document.review`	A trained person reads and decides on something a model should not sign off alone.
`voice.call`	Confirm a booking, chase a supplier, verify a detail — the jobs that still need a voice.
`data.validate`	Resolve the records and judgement calls that models guess at and get wrong.
`world.capture`	Confirm something physically exists or eyeball a real-world state and report back.
`decision.own`	An accountable human makes, signs and stands behind the decision — not a confidence score.

See use cases for worked examples of each.

Retrieve a result

Poll GET /tasks/{id} until status is completed, or skip polling entirely and take the result on a webhook. The result is structured data your agent can act on directly.

{
  "id": "task_8sJ2k0Lm",
  "type": "document.review",
  "status": "completed",
  "result": {
    "answer": "No — clause 7 limits liability but does not waive it.",
    "reasoning": "It caps damages at fees paid in the prior 12 months …",
    "owner": "Maria R."
  },
  "completed_at": "2026-06-14T02:15:21Z"
}

GET /tasks/task_8sJ2k0Lm

Webhooks

Set return.mode to webhook and we POST the completed task to your URL the moment the human finishes — no polling loop required. Verify the signature header, respond 200, and continue your agent run.

The hitl CLI

The CLI wraps the same API for scripts and local testing. Authenticate once, then create tasks from the terminal.

# install once, authenticate with your key
hitl auth login

# send a task and block until the human returns a result
hitl tasks create \
  --type voice.call \
  --brief "Confirm the 3pm Friday booking for table of 6 under 'Carter'."

Task statuses

status	Meaning
`routing`	Received and being assigned to a specialist on the floor.
`in_progress`	A named human owns the task and is working on it.
`completed`	Done — the structured result is available.
`needs_input`	The specialist needs a clarification before they can finish.
`failed`	The task could not be completed; the reason is returned.

Integration summary: REST API (POST /tasks, GET /tasks/{id}) and a `hitl` CLI, with API-key auth and optional return webhooks.

Get a key.

hitl.ph is onboarding its first agencies now. Request access and the team will send you credentials and the current API reference.

New to the idea? Start with what human in the loop means.