HumanLayer API v1

Authentication

Every request includes your API key in the x-api-key header.

x-api-key: hl_live_…

• Create and revoke keys in the client portal (up to 5 active keys).
• The full key is shown only once: HumanLayer stores only its SHA-256 fingerprint.
• Each key comes with a webhook signing secret (whsec_…), also shown at creation.

Levels, SLAs and pricing

The request_type field sets the decision level, and therefore the SLA and the price. Your plan sets which levels you can use and your daily quota.

The clock starts at submission. You may ask for a longer delay with sla_minutes, never shorter than the level’s commitment (7 days at most).

Request lifecycle

1. The agent submits the request: POST /api/v1/decisions.
2. HumanLayer routes it to an active Sentinel in the right domain (and jurisdiction) with two-factor authentication configured, least busy first.
3. The Sentinel decides (approved or rejected, justification required) or escalates for a second opinion: the request then moves to another Sentinel.
4. The decision is signed (Ed25519) and delivered by webhook; it remains available through GET /api/v1/decisions?id=….
5. If the SLA is exceeded, you receive sla.breached and the request is reassigned automatically (up to three escalations). The check runs every 5 minutes.
6. Once the request is decided, you can ask for a second opinion: another Sentinel takes the case without knowing the first verdict.

Submit a request

{
  "ok": true,
  "request_id": "8b1f2c4e-…",
  "status": "assigned",
  "level": 1,
  "sla_minutes": 30,
  "expires_at": "2026-03-12T15:02:07.000Z",
  "sentinel_ref": "S-4F2A9C"
}

Track a request

{
  "request": {
    "id": "8b1f2c4e-…",
    "status": "decided",
    "level": 1,
    "priority": "normal",
    "sentinel_ref": "S-4F2A9C",
    "expires_at": "2026-03-12T15:02:07.000Z",
    "escalation_count": 0,
    "verdict": "approved",
    "reasoning": "Compliant with the client’s internal policy.",
    "decision": {
      "id": "d41c…",
      "verdict": "approved",
      "signed_at": "2026-03-12T14:48:31.000Z",
      "signature": "base64…",
      "signed_payload": "{\"decision_id\":…}",
      "key_id": "3f9a…"
    }
  }
}

Agent history

Request a second opinion

{
  "ok": true,
  "request_id": "c7d05e91-…",
  "status": "assigned",
  "level": 2,
  "sla_minutes": 120,
  "sentinel_ref": "S-9B31D0",
  "second_opinion_of": "8b1f2c4e-…"
}

Verification key

Signed webhooks

If you provide callback_url, HumanLayer sends a JSON POST for each event:

Headers: X-HumanLayer-Event, X-HumanLayer-Delivery and X-HumanLayer-Signature: t=<timestamp>,v1=<hmac>, where v1 is the hex HMAC-SHA256 of t + "." + raw body with your key’s whsec_… secret. Each event is delivered once (5 s timeout); if delivery fails, the state stays available through the API (webhook_status).

import hmac, hashlib, time

def verify_webhook(headers, raw_body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in headers["X-HumanLayer-Signature"].split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False  # too old: possible replay
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Verify a decision

Every decision is signed with Ed25519 over the signed_payload field (canonical JSON: identifiers, verdict, SHA-256 fingerprint of the justification, Sentinel pseudonym, timestamp, key_id). Any later change invalidates the signature.

import crypto from 'node:crypto';

const key = await (await fetch('https://humanlayer.systems/api/v1/decision-key')).json();
const ok = crypto.verify(
  null,
  Buffer.from(decision.signed_payload),
  key.public_key_pem,
  Buffer.from(decision.signature, 'base64')
);
// Also check that sha256(reasoning) === JSON.parse(signed_payload).reasoning_sha256

Statuses

An escalation (escalated) is not final: the request returns to assigned with another Sentinel, and escalation_count increases.

Errors and limits

Errors return { "error": "message", "code": "…" }.

Full example

import time, requests

API = "https://humanlayer.systems/api/v1/decisions"
HEADERS = {"x-api-key": "hl_live_…"}

# 1. Arbitrium threshold crossed: submit the case
created = requests.post(API, headers=HEADERS, json={
    "agent_id": "agent-credit",
    "request_type": "compliance",
    "domain": "finance",
    "summary": "KYC: partial match on a sanctions list. Validate?",
    "context_json": {"customer_id": "c_4521", "match_score": 0.71},
    "callback_url": "https://your-app.example/webhooks/humanlayer",
}).json()

# 2. Without a webhook: poll, spaced out, until decided
while True:
    req = requests.get(API, headers=HEADERS, params={"id": created["request_id"]}).json()["request"]
    if req["status"] == "decided":
        break
    time.sleep(15)

# 3. The agent resumes its workflow, backed by a signed decision
if req["verdict"] == "approved":
    continue_workflow(req["decision"])

curl -X POST https://humanlayer.systems/api/v1/decisions \
  -H "x-api-key: hl_live_…" \
  -H "content-type: application/json" \
  -d '{"agent_id":"agent-legal","request_type":"judgment","domain":"legal","summary":"Is clause §4.2.b acceptable?"}'