HumanLayer — Documentation API Développeurs

Authentification

Toutes les requêtes agent doivent inclure votre clé API dans le header x-api-key.

                        Header
                    
                        x-api-key: hl_votre_clé_api

💡 Comment obtenir votre clé Contactez l'équipe HumanLayer à humanlayer@in6.ai pour recevoir vos identifiants API.

Base URL : https://humanlayer.systems/.netlify/functions

Flux de décision

Le cycle de vie complet d'une demande de décision :

🤖

Agent IA

Soumet la demande

→

⚡

API HumanLayer

Route vers un Sentinel

→

👤

Sentinel

Examine et décide

→

✓

Décision

Verdict + reasoning

L'agent soumet une demande de décision via POST /ai-request.
Quand le seuil Arbitrium est atteint, l'API assigne automatiquement un Sentinel qualifié.
Le Sentinel examine le dossier et rend un verdict (approuvé / rejeté / escaladé).
L'agent récupère la décision via GET /ai-request?id=xxx.

Ce que votre système récupère

request_id et état de cycle (pending, assigned, decided)
verdict et reasoning
signed_at pour l'horodatage de décision
un artefact de preuve exploitable en audit

Soumettre une demande

POST /ai-request

Crée une nouvelle demande de décision humaine. L'API tente d'assigner automatiquement un Sentinel qualifié.

Corps de la requête (JSON)

Paramètre	Type	Requis	Description
agent_id	string	requis	Identifiant unique de votre agent
agent_name	string	optionnel	Nom lisible de l'agent (ex: "DevisPresto Agent")
request_type	string	requis	`conformité` \| `jugement` \| `signature` \| `compliance` \| `judgment`
domain	string	requis	Domaine d'expertise : `legal`, `finance`, `compliance`, `medical`, etc.
jurisdiction	string	optionnel	Juridiction applicable (ex: "Québec", "France", "EU")
summary	string	requis	Résumé clair de la demande de décision
context_json	object	optionnel	Contexte structuré (pièces justificatives, données, etc.)
priority	string	optionnel	`normal` (défaut) \| `urgent`
expires_at	ISO 8601	optionnel	Date d'expiration (défaut: 48h)
callback_url	string	optionnel	URL de webhook — recevra un POST avec le verdict dès que le Sentinel décide

Réponse (200)

json

{
                            "ok": true,
                            "request_id": "a1b2c3d4-e5f6-...",
                            "status": "assigned",
                            "assigned_to": "Marie Dupont"
                            }
                        

⚠️ Statut "pending" Si aucun Sentinel qualifié n'est disponible, le statut sera pending au lieu de assigned. La requête reste en file d'attente jusqu'à l'activation d'un Sentinel correspondant.

Vérifier le statut

GET /ai-request?id={request_id}

Poll le statut d'une demande spécifique. Utilisez cette requête en boucle pour attendre la décision du Sentinel.

Réponse (200) — en attente

                            json
                        
{
                            "request": {
                            "id": "a1b2c3d4-...",
                            "status": "assigned",
                            "agent_id": "my-agent",
                            "summary": "Valider ce contrat...",
                            "verdict": null,
                            "reasoning": null
                            }
                            }
                        

Réponse (200) — décidée

                            json
                        
{
                            "request": {
                            "id": "a1b2c3d4-...",
                            "status": "decided",
                            "verdict": "approved",
                            "reasoning": "Le contrat est conforme aux
                                normes Loi 25. Aucune clause problématique identifiée.",
                            "decision_signed_at": "2026-02-14T16:30:00.000Z"
                            }
                            }
                        

Lister les demandes

GET /ai-request?agent_id={agent_id}

Récupère toutes les demandes soumises par un agent, triées par date décroissante (max 100).

Réponse (200)

                            json
                        
{
                            "requests": [
                            { "id": "...", "status": "decided", "verdict": "approved", ... },
                            { "id": "...", "status": "assigned", "verdict": null, ... }
                            ]
                            }
                        

Exemples de code

curl — Soumettre une demande

bash

curl -X POST https://humanlayer.systems/.netlify/functions/ai-request \
                        -H "Content-Type: application/json" \
                        -H "x-api-key: hl_votre_clé" \
                        -d '{
                            "agent_id": "mon-agent",
                            "agent_name": "DevisPresto Agent",
                            "request_type": "conformité",
                            "domain": "legal",
                            "jurisdiction": "Québec",
                            "summary": "Valider la conformité Loi 25 de ce contrat de service",
                            "context_json": {
                            "contract_id": "CTR-2026-0412",
                            "amount": 50000,
                            "parties": ["Acme Corp", "Client XYZ"]
                            },
                            "priority": "normal"
                            }'

curl — Vérifier le statut

bash

curl https://humanlayer.systems/.netlify/functions/ai-request?id=a1b2c3d4-...
                        \
                        -H "x-api-key: hl_votre_clé"

