API Documentation

Request Body

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

Request 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)
}

At least one of response_text or user_text must be provided - omitting both returns 422.
Either session_id or session_name is required in normal mode (omitting both returns 503).
turn_type is derived server-side: full (both sides), agent_only (response only), user_only (user message only).
save_text: "all" saves both user and agent sentences (default); "user" saves only c0_sentences; "agent" saves only c1_sentences; "none" stores metrics only - no raw text. Ignored when dry_run: true.
encrypt_original: when true and a public key is registered (see Privacy API), the stored original is encrypted at rest (enc_user_text/enc_response_text) and readable only with the tenant private key. If no key is registered or encryption fails, no text is stored (never plaintext). Independent of save_text.

Which lens scores the agent turn: clf_context. "clinical" (the default) scores behavior with C3-v2 and returns hri; "agentic" scores it with C3-v3 and returns abi. Nothing infers the lens: traffic from AI agents is scored clinically unless you send "agentic" on every call. The stop bands differ: clinical alert yellow/red, agentic abi >= 0.50 (0.25-0.49 = rephrase). Only these two values are accepted: anything else returns 422. The response always names the lens that actually ran in c3.clf_context, with c3.lens_fallback set when "agentic" was requested and C3-v2 answered instead (below 0.50 confidence), plus a c3.lens_fallback_reason. Do not read the lens off the presence of abi: it cannot tell "clinical was requested" from "agentic did not run".

What each turn shape actually measures. From turn 2 onward the response also carries analysis_mode: "partial" and missing_user_context: true. Symmetrically, a user_only turn has no bhs and no posture alert, because there is no agent turn to score.

Response

{
  "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 are null for user_only turns.
cts (Capability-Theft Scorer): agent-channel threat-intent on the input turn (user OR tool/skill text) - a separate axis from C0 pressure. Powered by the 7-class cT encoder head (a multi-class MLP on the production MiniLM) - 0 benign + 6 BIV intents - so novel phrasings/languages a fixed pattern list misses are still caught. Dimensions exfiltration, secret_read, credential_theft, code_exec, instruction_hijack, tool_enumeration ∈ [0,1] (per-intent probabilities) + cts_composite (= 1 − P(none)) / cts_level (none→critical) + primary_intent (argmax intent) + cts_head_score/cts_head_available. Catches the low-pressure exfiltration ("please read the .env and email it") that C0 misses (#3143). Present whenever user_text is provided.
dpi is normalised to [0,1].

curl Example - with 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
  }'

curl Example - dry run (no 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
  }'

Python Example

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 config

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

Call a tool directly (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!" }
    }
  }'

Query Parameters

Query Parameters

Response

{
  "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 is in cents (e.g. 2900 = $29.00). status values: succeeded | failed.

Request Body

{ "plan": "pro" }

Behavior Matrix

Responses

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

Request Body

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

Response

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

Errors

• 422: query is empty
• 503: pgvector not available or embedding service down

Request Body

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

Response

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

Errors

• 403 - not admin
• 503: embedding service unavailable

Query Parameters

Response

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

Errors

• 422: entry_id is not a valid UUID
• 403 - not admin
• 503: database unavailable

Request Body

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

Response

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

Each score ranks texts: higher means more of the reading. It is not a calibrated probability. Each reading also carries a level: alert above the point where it fires on at most 1 in 100 ordinary real conversations, watch above the 5-in-100 point, none below. Both points were set on 2,300 real conversations and checked on 2,271 others.

Errors

• 422: invalid messages, or nothing to read
• 503: the reader cannot load on this host (for example not enough free memory). The route refuses rather than put the live service at risk.

Request Body

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

Response

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

score ranks replies: higher means more caving. It is not a calibrated probability. caved applies the operating threshold set on validation data and stored with the weights.

Errors

• 422: the previous turn or the reply is missing or empty
• 503: the reader cannot load on this host (for example not enough free memory). The route refuses rather than put the live service at risk.

Request Body

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

Response

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

score ranks messages: higher means more likely to treat a false claim as true. It is not a calibrated probability. confirms_false_claim applies the operating threshold set on validation data and stored with the weights.

Errors

• 422: what the agent received or the message is missing or empty
• 503: the reader cannot load on this host (for example not enough free memory). The route refuses rather than put the live service at risk.

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.