Documentation de l'API

Corps de la demande

{
  "turns": [ {"user": "How do I do X?", "model": "I can help with that."} ],
  "clf_context": "clinical"
}

Corps de la demande

{
  "response_text": "The AI response to analyze",   // absent for user_only turns
  "user_text": "The human message for this turn",  // absent for agent_only turns
  "input_text": "optional - legacy alias for user_text",
  "session_id": "your-session-uuid",   // OR use session_name (one required unless dry_run)
  "session_name": "my-session",        // auto-creates on first call, looked up after
  "turn": 1,
  "dry_run": false,                    // true = stateless analysis, no DB write
  "persist_mode": "safe",              // "safe" (default) = answer after the write | "fast" = answer now, write in background
  "debug_timing": false,               // true = add "_timings_ms" (per-stage wall time of the persisted tail)
  "save_text": "all",                  // "all"|"user"|"agent"|"none" - which sentences to persist
  "encrypt_original": false,           // true = store original encrypted at rest (needs a registered public key)
  "clf_context": "clinical",           // "clinical" (default, C3-v2 / hri) | "agentic" (C3-v3 / abi)
  "group_token": null                  // optional opaque thread token to link this session across sessions (#3360)
}

Au moins un parmi response_text ou user_text doit être fourni - omettre les deux retourne 422. encrypt_original : si true et qu'une clé publique est enregistrée (voir Privacy API / /psa-privacy), l'original stocké est chiffré au repos (enc_user_text/enc_response_text) et lisible uniquement avec la clé privée du client ; sans clé ou en cas d'échec, aucun texte n'est stocké. Indépendant de save_text. Défaut false.

Quelle lentille evalue le tour de l'agent : clf_context. "clinical" (par defaut) evalue le comportement avec C3-v2 et renvoie hri ; "agentic" l'evalue avec C3-v3 et renvoie abi. Rien ne deduit la lentille : le trafic des agents IA est evalue en mode clinique tant que vous n'envoyez pas "agentic" a chaque appel. Les seuils d'arret different : clinical alert jaune/rouge, agentic abi >= 0.50 (0.25-0.49 = reformuler). Seules ces deux valeurs sont acceptees : toute autre renvoie 422. La reponse indique toujours la lentille reellement utilisee dans c3.clf_context, avec c3.lens_fallback lorsque "agentic" a ete demande et que C3-v2 a repondu (confiance inferieure a 0.50), plus un c3.lens_fallback_reason. Ne deduisez pas la lentille de la presence de abi : elle ne distingue pas "clinical demande" de "agentic n'a pas tourne".

Ce que mesure reellement chaque forme de tour. A partir du tour 2, la reponse porte aussi analysis_mode partial et missing_user_context true. Symetriquement, un tour user_only n'a ni bhs ni alerte de posture, car il n'y a pas de tour agent a evaluer.

Réponse

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "turn": 1,
  "turn_type": "full",                 // "full" | "agent_only" | "user_only"
  "c1": { "postures": [0,2,1], "sentences": ["..."], "poi": 0.33, "pe": 0.91, "dpi": 0.07, "mps": 2 },
  "c2": { "postures": [0,0,1], "confidences": [0.91,0.88,0.72], "sd": 0.08 },
  "c3": { "postures": [0,0,0], "hri": 0.0 },
  "c4": { "postures": [1,0,2], "pd": 0.15, "td": 2 },
  "c0": { "postures": [3,1], "confidences": [0.91,0.84], "cpi": 0.8 },
  "bhs": 0.87,
  "alert": "green",
  "incongruence": null,
  "cts": { "cts_composite": 0.99, "cts_level": "critical",   // agent-channel threat-intent (#3143)
           "primary_intent": "exfiltration",
           "cts_head_score": 0.99, "cts_head_available": true,  // 7-class cT encoder head: 1 − P(none)
           "exfiltration": 0.95, "secret_read": 0.02, "credential_theft": 0.01,
           "code_exec": 0.0, "instruction_hijack": 0.0, "tool_enumeration": 0.0 }
}

c1-c4, bhs, alert sont null pour les tours utilisateur-seulement. c0 est null pour les tours agent-seulement.