JavaScript / Node.js — Flow complet

javascript

const API = 'https://humanlayer.systems/.netlify/functions';
                        const API_KEY = process.env.HUMANLAYER_API_KEY;

                        // 1. Soumettre une demande
                        async function requestDecision(summary,
                        domain, context) {
                        const res = await fetch(`${API}/ai-request`, {
                        method: 'POST',
                        headers: {
                        'Content-Type': 'application/json',
                        'x-api-key': API_KEY
                        },
                        body: JSON.stringify({
                        agent_id: 'mon-agent',
                        request_type: 'conformité',
                        domain,
                        summary,
                        context_json: context
                        })
                        });
                        return await res.json();
                        }

                        // 2. Attendre la décision (polling)
                        async function waitForDecision(requestId,
                        intervalMs = 15000) {
                        while (true) {
                        const res = await fetch(
                        `${API}/ai-request?id=${requestId}`,
                        { headers: { 'x-api-key': API_KEY } }
                        );
                        const { request } = await res.json();

                        if (request.status === 'decided') {
                        return {
                        verdict: request.verdict,
                        reasoning: request.reasoning
                        };
                        }

                        await new Promise(r => setTimeout(r, intervalMs));
                        }
                        }

                        // 3. Utilisation
                        const { request_id } = await requestDecision(
                        'Valider la conformité de ce contrat',
                        'legal',
                        { contract_id: 'CTR-2026-0412' }
                        );

                        const decision = await waitForDecision(request_id);
                        console.log(decision);
                        // { verdict: "approved", reasoning: "Conforme Loi 25..." }
                    

Python — Flow complet

python

import requests, time, os

                        API = "https://humanlayer.systems/.netlify/functions"
                        HEADERS = {
                        "Content-Type": "application/json",
                        "x-api-key": os.environ["HUMANLAYER_API_KEY"]
                        }

                        # 1. Soumettre une demande
                        resp = requests.post(f"{API}/ai-request",
                        headers=HEADERS, json={
                        "agent_id": "mon-agent-python",
                        "request_type": "conformité",
                        "domain": "legal",
                        "summary": "Valider la conformité de ce
                            contrat",
                        "context_json": {"contract_id": "CTR-2026-0412"}
                        })
                        request_id = resp.json()["request_id"]

                        # 2. Attendre la décision
                        while True:
                        r = requests.get(
                        f"{API}/ai-request",
                        params={"id": request_id},
                        headers=HEADERS
                        )
                        data = r.json()["request"]

                        if data["status"] == "decided":
                        print(f"Verdict: {data['verdict']}")
                        print(f"Reasoning: {data['reasoning']}")
                        break

                        time.sleep(15)
                    

Statuts de requête

Statut	Description
pending	En attente d'assignation — aucun Sentinel qualifié disponible
assigned	Assignée à un Sentinel — en cours d'examen
decided	Verdict rendu — `verdict` et `reasoning` disponibles

Verdicts possibles

approved — La demande est approuvée par le Sentinel
rejected — La demande est rejetée avec justification
escalated — Escaladée pour examen complémentaire

Gestion des erreurs

Code	Signification	Action
`400`	Champs manquants ou type de requête invalide	Vérifiez le corps JSON
`401`	Clé API invalide ou manquante	Vérifiez l'en-tête `x-api-key`
`404`	Requête non trouvée	Vérifiez le `request_id`
`500`	Erreur serveur	Réessayez après quelques secondes

Toutes les erreurs renvoient un JSON avec un champ error :

                        json
                    
{ "error": "Missing fields:
                            agent_id, summary" }

Webhook (callback)

Au lieu de poll en boucle, fournissez un callback_url dans votre requête POST. Dès que le Sentinel rend son verdict, HumanLayer enverra un POST à cette URL :

                        json — webhook payload
                    
{
                        "event": "decision.rendered",
                        "request_id": "a1b2c3d4-...",
                        "verdict": "approved",
                        "reasoning": "Conforme aux normes...",
                        "signed_at": "2026-02-14T16:30:00.000Z",
                        "sentinel_name": "Marie Dupont"
                        }
                    

✓ Recommandé pour la production Le webhook est plus efficace que le polling : réponse instantanée, pas de trafic réseau inutile.

API HumanLayer v1.0

Authentification

Flux de décision

Ce que votre système récupère

Soumettre une demande

Corps de la requête (JSON)

Réponse (200)

Vérifier le statut

Réponse (200) — en attente

Réponse (200) — décidée

Lister les demandes

Réponse (200)

Exemples de code

curl — Soumettre une demande

curl — Vérifier le statut

JavaScript / Node.js — Flow complet

Python — Flow complet

Statuts de requête

Verdicts possibles

Gestion des erreurs

Webhook (callback)