[Home](/) / Docs

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](#auth) [Create a task](#create) [Task types](#types) [Retrieve a result](#retrieve) [Webhooks](#webhooks) [CLI](#cli) [Statuses](#status)

## 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](/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](/human-in-the-loop/).

***

Source: https://www.hitl.ph/docs/
This is the markdown representation of that page, served to clients that send `Accept: text/markdown`.
Machine-readable index: https://www.hitl.ph/llms.txt · Knowledge bundle: https://www.hitl.ph/okf/index.md