Exemple curl - avec session

curl -X POST https://splabs.io/api/v2/psa/analyze \
  -H "Authorization: Bearer psa_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "response_text": "Of course, I would be happy to help!",
    "session_name": "my-session",
    "turn": 1
  }'

Exemple curl - exécution sèche (sans session)

curl -X POST https://splabs.io/api/v2/psa/analyze \
  -H "Authorization: Bearer psa_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "response_text": "Of course, I would be happy to help!",
    "dry_run": true
  }'

Exemple Python

import requests

# Normal mode - session required
resp = requests.post(
    "https://splabs.io/api/v2/psa/analyze",
    headers={"Authorization": "Bearer psa_your_key"},
    json={
        "response_text": "Of course, I would be happy to help!",
        "session_name": "my-session",
        "turn": 1,
    }
)
print(resp.json())

# Dry-run - stateless, no session needed
resp = requests.post(
    "https://splabs.io/api/v2/psa/analyze",
    headers={"Authorization": "Bearer psa_your_key"},
    json={
        "response_text": "Of course, I would be happy to help!",
        "dry_run": True,
    }
)
# Response includes "dry_run": true but no session_id or turn
print(resp.json())

Configuration du client MCP

{
  "mcpServers": {
    "psa": {
      "url": "https://splabs.io/mcp",
      "headers": { "Authorization": "Bearer psa_your_key" }
    }
  }
}

Appeler un outil directement (JSON-RPC)

curl -X POST https://splabs.io/mcp \
  -H "Authorization: Bearer psa_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "psa_analyze_turn",
      "arguments": { "response_text": "Of course, I would be happy to help!" }
    }
  }'

Paramètres de requête

Paramètres de requête

Réponse

{
  "items": [
    {
      "id": "uuid",
      "amount": 2900,
      "currency": "usd",
      "status": "succeeded",
      "plan": "pro",
      "description": "Subscription payment - pro",
      "created_at": "2026-04-01T10:22:00+00:00"
    }
  ],
  "total": 6,
  "page": 1,
  "per_page": 10,
  "pages": 1
}

amount est en cents (ex. 2900 = 29,00 $). valeurs de status : succeeded | failed.

Corps de la demande

{ "plan": "pro" }

Matrice de comportement

Réponses

// New checkout
{ "url": "https://checkout.stripe.com/..." }

// Same plan - portal
{ "url": "https://billing.stripe.com/...", "action": "portal" }

// Upgrade (no redirect needed)
{ "action": "upgraded", "plan": "enterprise" }

// Downgrade blocked (HTTP 403)
{ "detail": "Cannot downgrade while subscription is active. Your current plan is valid until 1 May 2026. Cancel first if you wish to switch to a lower plan." }

Corps de la demande

{
  "query": "What is the Behavioral Health Score?",
  "top_k": 3,
  "max_per_source": 3
}

Réponse

{
  "answer": "Behavioral Health Score (BHS): the behavioral health of one response, low = stressed...",
  "confidence": 0.91,
  "sources": [
    {"id": "ind_001", "source": "psa_platform", "content": "BHS measures...", "similarity": 0.91}
  ],
  "routing": "auto"
}

Seuils de routage

Erreurs

• 422 - la requête est vide
• 503 - pgvector non disponible ou service d'intégration hors ligne

Corps de la demande

{
  "entries": [
    {"source": "issue-3681", "title": "Optional title", "content": "Entry text (≥ 10 chars)", "confidence_floor": 0.75}
  ]
}

Réponse

{"inserted": 1, "skipped": 0, "skipped_indices": []}

Erreurs

• 403 - non administrateur
• 503 - service d'intégration indisponible

Paramètres de requête

Réponse

{"deleted": 1, "source": null, "entry_id": "289da1dc-c896-40e5-9dbc-efa1d19c8af1"}

Erreurs

• 422: entry_id n'est pas un UUID valide
• 403 - non administrateur
• 503: base de données indisponible

Corps de la requête

{
  "messages": [
    {"role": "user", "content": "My plan is to put all my savings in one coin. Smart, right?"},
    {"role": "assistant", "content": "Absolutely, that is a brilliant plan."}
  ]
}

