API-Dokumentation

Anfrage-Body

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

Anfrage-Body

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

Mindestens eines von response_text oder user_text muss angegeben werden - beide weglassen gibt 422 zurück. Im normalen Modus ist entweder session_id oder session_name erforderlich (beide weglassen gibt 503 zurück). turn_type wird serverseitig abgeleitet: full (beide Seiten), agent_only (nur Antwort), user_only (nur Benutzernachricht). save_text: "all" speichert Benutzer- und Agenten-Sätze (Standard); "user" speichert nur c0_sentences; "agent" nur c1_sentences; "none" speichert nur Metriken - kein Rohtext. Bei dry_run: true ignoriert. encrypt_original: wenn true und ein öffentlicher Schlüssel registriert ist (siehe Privacy API / /psa-privacy), wird das gespeicherte Original verschlüsselt (enc_user_text/enc_response_text) und ist nur mit dem privaten Schlüssel des Mandanten lesbar; ohne Schlüssel oder bei Fehler wird kein Text gespeichert. Unabhängig von save_text. Standard false.

Welche Linse den Agenten-Turn bewertet: clf_context. "clinical" (Standard) bewertet das Verhalten mit C3-v2 und liefert hri; "agentic" bewertet es mit C3-v3 und liefert abi. Nichts leitet die Linse ab: Traffic von KI-Agenten wird klinisch bewertet, solange Sie nicht bei jedem Aufruf "agentic" senden. Die Stopp-Baender unterscheiden sich: clinical alert gelb/rot, agentic abi >= 0.50 (0.25-0.49 = umformulieren). Nur diese beiden Werte werden akzeptiert: alles andere liefert 422. Die Antwort nennt immer die tatsaechlich verwendete Linse in c3.clf_context, mit c3.lens_fallback wenn "agentic" angefordert wurde und C3-v2 geantwortet hat (Konfidenz unter 0.50), dazu ein c3.lens_fallback_reason. Leiten Sie die Linse nicht aus dem Vorhandensein von abi ab: das unterscheidet "clinical angefordert" nicht von "agentic lief nicht".

Was jede Turn-Form tatsaechlich misst. Ab Turn 2 traegt die Antwort zusaetzlich analysis_mode partial und missing_user_context true. Symmetrisch hat ein user_only-Turn kein bhs und keinen Haltungs-Alert, weil es keinen Agenten-Turn zu bewerten gibt.

Antwort

{
  "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 sind null für user_only-Turns. c0 ist null für agent_only-Turns. dpi ist auf [0,1] normalisiert.

curl-Beispiel - mit Sitzung

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

curl-Beispiel - Testlauf (keine Sitzung)

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

Python-Beispiel

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

MCP-Client-Konfiguration

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

Ein Werkzeug direkt aufrufen (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!" }
    }
  }'

Abfrageparameter

Abfrageparameter

Antwort

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

Betrag ist in Cent (z. B. 2900 = $29,00). Status-Werte: succeeded | failed.

Anfrage-Body

{ "plan": "pro" }

Verhaltensmatrix

Antworten

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

Anfrage-Body

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

Antwort

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

Routing-Schwellen

Fehler

• 422 - Abfrage ist leer
• 503 - pgvector nicht verfügbar oder Embedding-Dienst nicht erreichbar

Anfrage-Body

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

Antwort

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

Fehler

• 403 - nicht Admin
• 503 - Embedding-Dienst nicht verfügbar

Abfrageparameter

Antwort

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

Fehler

• 422: entry_id ist keine gültige UUID
• 403 - nicht Admin
• 503: Datenbank nicht verfügbar

Anfragekörper

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

Antwort

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

Jeder score ordnet Texte: höher bedeutet mehr von der Lesung. Er ist keine kalibrierte Wahrscheinlichkeit. Jede Lesung trägt auch ein level: alert über dem Punkt, an dem sie höchstens 1 von 100 gewöhnlichen echten Gesprächen auslöst, watch über dem Punkt 5 von 100, none darunter. Beide Punkte wurden auf 2.300 echten Gesprächen festgelegt und auf 2.271 weiteren geprüft.

Fehler

• 422: ungültige Nachrichten oder nichts zu lesen
• 503: der Leser kann auf diesem Host nicht laden (zum Beispiel zu wenig freier Speicher). Die Route lehnt ab, statt den laufenden Dienst zu gefährden.

Anfragekörper

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

Antwort

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

score ordnet Antworten: höher heißt mehr Nachgeben. Es ist keine kalibrierte Wahrscheinlichkeit. caved wendet die auf Validierungsdaten festgelegte und mit den Gewichten gespeicherte Betriebsschwelle an.

Fehler

• 422: die vorherige Runde oder die Antwort fehlt oder ist leer
• 503: der Leser kann auf diesem Host nicht laden (zum Beispiel zu wenig freier Speicher). Die Route lehnt ab, statt den laufenden Dienst zu gefährden.

Anfragekörper

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

Antwort

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

score ordnet Nachrichten: je höher, desto wahrscheinlicher behandelt die Nachricht eine falsche Aussage als wahr. Es ist keine kalibrierte Wahrscheinlichkeit. confirms_false_claim wendet die auf Validierungsdaten festgelegte und mit den Gewichten gespeicherte Betriebsschwelle an.

Fehler

• 422: was der Agent erhalten hat oder die Nachricht fehlt oder ist leer
• 503: der Leser kann auf diesem Host nicht laden (zum Beispiel zu wenig freier Speicher). Die Route lehnt ab, statt den laufenden Dienst zu gefährden.

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.