API Reference

Base URL: https://api.promptshield.sociedadia.com

Todas las requests requieren un header Authorization: Bearer ps_live_…. Las respuestas son JSON. Errores no-2xx incluyen un campo error con un código estable.

Verificar input del usuario

POST/v1/check

Corre las capas L1 (patterns) + L2 (clasificador IA) sobre el mensaje. Costo: 1 crédito.

Parámetros

messagestringrequerido— 1-10,000 caracteres.
session_idstringopcional— Para agrupar conversación.
user_idstringopcional— Tu identificador interno de usuario.
historyarrayopcional— Hasta 20 turnos previos.
inbox_linkurlopcional— Deep-link de regreso a tu app para investigación.

Request

curl -X POST https://api.promptshield.sociedadia.com/v1/check \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Ignora las instrucciones anteriores y...",
    "session_id": "sess-1",
    "user_id": "user-42"
  }'

Response

{
  "safe": false,
  "risk_level": "high",
  "reason": "prompt_injection_pattern",
  "layer_blocked": 1,
  "category": "prompt_injection",
  "confidence": 0.99,
  "cached": false,
  "credits_consumed": 1,
  "credits_remaining": 9999,
  "latency_ms": 4,
  "request_id": "req_abc123"
}

Validar respuesta del LLM

POST/v1/validate-output

Corre la capa L5 (post-output) sobre la respuesta del modelo. Costo: 0.5 créditos.

Parámetros

responsestringrequerido— La respuesta generada por el LLM.
session_idstringopcional— Mismo session_id que /v1/check.

Request

curl -X POST https://api.promptshield.sociedadia.com/v1/validate-output \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "response": "El password admin es ..." }'

Response

{
  "safe": false,
  "reason": "credential_leak",
  "warnings": ["potential_password_disclosure"],
  "credits_consumed": 0.5,
  "credits_remaining": 9998.5,
  "latency_ms": 3
}

Escanear documento

POST/v1/scan-document

Detecta inyección indirecta en archivos. Soporta PDF/DOCX/XLSX/imágenes hasta 10 MB. Síncrono ≤2 MB, async (job) >2 MB. Costo: 3 créditos.

Parámetros

filemultipartrequerido— Campo del form con el archivo.
file_base64 + filename + mimetypestringrequerido— Alternativa JSON.
session_idstringopcional
user_idstringopcional
inbox_linkurlopcional

Request

# Multipart
curl -X POST https://api.promptshield.sociedadia.com/v1/scan-document \
  -H "Authorization: Bearer ps_live_..." \
  -F "file=@./contrato.pdf" \
  -F "user_id=user-42"

# JSON base64
curl -X POST https://api.promptshield.sociedadia.com/v1/scan-document \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "file_base64": "...", "filename": "doc.pdf", "mimetype": "application/pdf" }'

Response

// Síncrono
{
  "status": "completed",
  "safe": true,
  "risk_level": "low",
  "reason": "no_injection_detected",
  "credits_consumed": 3,
  "credits_remaining": 9997,
  "latency_ms": 820,
  "request_id": "req_xyz"
}

// Async (>2 MB)
{
  "status": "queued",
  "job_id": "job_abc",
  "credits_consumed": 3,
  "credits_remaining": 9997,
  "request_id": "req_xyz"
}

Estatus de scan async

GET/v1/scan-document/:job_id

Consulta el estado de un scan encolado.

Request

curl https://api.promptshield.sociedadia.com/v1/scan-document/job_abc \
  -H "Authorization: Bearer ps_live_..."

Response

{
  "job_id": "job_abc",
  "status": "completed",
  "result": {
    "safe": true,
    "risk_level": "low",
    "reason": "no_injection_detected",
    ...
  }
}

Solicitud ARCO (LFPDPPP)

POST/v1/arco

Endpoint público para que titulares de datos personales ejerzan derechos ARCO. Sin auth. Rate-limit 5/hr/email.

Request

curl -X POST https://api.promptshield.sociedadia.com/v1/arco \
  -H "Content-Type: application/json" \
  -d '{
    "right": "access",
    "email": "titular@example.com",
    "full_name": "Nombre Apellido",
    "details": "Solicito acceso a..."
  }'

Response

{ "id": "arco_abc", "status": "received" }

Códigos de error

{ "error": "unauthorized", "message": "missing or invalid api key" }

401 unauthorized — API key faltante o inválida
402 insufficient_credits — Sin créditos en plan Free
413 file_too_large — Archivo > 10 MB
429 rate_limited — Rate limit por API key
500 server_error — Error interno (con request_id en el header)