API HumanLayer v1

Authentification

Chaque requête inclut votre clé d’API dans l’en-tête x-api-key.

x-api-key: hl_live_…

• Créez et révoquez vos clés dans l’espace client (jusqu’à 5 clés actives).
• La clé complète n’est affichée qu’une fois : HumanLayer n’en conserve que l’empreinte SHA-256.
• Chaque clé reçoit un secret de signature des webhooks (whsec_…), lui aussi affiché à la création.

Niveaux, SLA et tarifs

Le champ request_type fixe le niveau de décision, donc le SLA et le prix. Votre forfait détermine les niveaux accessibles et le quota quotidien.

Le délai court dès la soumission. Vous pouvez demander un délai plus long avec sla_minutes, jamais plus court que l’engagement du niveau (7 jours au plus).

Cycle d’une demande

1. L’agent soumet la demande : POST /api/v1/decisions.
2. HumanLayer la route vers un Sentinel actif du bon domaine (et de la bonne juridiction), dont la double authentification est configurée, en privilégiant le moins chargé.
3. Le Sentinel tranche (approved ou rejected, justification obligatoire) ou escalade pour un second avis : la demande passe alors à un autre Sentinel.
4. La décision est signée (Ed25519) et vous est livrée par webhook ; elle reste consultable via GET /api/v1/decisions?id=….
5. Si le SLA est dépassé, vous recevez sla.breached et la demande est réassignée automatiquement (trois escalades au plus). Le contrôle tourne toutes les 5 minutes.
6. Une fois la demande tranchée, vous pouvez demander un second avis : un autre Sentinel reprend le dossier sans connaître le premier verdict.

Soumettre une demande

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

Suivre une demande

{
  "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": "Conforme à la politique interne du client.",
    "decision": {
      "id": "d41c…",
      "verdict": "approved",
      "signed_at": "2026-03-12T14:48:31.000Z",
      "signature": "base64…",
      "signed_payload": "{\"decision_id\":…}",
      "key_id": "3f9a…"
    }
  }
}

Historique d’un agent

Demander un second avis

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

Clé de vérification

Webhooks signés

Si vous fournissez callback_url, HumanLayer y envoie un POST JSON à chaque événement :

En-têtes : X-HumanLayer-Event, X-HumanLayer-Delivery et X-HumanLayer-Signature: t=<horodatage>,v1=<hmac>, où v1 est le HMAC-SHA256 hexadécimal de t + "." + corps brut avec le secret whsec_… de votre clé. Chaque événement est livré une fois (délai de 5 s) ; en cas d’échec, l’état reste consultable par l’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  # trop ancien : rejeu possible
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Vérifier une décision

Chaque décision est signée en Ed25519 sur le champ signed_payload (JSON canonique : identifiants, verdict, empreinte SHA-256 de la justification, pseudonyme du Sentinel, horodatage, key_id). Toute modification ultérieure invalide la 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')
);
// Vérifiez aussi que sha256(reasoning) === JSON.parse(signed_payload).reasoning_sha256

Statuts

Une escalade (escalated) n’est pas un statut final : la demande repasse à assigned auprès d’un autre Sentinel, et escalation_count augmente.

Erreurs et limites

Les erreurs renvoient { "error": "message", "code": "…" }.

Exemple complet

import time, requests

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

# 1. Seuil Arbitrium franchi : on soumet le dossier
created = requests.post(API, headers=HEADERS, json={
    "agent_id": "agent-credit",
    "request_type": "compliance",
    "domain": "finance",
    "summary": "KYC : correspondance partielle sur une liste de sanctions. Valider ?",
    "context_json": {"customer_id": "c_4521", "match_score": 0.71},
    "callback_url": "https://votre-app.example/webhooks/humanlayer",
}).json()

# 2. Sans webhook : sondage espacé jusqu'à la décision
while True:
    req = requests.get(API, headers=HEADERS, params={"id": created["request_id"]}).json()["request"]
    if req["status"] == "decided":
        break
    time.sleep(15)

# 3. L'agent reprend son workflow, décision signée à l'appui
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":"La clause §4.2.b est-elle acceptable ?"}'