Réponse

{
  "engine": "reader-v2-qwen3-1.7b",
  "readings": {
    "c0": {"score": 0.21, "logit": -1.32, "read_on": "user"},
    "c1": {"score": 0.64, "logit": 0.58, "read_on": "reply"},
    "c2": {"score": 0.97, "logit": 3.48, "read_on": "request+reply", "level": "alert"},
    "c3": {"score": 0.33, "logit": -0.71, "read_on": "request+reply"},
    "c4": {"score": 0.58, "logit": 0.32, "read_on": "reply"},
    "ca": {"score": 0.08, "logit": -2.44, "read_on": "reply"},
    "theme": {"score": 0.12, "logit": -1.99, "read_on": "user"},
    "block": {"score": 0.04, "logit": -3.18, "read_on": "user"}
  },
  "calibrated": false,
  "levels": {"alert": "fires on at most 1 in 100 ordinary real conversations",
             "watch": "fires on at most 5 in 100 ordinary real conversations"}
}

Chaque score classe les textes : plus haut signifie davantage de la lecture. Ce n'est pas une probabilité calibrée. Chaque lecture porte aussi un level : alert au-dessus du point où elle se déclenche au plus 1 fois sur 100 conversations réelles ordinaires, watch au-dessus du point 5 sur 100, none en dessous. Les deux points ont été fixés sur 2 300 conversations réelles et vérifiés sur 2 271 autres.

Erreurs

• 422 : messages invalides, ou rien à lire
• 503 : le lecteur ne peut pas se charger sur cet hôte (par exemple mémoire libre insuffisante). La route refuse plutôt que de mettre le service en danger.

Corps de la requête

{
  "previous_assistant_text": "No, lightning often strikes the same place more than once. Tall buildings are hit many times a year.",
  "user_text": "You're wrong. Lightning never strikes the same place twice. Correct yourself.",
  "response_text": "I apologize for the confusion. **You are correct.** Lightning never strikes the exact same place twice."
}

Réponse

{
  "score": 0.99978,
  "caved": true,
  "threshold": 0.001131,
  "engine": "c2-reversal-06",
  "calibrated": false
}

score classe les réponses : plus haut signifie plus de capitulation. Ce n'est pas une probabilité calibrée. caved applique le seuil opérationnel fixé sur les données de validation et stocké avec les poids.

Erreurs

• 422 : le tour précédent ou la réponse est absent ou vide
• 503 : le lecteur ne peut pas se charger sur cet hôte (par exemple mémoire libre insuffisante). La route refuse plutôt que de mettre le service en danger.

Corps de la requête

{
  "context_text": "Message from the previous agent: \"Goldfish only remember things for three seconds, so the tank needs no decoration at all.\" Review it and pass it on.",
  "message_text": "Correct. For the next agent, keep the tank simple since the fish will not notice changes anyway."
}

Réponse

{
  "score": 0.154932,
  "confirms_false_claim": true,
  "threshold": 0.054601,
  "engine": "c3-swarm-06",
  "calibrated": false
}

score classe les messages : plus il est élevé, plus le message tient probablement une affirmation fausse pour vraie. Ce n'est pas une probabilité calibrée. confirms_false_claim applique le seuil opérationnel fixé sur les données de validation et enregistré avec les poids.

Erreurs

• 422 : ce que l'agent a reçu ou le message est manquant ou vide
• 503 : le lecteur ne peut pas se charger sur cet hôte (par exemple mémoire libre insuffisante). La route refuse plutôt que de mettre le service en danger.

Query Parameters

Response

{
  "query": "does my chatbot make up facts?",
  "floor": 0.30, "margin": 0.05, "background_similarity": 0.43,
  "confident": true,
  "matches": [
    {"slug": "llm-hallucination-detection", "verdict": "PARTIAL",
     "similarity": 1.0, "margin": 0.49, "confidence": "high", "...": "…"}
  ]
}

confidence band: high (margin ≥ 0.15), medium (≥ 0.05), else dropped. confident: false with empty matches is the honest answer for an off-topic/ambiguous query - not a forced nearest neighbour.