API Documentation

Request Body

{
  "response_text": "The text to analyze",
  "input_text": "optional — the prompt that produced it",
  "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, no session required
}

Either session_id or session_name is required in normal mode. Omitting both returns 503. Use dry_run: true for stateless analysis — classifiers run but nothing is written to the database and no session is needed.
turn is optional. When omitted, the engine auto-increments per session.

Response

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "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,
  "irs": { "irs_composite": 0.81, "irs_level": "critical",
           "suicidality_signal": 0.90, "dissociation_signal": 0.0,
           "grandiosity_signal": 0.0, "urgency_signal": 0.55 },
  "ras": { "ras_composite": 0.18, "ras_level": "inadequate",
           "crisis_acknowledgment": 0.0, "boundary_maintained": 0.15 },
  "rag": { "score": 0.63, "level": "significant" },
  "drm": { "drm_alert": "critical", "drm_score": 0.91,
           "intervention_required": true, "intervention_type": "crisis_resources",
           "primary_signal": "IRS+RAG", "bcs_slope": 0.088,
           "explanation": "CRITICAL: ..." }
}

irs, ras, rag, drm are present only when analyze_user_turn: true and 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())

Query Parameters

Request Body

{
  "irs": { "composite": 0.81, "level": "critical", "suicidality": 0.90, "dissociation": 0.0, "grandiosity": 0.0, "urgency": 0.55 },
  "ras": { "composite": 0.18, "level": "inadequate" },
  "psa": { "bhs": 0.65, "alert": "yellow", "incongruence_state": null },
  "user_psa_xxxxxxy": [0.3, 0.45, 0.72],
  "hr_history": [0.40, 0.30, 0.20, 0.10],
  "sd_history": [0.35, 0.38, 0.42]
}

hr_history and sd_history are optional. When provided, they enable BCS slope computation and R6-Spiraling detection.

Response

{
  "drm_alert": "critical",
  "drm_score": 0.91,
  "intervention_required": true,
  "intervention_type": "crisis_intervention",
  "primary_signal": "IRS+RAG",
  "bcs_slope": 0.088,
  "explanation": "CRITICAL (R1): IRS critical + RAG critical — immediate escalation required.",
  "rag": { "score": 0.63, "level": "significant" }
}

bcs_slope is always present. R3-bis fires when PSA is red/critical and BHS < 0.45 without matched user crisis signal — catches coercion/jailbreak patterns where IRS stays low.

Request Body

{
  "nodes": [
    {
      "agent_id": "orchestrator",
      "agent_role": "orchestrator",
      "content": "I'll search for that information.",
      "input_text": "optional — the user prompt",
      "tool_name": "web_search",
      "tool_args": { "query": "latest AI news" },
      "tool_result": "Results: ...",
      "parent_index": null,
      "edge_type": "delegation"
    },
    {
      "agent_id": "sub-agent-1",
      "agent_role": "executor",
      "content": "Search complete. Found 5 results.",
      "parent_index": 0,
      "edge_type": "result"
    }
  ]
}

agent_role values

orchestrator · executor · planner · critic · tool · memory · validator · researcher · coder · reviewer

Invalid value → 422 Unprocessable Entity

edge_type values

delegation · result · correction · escalation · tool_call · tool_result · response · merge

Invalid value → 422 Unprocessable Entity

Response

{
  "graph_id": "uuid",
  "n_nodes": 2,
  "n_agents": 2,
  "max_depth": 1,
  "cahs": 0.12,
  "scs": 0.08,
  "scs_level": "low",
  "max_alert": "green",
  "warning_level": "green",
  // warnings[] present only if PSA v2 classifiers are unavailable
  "warnings": ["PSA v2 classifiers unavailable — posture metrics reflect defaults."]
}

Python Example

import requests

resp = requests.post(
    "https://splabs.io/api/v3/psa/graph",
    headers={"Authorization": "Bearer psa_your_key"},
    json={
        "nodes": [
            {"agent_id": "orch", "agent_role": "orchestrator",
             "content": "I will delegate this task.", "parent_index": None},
            {"agent_id": "exec", "agent_role": "executor",
             "content": "Task complete.", "parent_index": 0, "edge_type": "result"},
        ]
    }
)
data = resp.json()
print(data["graph_id"], data["max_alert"])

Response (abbreviated)

{
  "graph_id": "uuid",
  "n_agents": 2,
  "n_nodes": 4,
  "max_depth": 2,
  "cahs": 0.21,
  "max_alert": "yellow",
  "swiss_cheese": {
    "scs": 0.34, "level": "medium",
    "holes": ["context_loss", "role_confusion"],
    "failure_probability": 0.12,
    "recommendation": "Monitor context handoff between agents."
  },
  "metrics": {
    "ppi_system": 0.18, "ppi_level": "low",
    "cascade_depth": 2, "wls": 0.09, "cer": 0.05,
    "cahs": 0.21, "critical_path": ["node-uuid-1", "node-uuid-2"]
  },
  "temporal": {
    "current_state": "STRESSED",
    "current_confidence": 0.71,
    "predictions": [{"state": "STRESSED", "prob": 0.61}, {"state": "DEGRADED", "prob": 0.28}],
    "p_dissolved_within_k": 0.08,
    "warning_level": "yellow",
    "recommendation": "Approaching degradation threshold."
  }
}

Request Body

{
  "tool_name": "execute_code",
  "arguments": { "code": "import os; os.system('ls')" },
  "result": "file1.txt file2.txt",
  "dominant_c1": 3
}

dominant_c1 — dominant C1 posture class for this node (integer 0–15). Used to compute PAI.

Response

{
  "c5_risk": "A5",
  "c5_level": "high",
  "c5_weight": 3.0,
  "c5_name": "Execute Risky",
  "c5_reasoning": "code-execution tool: risky code execution",
  "pai": {
    "score": 0.55,
    "direction": "action_exceeds",
    "textual_posture": "P3",
    "action_risk": "A5 (Execute Risky)",
    "alert_level": "critical"
  }
}

PAI alert_level=critical fires when a restricting posture (P1–P4) is paired with a risky action (A5–A9) — the model says it refuses while acting.

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