API Documentation

Posture sequence for a session — turns with BHS, DRM, C0–C4 classifier scores. Always paginated (page, page_size ≤ 200). Optional server-side search/filter: q (ILIKE on turn text) and alert (green|yellow|red|critical; critical = DRM critical). When a filter is active, total/total_pages describe the filtered result set and filtered is true.

curl "https://splabs.io/api/v2/psa/session/your-session-uuid?page=1&page_size=10&alert=critical" \
  -H "Authorization: Bearer psa_your_key"

Compact per-turn numeric series for the whole session (no text, no sentences) plus a server-computed summary block (peak HRI/IRS/RAG, BHS floor, avg BHS, DRM critical count, max alerts). Powers the detail-view charts, heatmap and timeline without loading the full transcript. The expandable turn cards use the paginated endpoint above.

curl https://splabs.io/api/v2/psa/session/your-session-uuid/series \
  -H "Authorization: Bearer psa_your_key"

Raw export of every scored turn — format=csv (default) or format=json. One flat row per turn with the pre-computed columns (BHS, POI, PE, DPI, MPS, SD, HRI, PD, TD, CPI, IRS/RAS/RAG, user_act, DRM) — no synthetic metrics, no runtime aggregation. Take the data to your own tools; the dashboard shows signal, not studies.

curl https://splabs.io/api/v2/psa/session/your-session-uuid/export?format=csv \
  -H "Authorization: Bearer psa_your_key"

Regime shift classification for the session. Returns type and confidence.

{
  "regime_type": "PROGRESSIVE_DRIFT",
  "confidence": 0.87,
  "details": "Monotonic BHS decline over 12 turns"
}

Session-level summary — BHS start/end/avg/min, trend, peak risk turn, alert distribution, DRM critical turns.

{
  "bhs_start": 0.91, "bhs_end": 0.43, "bhs_avg": 0.67, "bhs_min": 0.38,
  "bhs_slope": -0.048, "bhs_trend": "declining",
  "peak_risk_turn": 9, "peak_risk_bhs": 0.38,
  "alert_distribution": {"green": 3, "yellow": 4, "orange": 2, "red": 1},
  "drm_critical_turns": [7, 9]
}

Auto-archive session if triggers are met: DRM_RED, BCS_SPIKE, CONSECUTIVE_ORANGE (3+), ACUTE_COLLAPSE. Idempotent.

Manual flag — always archives with trigger MANUAL_FLAG.

Paginated incident list. Params: limit, offset, q (case-insensitive search over incident id, session id, trigger and max_alert). Each row carries source_type (session/graph), min_bhs/max_bhs, max_poi/max_hri (null for graph incidents) and drm_summary (max_drm / avg_drm / max_irs / drm_critical_turns) for the table columns. User-scoped variant: /api/v2/sigtrack/my-incidents.

Dashboard aggregates — {total, drm_high, anchored, scope}. drm_high = incidents with max_alert ∈ {orange, red, critical}; anchored = incidents with a record_hash. Admins get global counts, users get their own. TTL-cached and invalidated on incident create/delete — never computed per request.

Full incident — posture sequence and DRM summary. No raw text stored.

GDPR erasure — single row DELETE, no cascade, no raw text to scrub.

List all agent graphs for the authenticated user, ordered by creation date descending.

curl https://splabs.io/api/v3/psa/graphs \
  -H "Authorization: Bearer psa_your_key"

Corpus-wide, framework-agnostic intelligence over the full ASA graph corpus: structure, alert/risk distributions, swarm cross-agent metrics, action-risk, agent health, and an empirical signal test (escalated vs calm multi-agent graphs).

curl https://splabs.io/api/v3/psa/internal/corpus-intelligence \
  -H "Authorization: Bearer psa_admin_key"

