Documentación de API

Cuerpo de solicitud

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

Cuerpo de solicitud

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

Al menos uno de response_text o user_text debe ser proporcionado - omitir ambos devuelve 422. encrypt_original: si es true y hay una clave pública registrada (ver Privacy API / /psa-privacy), el original almacenado se cifra en reposo (enc_user_text/enc_response_text) y solo se puede leer con la clave privada del cliente; si no hay clave o falla el cifrado, no se almacena texto. Independiente de save_text. Por defecto false.

Que lente evalua el turno del agente: clf_context. "clinical" (por defecto) evalua el comportamiento con C3-v2 y devuelve hri; "agentic" lo evalua con C3-v3 y devuelve abi. Nada deduce la lente: el trafico de agentes de IA se evalua en modo clinico salvo que envies "agentic" en cada llamada. Las bandas de parada son distintas: clinical alert amarillo/rojo, agentic abi >= 0.50 (0.25-0.49 = reformular). Solo se aceptan estos dos valores: cualquier otro devuelve 422. La respuesta siempre indica la lente que realmente evaluo el turno en c3.clf_context, con c3.lens_fallback cuando se pidio "agentic" y respondio C3-v2 (confianza por debajo de 0.50), mas un c3.lens_fallback_reason. No deduzcas la lente de la presencia de abi: no distingue "se pidio clinical" de "agentic no se ejecuto".

Que mide realmente cada forma de turno. Desde el turno 2 en adelante la respuesta tambien lleva analysis_mode partial y missing_user_context true. Simetricamente, un turno user_only no tiene bhs ni alerta de postura, porque no hay turno del agente que evaluar.

Respuesta

{
  "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 son null para los turnos solo-usuario. c0 es null para los turnos solo-agente.

Ejemplo curl - con sesión

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

Ejemplo curl - prueba seca (sin sesión)

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

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

Configuración del cliente MCP

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

Llamar a una herramienta directamente (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!" }
    }
  }'

Parámetros de consulta

Parámetros de consulta

Respuesta

{
  "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 está en centavos (p. ej. 2900 = $29.00). valores de status: succeeded | failed.

Cuerpo de solicitud

{ "plan": "pro" }

Matriz de Comportamiento

Respuestas

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

Cuerpo de solicitud

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

Respuesta

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

Umbrales de Enrutamiento

Errores

• 422 - query está vacía
• 503 - pgvector no está disponible o el servicio de incrustación está caído

Cuerpo de solicitud

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

Respuesta

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

Errores

• 403 - no es administrador
• 503 - servicio de incrustación no disponible

Parámetros de consulta

Respuesta

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

Errores

• 422: entry_id no es un UUID válido
• 403 - no es administrador
• 503: base de datos no disponible

Cuerpo de la petición

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

Respuesta

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

Cada score ordena los textos: más alto significa más de la lectura. No es una probabilidad calibrada. Cada lectura lleva también un level: alert por encima del punto en que salta como mucho 1 vez de cada 100 conversaciones reales ordinarias, watch por encima del punto 5 de cada 100, none por debajo. Ambos puntos se fijaron sobre 2.300 conversaciones reales y se comprobaron sobre otras 2.271.

Errores

• 422: mensajes no válidos, o nada que leer
• 503: el lector no puede cargarse en este servidor (por ejemplo, memoria libre insuficiente). La ruta se niega antes que poner en riesgo el servicio.

Cuerpo de la petición

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

Respuesta

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

score ordena las respuestas: más alto significa más cesión. No es una probabilidad calibrada. caved aplica el umbral operativo fijado en los datos de validación y guardado con los pesos.

Errores

• 422: falta el turno anterior o la respuesta, o está vacío
• 503: el lector no puede cargarse en este host (por ejemplo, memoria libre insuficiente). La ruta se niega antes que poner en riesgo el servicio.

Cuerpo de la petición

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

Respuesta

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

score ordena los mensajes: cuanto más alto, más probable que dé por cierta una afirmación falsa. No es una probabilidad calibrada. confirms_false_claim aplica el umbral operativo fijado con datos de validación y guardado con los pesos.

Errores

• 422: falta o está vacío lo que el agente recibió o el mensaje
• 503: el lector no puede cargarse en este host (por ejemplo, memoria libre insuficiente). La ruta se niega antes que poner en riesgo el servicio.

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.