Developer questions

HumanLayer is a human decision orchestration API.

It allows a system (AI agent, backend, workflow engine) to:

• submit a decision case
• wait for qualified human validation
• receive a structured response
• with a complete audit trail

👉 For a developer, HumanLayer is an external service you can call, like Stripe, Twilio, or Auth0 — but for human decisions.

When your system reaches a point where:

• a decision carries human accountability
• a rule is no longer sufficient
• a signature or validation is required
• or when you want formal proof of validation

Simple rule:

If you hesitate to automate → call HumanLayer.

Yes.

HumanLayer is designed to:

• be called as a tool
• work in agentic loops
• be used by LLMs under control

Mental model:

if confidence < threshold or risk == "high":
    r = requests.post(API, headers={"x-api-key": KEY}, json=case)
    # then a signed webhook, or GET /api/v1/decisions?id=…

Asynchronous.

You create a request (POST /api/v1/decisions): the response is immediate (request_id, status, sla_minutes, expires_at) and your workflow continues. The decision then reaches you by signed webhook; you can also fetch it via GET /api/v1/decisions?id=…

No blocking mode: the shortest SLA is 30 min (compliance level).

Each request's deadline is stated as soon as it is created (sla_minutes, expires_at).

A decision is a structured object, with:

• a type (request_type: compliance, judgment or signature)
• a level (level: 1, 2 or 3)
• the context provided by the agent (summary, context_json)
• a status (pending, assigned, decided, sla_breached) and the latest decision (verdict: approved, rejected or escalated)
• the Sentinel’s justification (reasoning)
• an Ed25519 signature (signature, signed_payload, key_id) and timestamps

👉 This is not free text. It's an artifact a system can use.

Only:

• the summary and context your agent sent: it is up to you to include only what is needed
• the AI-prepared elements
• the required fields to decide

No global system access, no unnecessary data.

👉 Minimization by design.

Not at this time. Requests go to HumanLayer’s Sentinel network, by domain and jurisdiction; reserving Sentinels for your organization is not available today.

HumanLayer remains:

• the orchestration layer
• the source of truth
• the audit proof

Past the SLA, a signed sla.breached webhook is sent (once) and the request is automatically reassigned to another qualified Sentinel, up to three times. No decision is ever made by default, and nothing is configurable apart from a longer SLA (sla_minutes).

Since the API is asynchronous, your code never waits: your agent decides what to do while no decision has been rendered.

Yes, always. Every final decision is binary: approved or rejected, with a mandatory written justification (at least 10 characters), and signed. The Sentinel can also escalate the request to another Sentinel. Conditional decisions, custom response fields and thresholds are not available: state your criteria in summary or context_json.

HumanLayer does not allow ambiguous decisions.

Yes. Send a new request with second_opinion_of (the decided request’s ID): another Sentinel, who never handled the case and does not see the first verdict, renders their own signed decision. One second opinion per request, billed as a new decision at the same level. The assigned Sentinel can also escalate the case on their own. Multi-signature validation and quorum are not available.

No. Never.

HumanLayer:

• does not generate decisions
• does not modify the human response
• does not "correct" the Sentinel

It orchestrates, structures, and logs.

• API key authentication (x-api-key header), stored only as a SHA-256 hash
• Decision levels allowed by each key’s plan
• Organization isolation
• Access logs
• Encryption in transit (HTTPS required, webhooks included); two-factor secrets encrypted (AES-256-GCM); API keys and passwords stored as hashes

A Sentinel can only access the cases assigned to them and those they already decided or escalated.

You can extract:

• a JSON export of your signed decisions from the client portal (5,000 most recent requests, latest decision of each)
• the justifications
• the timestamps
• the Sentinel’s pseudonymous reference (S-XXXXXX); the real identity stays with HumanLayer

👉 No need to reconstruct from application logs.

A classic workflow:

• does not verify qualifications
• does not assign accountability
• does not provide enforceable proof
• is not designed for AI

HumanLayer treats a decision as a binding act, not a click.

Yes — where it's intentional.

HumanLayer is called:

• only at critical points
• when slowing down is preferable to taking a risk

Everywhere else, your system remains fully automated.

Because you would need to build:

• an assignment system
• human governance
• audit-grade traceability
• decision SLAs
• an API designed to be called by agents

👉 HumanLayer saves you months, even years.