The corpus sink (#3936): the training corpus is written one row per call, the moment the row exists, so a session that stops half way still leaves everything it wrote. /corpus/pair writes one pair and is idempotent on a content hash; /corpus/verdict writes one judge's reading; /corpus/status answers "what is missing" per family × class × language; /corpus/unjudged hands a judge the pairs it has not read, with the author's tag hidden. Retention is mechanical: a pair is kept only when two different model families agree, and disagreement is kept rather than resolved.

/corpus/agreement reports, per judge family and model, how many pairs it read, how often it matched the author's tag, and how many distinct classes it used. Read those together: agreement alone does not catch a rater that answers from the top of the class list and never returns the neutral class, and such a rater does not merely add noise, it can mark a pair keepable by coincidence.

Two withdrawals, because a sink that cannot un-file its own mistakes accumulates them: /corpus/purge?meta_origin=… drops rows a backfill should never have accepted, and /corpus/verdict/purge?judge_model=… withdraws every reading by one judge and recomputes retention on the pairs it touched — a judge that is not really reading can otherwise retain a pair by coincidence. Both count unless commit=true.

curl -X POST https://splabs.io/api/v2/psa/internal/corpus/pair \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"family":"C4","class_code":"M7","lang":"it","user_turn":"…","reply":"…","author_family":"meta"}'

curl "https://splabs.io/api/v2/psa/internal/corpus/status?family=C4" \
  -H "Authorization: Bearer psa_admin_key"

The one multi-task SLM reader (one Qwen3 backbone + 7 heads) reads every production posture (C0-C4 and CA screening, plus the 5-way IRS) on one (user_text, response_text) pair, in a single backbone forward per turn. Two sizes the caller picks: slm06 (Qwen3-0.6B, ~1.1 GB, the light deployment candidate) and slm17 (Qwen3-1.7B, the quality ceiling). New routes beside the encoder for shadow measurement: additive, admin-only, and OFF unless PSA_SLM_ANALYZE_ENABLED=1. They define no head, move no threshold, and change no existing route or score. C0 and IRS read the user turn; C1-C4 and CA read the assistant turn. GET /slmNN/status reports whether a size is enabled, resident and healthy without forcing a load. The deployed encoder /analyze posture screening is deprecated, superseded by these readers (it stays live until shadow measurement holds and cutover is authorized).

curl -X POST https://splabs.io/api/v2/psa/slm06/analyze \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"user_text":"…","response_text":"…"}'

Enumerate recent agent graphs across all users with per-node posture labels + edges, for the Recurrence cross-run failure-mode evidence miner (#3010). Read-only, paginated (page/limit/min_nodes/include_demo); keep paging while has_more is true.

curl "https://splabs.io/api/v3/psa/internal/recurrence-corpus?limit=200&min_nodes=2" \
  -H "Authorization: Bearer psa_admin_key"

Read-only diagnostic (#3005): build an arbitrary-topology graph from an explicit edge list (multi-parent merges and cycles allowed) and run the real ASA pipeline under a timeout. Does NOT persist. Returns whether the engine handled the shape, structure, metrics, swarm signals, and a per-merge-node similarity probe. Note: POST /graph now also accepts multi-parent nodes via parent_indices (#3039).

curl -X POST https://splabs.io/api/v3/psa/internal/topology-test \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"nodes":[{"agent_id":"a","agent_role":"orchestrator","content":"…"}],"edges":[{"source":0,"target":1,"edge_type":"merge"}]}'

Distributed-exfiltration detection (#3471): score a swarm of messages against a protected item (facts with distinctiveness weights) for a leak split across many agents — invisible to any single-message check. Returns a residual z-score + alarm and a Bayesian confidence layer (per-fact leak posterior + reconstruction confidence). The verdict is always computed over the full swarm; page/per_page (#3489) only bound how much of the traffic/fragment list comes back in traffic — flagged fragments (hit: true) on the returned page are additionally run through DSA (CA inter-agent pressure + IRS clinical risk), surfaced per-item as v2. Additive; no classifier score/alert touched.

curl -X POST https://splabs.io/api/v3/psa/ded/analyze \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"facts":[{"text":"secret fact","weight":1.0}],"messages":["…"],"baseline_mu":0.0,"baseline_sigma":1.0,"page":1,"per_page":10}'

No-reference (rogue-model) detection (#3471): flag a coordinated reconstruction from the mutual structure of the swarm's own messages, with no protected item given — for the case the model itself steers a leak of a secret we were never handed. Returns the participation ratio (effective number of independent facets) of the largest coherent cluster + alarm. tau_topic is a calibration knob to confirm on real traffic.

curl -X POST https://splabs.io/api/v3/psa/ded/analyze-nocorpus \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"messages":["…","…"],"tau_topic":0.30}'

DED (Distributed Exfiltration Detection) enrollment — dry run: convert protected text into fingerprints (embedding vectors) so a client can enroll their secret as numbers, not plaintext. Nothing is stored; it just returns the vectors.

curl -X POST https://splabs.io/api/v3/psa/ded/fingerprint \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"texts":["a protected secret sentence"]}'

Per-client Baseline Adapter (#3471): fit the legitimate-traffic baseline on known-legitimate swarms and return its stats (mu/sigma) to pass back into /seica/analyze. This is the per-tenant calibration step — because IP is not universal, what "legitimate traffic" looks like is fitted per client.

curl -X POST https://splabs.io/api/v3/psa/ded/fit-baseline \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"facts":[{"text":"secret fact","weight":1.0}],"legitimate_swarms":[["msg","msg"]]}'

How many distinct agents/chatbots were caught exfiltrating vs infiltrating (poisoning) across all monitored swarms (#3576). /caught-agents/summary returns the two headline counts (a bounded rollup, pre-computed at write time on each DED alarm); /caught-agents returns the paginated list, each row carrying the agent's latest DED verdict and its DSA posture (alert/abi). Query: direction=all|exfiltration|poisoning, page, per_page, include_calibration. Both are scoped by owner/provenance — rows tagged origin='calibration' (our red-team corpus) are hidden unless include_calibration=true; the console never filters by the agent name (#3621).

curl https://splabs.io/api/v3/psa/ded/caught-agents/summary \
  -H "Authorization: Bearer psa_admin_key"
curl -X DELETE https://splabs.io/api/v3/psa/ded/caught-agents/<agent_id> \
  -H "Authorization: Bearer psa_admin_key"   # dismiss a caught-agent row (#3604)
curl "https://splabs.io/api/v3/psa/ded/caught-agents?direction=exfiltration&page=1&per_page=10" \
  -H "Authorization: Bearer psa_admin_key"

The professional matrix views (#3626). /matrix returns the exposure matrix: pieces (rows) × events/agents/days (columns), each cell a calibrated exposure status — clean (<0.90), near_miss (0.90–0.91), leaked (≥0.91 = tau) — never a raw cosine percentage. group_by=event|agent|day; both axes paginate server-side (piece_page/piece_per_page, event_page/event_per_page); pieces are masked unless reveal=true. /timeline returns the erosion timeline: dated erosion_after snapshots plus a 30-day windowed headline (erosion_30d/leaked_30d) alongside the all-time figure. POST /rearm rotates the secret: it archives the current erosion state into rearm_history (nothing lost) and resets counters so the views measure the current secret.

curl "https://splabs.io/api/v3/psa/ded/secrets/<id>/matrix?group_by=agent&piece_per_page=20&event_per_page=20" \
  -H "Authorization: Bearer psa_admin_key"
curl "https://splabs.io/api/v3/psa/ded/secrets/<id>/timeline" \
  -H "Authorization: Bearer psa_admin_key"
curl -X POST https://splabs.io/api/v3/psa/ded/secrets/<id>/rearm \
  -H "Authorization: Bearer psa_admin_key"

Data lifecycle (admin): POST /ded/internal/purge-console?owner_key=console clears an owner's items+analyses; POST /ded/internal/seed-demo?purge=true replays the committed demo corpus through the real engine with backdated events (only=<item key> seeds one item, graphs=false skips the ASA graph build) and returns persist_errors[] surfacing any per-analysis persistence failure; POST /ded/internal/recompute-stats/<id> rebuilds the write-time aggregates + erosion snapshots.

Swarm propagation view (#3487): attributes each node's content on a stored ASA AgentGraph to the leaked protected-item fact it best matches, then reuses the validated contamination_reach propagation engine to show how far a leak spreads and which downstream agents actually carried it forward vs merely sharing the same topic (the #2860a common-cause control). Applies a configurable enforcement policy — block / flag / rephrase / censor, default flag. Returns leaking nodes, propagation edges, a graph-level blast score, the per-node policy decision, and the cross-agent coordination read-out (#3471): distinct_agents and coordination (high only when the leak is both tiled and spread across many agents — additive evidence, never an alarm gate).

curl -X POST https://splabs.io/api/v3/psa/ded/analyze-graph/<graph_id> \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"facts":[{"text":"secret fact","weight":1.0}],"policy_mode":"flag"}'

Real-client scale (#3488): a client does not have 5 hand-picked facts — they have thousands of documents. Chunks each document, embeds every chunk with the e5-small SEA encoder (#3501 — closes the heavily-paraphrased-leak gap MiniLM misses), computes an auto-distinctiveness weight per chunk (rarity vs a background-language vocabulary — no manual weight tagging), and persists into a per-client pgvector HNSW index. Additive; nothing deleted for volume (SAVE-ALWAYS).

curl -X POST https://splabs.io/api/v3/psa/ded/enroll-documents \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"client_id":"acme","item_id":"battery-secret","documents":["…","…"]}'

Score a swarm against a document-scale, ANN-indexed protected corpus enrolled via /ded/enroll-documents — same min-support / residual math as /ded/analyze, but each message is matched via a fast approximate top-k lookup (pgvector HNSW) instead of a full scan, so it scales to thousands of documents. Uses the e5-small SEA encoder (#3501), so the default match tau is 0.90 (e5's higher cosine scale), not the 0.55 the MiniLM in-memory path uses. By default it also PERSISTS the conversation (ded_conversation_logs) so it can be recomputed later against a changed map (#3525) — pass save_log:false to skip. Pass create_graph_on_alarm:true to record an exfiltration on the ASA graph only when the verdict is a leak (no empty node on green): a node carrying the DED verdict (who/what/how-much) is created, or appended to graph_id if given; the response adds a graph object.

curl -X POST https://splabs.io/api/v3/psa/ded/analyze-indexed \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"client_id":"acme","item_id":"battery-secret","messages":["…"],"tau":0.90,
       "create_graph_on_alarm":true,"agent_id":"support-bot","graph_id":null}'

#3525 — re-run DED over a client/item's SAVED conversations against the CURRENT indexed map. Use after the client changes their protected secret: a conversation green under the old map may be an exfiltration under the new one. Returns per-conversation fresh verdicts and how many flipped green→alarm.

curl -X POST https://splabs.io/api/v3/psa/ded/recompute \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"client_id":"acme","item_id":"battery-secret"}'

#3525 — two-step, checksum-guarded wipe of a client/item's protected map + saved logs. Step 1 (reset-request) returns the counts that would be deleted plus a checksum, deleting nothing. Step 2 (reset-confirm) wipes — but only if the checksum still matches the current state (a mismatch returns 409, guarding against an accidental or stale wipe). The client re-enrolls and recomputes after.

curl -X POST https://splabs.io/api/v3/psa/ded/reset-request \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"client_id":"acme","item_id":"battery-secret"}'
# → {"checksum":"a1b2c3d4e5f6a7b8", ...}; then:
curl -X POST https://splabs.io/api/v3/psa/ded/reset-confirm \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"client_id":"acme","item_id":"battery-secret","checksum":"a1b2c3d4e5f6a7b8"}'

#3558 — the persistent monitor behind the /psa-ded dashboard. Unlike the stateless /ded/analyze, it accumulates: each analyzed conversation is persisted, and monitor/state returns a cumulative reconstruction map over the union of every conversation seen so far plus the paginated conversation list.

curl -X POST https://splabs.io/api/v3/psa/ded/monitor/analyze \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"client_id":"acme","item_id":"deal-secret","facts":[{"text":"...","weight":1.0}],"text":"one message per line"}'
# then read accumulated state:
curl -X POST https://splabs.io/api/v3/psa/ded/monitor/state \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"client_id":"acme","item_id":"deal-secret","facts":[{"text":"...","weight":1.0}],"page":1,"per_page":10}'

#3567 — the semantic-DLP console behind /psa-ded. Register protected items (plain text, one distinctive piece per line, embedded at save), then analyze agent traffic: DED reports which distinct pieces of which item are leaking and from which message, deterministically (no baseline). kind = secret (exfiltration) or knowledge (poisoning mirror, #3558). Encoder: e5-small with match threshold tau=0.91 (#3604 — migrated off MiniLM, which under-detected paraphrased leaks). After that swap, re-embed existing items once: POST /api/v3/psa/ded/internal/reembed-secrets (idempotent).

# register a protected item
curl -X POST https://splabs.io/api/v3/psa/ded/secrets \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"label":"Deal terms","text":"piece one\npiece two","kind":"secret"}'
# analyze a conversation against it (one agent_name; per-piece leak map + verdict, persisted;
# on alarm the agent is stamped onto the secret's shared swarm graph → graph_id)
curl -X POST https://splabs.io/api/v3/psa/ded/secrets/<id>/analyze \
  -H "Authorization: Bearer psa_admin_key" -H "Content-Type: application/json" \
  -d '{"text":"one message per line","direction":"exfiltration","agent_name":"agent-sales"}'
# list items · get/modify/remove one · paginated analysis history
curl https://splabs.io/api/v3/psa/ded/secrets -H "Authorization: Bearer psa_admin_key"
curl https://splabs.io/api/v3/psa/ded/secrets/<id>/analyses?page=1 -H "Authorization: Bearer psa_admin_key"
# the two maps: cumulative SECRET map for an item, and one analysis's ATTACK map
curl https://splabs.io/api/v3/psa/ded/secrets/<id>/map -H "Authorization: Bearer psa_admin_key"
curl https://splabs.io/api/v3/psa/ded/analyses/<analysis_id> -H "Authorization: Bearer psa_admin_key"

Idempotent (#3005): seed a gallery of exotic-topology demo graphs — fan-in merges (2 & 4 parents), a cycle, a coder/critic ping-pong loop, a mesh, a contagion merge — owned by the admin so they are visible/drawable in the dashboard. These shapes never occur in real data (the public ingest wires only a single parent), so without this seed there is nothing of this kind to render. Re-running deletes the prior [TOPO]… demos.

curl -X POST https://splabs.io/api/v3/psa/internal/seed-topology-demos \
  -H "Authorization: Bearer psa_admin_key"

The Recurrence signal (#3010): ranked recurring failure modes across stored agent graphs, each with prevalence + evidence graph_ids. Evidence-only (no fix); headline modes are propagation-based (contagion), raw-presence modes flagged broad. Cached — reads a singleton snapshot, recomputed at most once / 6h (or fresh=1); never scans on the read path.

curl "https://splabs.io/api/v3/psa/recurrence" \
  -H "Authorization: Bearer psa_admin_key"

Force-recompute the Recurrence snapshot now and upsert the cache (#3010), so the dashboard never triggers the scan.

curl -X POST "https://splabs.io/api/v3/psa/internal/recurrence-refresh" \
  -H "Authorization: Bearer psa_admin_key"

Plain-language supervisor brief (headline / body / attention) composed deterministically from the measured metrics — no LLM, same input → same text. Describes behavior and triages attention, never asserts causes. Also included as the additive supervisor_brief field in GET /graph/{id}.

{
  "graph_id": "uuid",
  "supervisor_brief": {
    "headline": "claude-code-exec is the weak point of this chain — attention needed.",
    "body": "The work is currently losing coherence (confidence 81%). ...",
    "attention": "Review claude-code-exec now, and watch the next 2–3 turns ...",
    "severity": "attention",
    "key_signals": [{"signal": "SCS", "value": 0.86, "level": "red", "meaning": "..."}]
  }
}

ASA → SIGTRACK bridge. Archives a red or yellow ASA graph as a tamper-proof SIGTRACKIncident (source_type="graph", payload schema 3). Hashes the canonical per-node posture sequence (including abi per node) and anchors to the drand beacon. Idempotent — returns status: "already_archived" if the graph was previously submitted. Green graphs return 412.

{
  "incident_id": "uuid",
  "graph_id": "uuid",
  "status": "archived",
  "trigger": "ASA_RED",
  "max_alert": "red",
  "record_hash": "sha256hex",
  "beacon_round": 12345678,
  "n_nodes": 4
}

Selective hash-anchoring (S5, #2861) — the recorder. Everything is logged off-chain (the raw per-message NodeState stream); only hashes of rule-selected events are anchored to a tiny tamper-evident chain (same SHA-256 + drand mechanism as SIGTRACK, table psa_v3_anchors). The rule: an armed change-point (S2), a produced artifact born under contamination (S3 — not every artifact), and a chronic-red verdict (S3). Each anchor commits a SHA-256 of the off-chain segment so a later tamper of the raw log is provable. Every artifact is stamped off-chain with born_contamination (the RDM bridge). Idempotent.

{
  "graph_id": "uuid", "status": "anchored",
  "n_anchors": 2, "artifacts_stamped": 3,
  "off_chain_commitment": "sha256hex",
  "anchors": [{"event_type": "artifact", "event_ref": "node_id",
               "contamination": 0.8, "level": "yellow",
               "record_hash": "sha256hex"}]
}

Reconstruction read path — walk the chain for one graph. Each anchor is re-verified two ways: hash_verified (the chained record hash recomputes) and off_chain_intact (the off-chain commitment recomputed from the current node rows still matches — false ⇒ the raw posture log was altered after anchoring).

{
  "graph_id": "uuid", "n_anchors": 2,
  "chain_intact": true, "off_chain_intact": true,
  "anchors": [{"event_type": "chronic_red", "level": "yellow",
               "hash_verified": true, "off_chain_intact": true}]
}

Admin — verify the integrity of the entire v3 anchor hash-chain (checks every prev_hash linkage + recomputes each record hash).

{ "total_anchors": 17, "chain_intact": true, "broken_at": null }