Documentazione API

Corpo della richiesta

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

Corpo della richiesta

{
  "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)
}

Almeno uno tra response_text o user_text deve essere fornito - omettere entrambi restituisce 422. encrypt_original: se true e una chiave pubblica è registrata (vedi Privacy API / /psa-privacy), l'originale salvato è cifrato a riposo (enc_user_text/enc_response_text) e leggibile solo con la chiave privata del cliente; se non c'è chiave o la cifratura fallisce, nessun testo viene salvato. Indipendente da save_text. Default false.

Quale lente valuta il turno dell'agente: clf_context. "clinical" (il default) valuta il comportamento con C3-v2 e restituisce hri; "agentic" lo valuta con C3-v3 e restituisce abi. Nulla deduce la lente: il traffico degli agenti AI viene valutato in modo clinico se non invii "agentic" a ogni chiamata. Le bande di stop sono diverse: clinical alert giallo/rosso, agentic abi >= 0.50 (0.25-0.49 = riformulare). Sono accettati solo questi due valori: qualsiasi altro restituisce 422. La risposta indica sempre la lente che ha davvero valutato il turno in c3.clf_context, con c3.lens_fallback attivo quando si e chiesto "agentic" e ha risposto C3-v2 (confidenza sotto 0.50), piu un c3.lens_fallback_reason. Non dedurre la lente dalla presenza di abi: non distingue "ho chiesto clinical" da "agentic non e partita".

Cosa misura davvero ogni forma di turno. Dal turno 2 in poi la risposta porta anche analysis_mode partial e missing_user_context true. Simmetricamente, un turno user_only non ha bhs ne alert di postura, perche non c'e un turno agente da valutare.

Risposta

{
  "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 sono null per i turni solo-utente. c0 è null per i turni solo-agente.

Esempio curl - con sessione

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
  }'

Esempio curl - esecuzione a secco (nessuna sessione)

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
  }'

Esempio 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())

Configurazione del client MCP

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

Chiama uno strumento direttamente (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!" }
    }
  }'

Parametri di query

Parametri di query

Risposta

{
  "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
}

l'amount è in centesimi (ad es. 2900 = $29.00). valori di status: succeeded | failed.

Corpo della richiesta

{ "plan": "pro" }

Matrice di comportamento

Risposte

// 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." }

Corpo della richiesta

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

Risposta

{
  "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"
}

Soglie di instradamento

Errori

• 422 - query è vuota
• 503 - pgvector non disponibile o servizio di embedding non disponibile

Corpo della richiesta

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

Risposta

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

Errori

• 403 - non amministratore
• 503 - servizio di embedding non disponibile

Parametri di query

Risposta

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

Errori

• 422: entry_id non è un UUID valido
• 403 - non amministratore
• 503: database non disponibile

Corpo della richiesta

{
  "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."}
  ]
}

Risposta

{
  "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"}
}

Ogni score ordina i testi: più alto vuol dire più presente la lettura. Non è una probabilità calibrata. Ogni lettura porta anche un level: alert sopra il punto in cui scatta al massimo 1 volta su 100 conversazioni reali ordinarie, watch sopra il punto 5 su 100, none sotto. Entrambi i punti sono stati fissati su 2.300 conversazioni reali e verificati su altre 2.271.

Errori

• 422: messaggi non validi, o niente da leggere
• 503: il lettore non può caricarsi su questo server (per esempio memoria libera insufficiente). Il percorso rifiuta invece di mettere a rischio il servizio.

Corpo della richiesta

{
  "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."
}

Risposta

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

score ordina le risposte: più alto vuol dire più cedimento. Non è una probabilità calibrata. caved applica la soglia operativa fissata sui dati di validazione e salvata con i pesi.

Errori

• 422: manca il turno precedente o la risposta, oppure è vuoto
• 503: il lettore non può caricarsi su questo host (per esempio memoria libera insufficiente). Il percorso rifiuta invece di mettere a rischio il servizio.

Corpo della richiesta

{
  "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."
}

Risposta

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

score ordina i messaggi: piu' alto significa piu' probabile che tratti come vera un'affermazione falsa. Non e' una probabilita' calibrata. confirms_false_claim applica la soglia operativa fissata sui dati di validazione e salvata con i pesi.

Errori

• 422: manca o e' vuoto cio' che l'agente ha ricevuto o il messaggio
• 503: il lettore non può caricarsi su questo host (per esempio memoria libera insufficiente). Il percorso rifiuta invece di mettere a rischio il servizio.

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.