REST API

La API de SocTalk es una app FastAPI. Toda su superficie se genera desde el código como un esquema OpenAPI y se sirve bajo /api/ (el ingress enruta /api/* a la API y todo lo demás a la consola web):

• OpenAPI JSON: https://mssp.your-mssp.example/api/openapi.json
• Swagger UI: https://mssp.your-mssp.example/api/docs
• ReDoc: https://mssp.your-mssp.example/api/redoc

La superficie OpenAPI es la fuente de verdad. Con estos docs se distribuye una instantánea en /openapi.json, y el catálogo de abajo se genera a partir de ese esquema: no puede desviarse del código.

Regenerar el catálogo

El catálogo de endpoints lo produce npm run gen:api, que lee docs/public/openapi.json. Actualiza primero el esquema desde el código de la API:

# en el repo soctalk
python scripts/dump_openapi.py <soctalk-docs>/docs/public/openapi.json
# en soctalk-docs
npm run gen:api

Todo lo que está entre los marcadores GENERATED se sobrescribe; la prosa a su alrededor se cura a mano.

Catálogo de endpoints

La columna Auth se deriva del guard require_role / require_tenant_role de cada ruta. Una etiqueta de session cookie significa que se acepta cualquier sesión autenticada en el handler, pero los roles con alcance de tenant siguen confinados a sus propios datos por row-level security, así que un tenant_admin solo ve las filas de su tenant incluso en una ruta estilo MSSP sin control de acceso.

146 operations across 33 groups, generated from the OpenAPI schema (API version 0.2.1). Auth is derived from the route's require_role / require_tenant_role guards.

auth

Method	Path	Summary	Auth
POST	/api/auth/assume-tenant	Assume Tenant	session cookie (login) / none
POST	/api/auth/login	Login	session cookie (login) / none
POST	/api/auth/logout	Logout	session cookie (login) / none
GET	/api/auth/me	Me	session cookie (login) / none
POST	/api/auth/password/change	Password Change	session cookie (login) / none

auth-admin

Method	Path	Summary	Auth
POST	/api/mssp/users/{user_id}/password/reset	Admin Reset	session cookie

authz-facts-mssp

Method	Path	Summary	Auth
POST	/api/mssp/tenants/{tenant_id}/authorization/answer	Mssp Answer Authorization	session cookie
GET	/api/mssp/tenants/{tenant_id}/authorization/facts	Mssp List Facts	session cookie
POST	/api/mssp/tenants/{tenant_id}/authorization/facts	Mssp Create Fact	session cookie
POST	/api/mssp/tenants/{tenant_id}/authorization/facts/{fact_id}/review	Mssp Review Fact	session cookie
POST	/api/mssp/tenants/{tenant_id}/authorization/facts/{fact_id}/revoke	Mssp Revoke Fact	session cookie

chat

Method	Path	Summary	Auth
GET	/api/chat/conversations	List Conversations	session cookie
POST	/api/chat/conversations	Create Conversation	session cookie
GET	/api/chat/conversations/{conv_id}	Get Conversation	session cookie
DELETE	/api/chat/conversations/{conv_id}	Delete Conversation	session cookie
POST	/api/chat/conversations/{conv_id}/messages	Post Message	session cookie
POST	/api/chat/conversations/{conv_id}/messages/{msg_id}/confirm	Confirm Action	session cookie
POST	/api/chat/conversations/{conv_id}/stop	Stop Conversation	session cookie

health

Method	Path	Summary	Auth
GET	/health/live	Live	none (public)
GET	/health/ready	Ready	none (public)

internal-adapter

Method	Path	Summary	Auth
GET	/api/internal/adapter/checkpoint	Get Checkpoint	service JWT (adapter token)
PUT	/api/internal/adapter/checkpoint	Put Checkpoint	service JWT (adapter token)
GET	/api/internal/adapter/config	Fetch Config	service JWT (adapter token)
POST	/api/internal/adapter/events	Ingest Events	service JWT (adapter token)
POST	/api/internal/adapter/heartbeat	Heartbeat	service JWT (adapter token)

internal-authorization

Method	Path	Summary	Auth
GET	/api/internal/authorization/facts	List Facts	session cookie
POST	/api/internal/authorization/facts	Submit Facts	session cookie
POST	/api/internal/authorization/facts/{fact_id}/revoke	Revoke	session cookie

internal-worker

Method	Path	Summary	Auth
POST	/api/internal/worker/runs/{run_id}/complete	Complete Run	service JWT (worker token)
POST	/api/internal/worker/runs/{run_id}/heartbeat	Heartbeat Run	service JWT (worker token)
POST	/api/internal/worker/runs/claim	Claim Run	service JWT (worker token)

investigations-bridge

Method	Path	Summary	Auth
GET	/api/investigations	List Investigations	session cookie
GET	/api/investigations/{investigation_id}	Get Investigation	session cookie
POST	/api/investigations/{investigation_id}/cancel	Post Cancel Investigation	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/investigations/{investigation_id}/events	Get Events	session cookie

ir-alerts

Method	Path	Summary	Auth
GET	/api/mssp/alerts	List Alerts	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)

ir-engagements

Method	Path	Summary	Auth
GET	/api/mssp/tenants/{tenant_id}/engagements	List Engagements Route	session cookie
POST	/api/mssp/tenants/{tenant_id}/engagements	Declare Engagement Route	session cookie
POST	/api/mssp/tenants/{tenant_id}/engagements/{engagement_id}/revoke	Revoke Engagement Route	session cookie

ir-integrations

Method	Path	Summary	Auth
GET	/api/mssp/tenants/{tenant_id}/integrations	Get Integrations	session (roles: mssp_admin / platform_admin)
PATCH	/api/mssp/tenants/{tenant_id}/integrations	Patch Integrations	session (roles: mssp_admin / platform_admin)

ir-mssp

Method	Path	Summary	Auth
GET	/api/mssp/investigations	List Cases Mssp	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/mssp/investigations/{investigation_id}	Get Case Mssp	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/mssp/investigations/{investigation_id}/events	List Case Events Mssp	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
PATCH	/api/mssp/investigations/{investigation_id}/facts	Patch Case Facts	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
POST	/api/mssp/investigations/{investigation_id}/messages	Post Analyst Message	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)

ir-playbooks

Method	Path	Summary	Auth
GET	/api/mssp/playbooks	List Triage Policies Route	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/mssp/tenants/{tenant_id}/playbooks	List Authored Triage Policies Route	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
POST	/api/mssp/tenants/{tenant_id}/playbooks	Create Authored Triage Policy Route	session (roles: mssp_admin / platform_admin)
PUT	/api/mssp/tenants/{tenant_id}/playbooks/{triage_policy_id}	Update Authored Triage Policy Route	session (roles: mssp_admin / platform_admin)
DELETE	/api/mssp/tenants/{tenant_id}/playbooks/{triage_policy_id}	Retire Authored Triage Policy Route	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/{tenant_id}/playbooks/{triage_policy_id}/activate	Activate Authored Triage Policy Route	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/{tenant_id}/playbooks/{triage_policy_id}/deactivate	Deactivate Authored Triage Policy Route	session (roles: mssp_admin / platform_admin)
GET	/api/mssp/tenants/{tenant_id}/playbooks/{triage_policy_id}/export	Export Authored Triage Policy Route	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/mssp/tenants/{tenant_id}/triage-policies	List Authored Triage Policies Route	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
POST	/api/mssp/tenants/{tenant_id}/triage-policies	Create Authored Triage Policy Route	session (roles: mssp_admin / platform_admin)
PUT	/api/mssp/tenants/{tenant_id}/triage-policies/{triage_policy_id}	Update Authored Triage Policy Route	session (roles: mssp_admin / platform_admin)
DELETE	/api/mssp/tenants/{tenant_id}/triage-policies/{triage_policy_id}	Retire Authored Triage Policy Route	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/{tenant_id}/triage-policies/{triage_policy_id}/activate	Activate Authored Triage Policy Route	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/{tenant_id}/triage-policies/{triage_policy_id}/deactivate	Deactivate Authored Triage Policy Route	session (roles: mssp_admin / platform_admin)
GET	/api/mssp/tenants/{tenant_id}/triage-policies/{triage_policy_id}/export	Export Authored Triage Policy Route	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)

ir-proposals

Method	Path	Summary	Auth
GET	/api/mssp/proposals	List Pending Proposals	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
POST	/api/mssp/proposals/{proposal_id}/approve	Approve Proposal Route	session cookie
POST	/api/mssp/proposals/{proposal_id}/reject	Reject Proposal Route	session cookie

ir-response-playbooks

Method	Path	Summary	Auth
GET	/api/mssp/tenants/{tenant_id}/response-playbooks	List Authored Response Playbooks Route	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
POST	/api/mssp/tenants/{tenant_id}/response-playbooks	Create Authored Response Playbook Route	session (roles: mssp_admin / platform_admin)
PUT	/api/mssp/tenants/{tenant_id}/response-playbooks/{response_playbook_id}	Update Authored Response Playbook Route	session (roles: mssp_admin / platform_admin)
DELETE	/api/mssp/tenants/{tenant_id}/response-playbooks/{response_playbook_id}	Retire Authored Response Playbook Route	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/{tenant_id}/response-playbooks/{response_playbook_id}/activate	Activate Authored Response Playbook Route	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/{tenant_id}/response-playbooks/{response_playbook_id}/deactivate	Deactivate Authored Response Playbook Route	session (roles: mssp_admin / platform_admin)
GET	/api/mssp/tenants/{tenant_id}/response-playbooks/{response_playbook_id}/export	Export Authored Response Playbook Route	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)

ir-tenant

Method	Path	Summary	Auth
GET	/api/tenant/investigations	List Cases Tenant	tenant session (customer_viewer / tenant_admin / tenant_analyst / tenant_manager)
GET	/api/tenant/investigations/{investigation_id}	Get Case Tenant	tenant session (customer_viewer / tenant_admin / tenant_analyst / tenant_manager)
PATCH	/api/tenant/investigations/{investigation_id}/facts	Tenant Patch Case Facts	tenant session
POST	/api/tenant/investigations/{investigation_id}/messages	Tenant Post Analyst Message	tenant session

ir-triage-policies

Method	Path	Summary	Auth
GET	/api/mssp/triage-policies	List Triage Policies Route	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)

l2-agent

Method	Path	Summary	Auth
POST	/api/agent/heartbeat	Heartbeat	L2 agent install token (bearer)
POST	/api/agent/jobs:claim	Claim Job	L2 agent install token (bearer)
POST	/api/agent/jobs/{job_id}/complete	Complete Job	L2 agent install token (bearer)
POST	/api/agent/jobs/{job_id}/events	Post Event	L2 agent install token (bearer)
POST	/api/agent/register	Register	L2 agent install token (bearer)

legacy-stubs

Method	Path	Summary	Auth
GET	/api/analytics/ai-behavior	Analytics Ai Behavior	session cookie
GET	/api/analytics/human-review	Analytics Human Review	session cookie
GET	/api/analytics/kpis	Analytics Kpis	session cookie
GET	/api/analytics/outcomes	Analytics Outcomes	session cookie
GET	/api/analytics/summary	Analytics Summary	session cookie
GET	/api/audit	Audit List	session cookie
GET	/api/audit/event-types	Audit Event Types	session cookie
GET	/api/audit/investigation/{investigation_id}	Audit Investigation	session cookie
GET	/api/audit/stats	Audit Stats	session cookie
GET	/api/events/stream	Events Stream	session cookie
GET	/api/review/{review_id}	Review Detail	session cookie
POST	/api/review/{review_id}/approve	Review Approve	session cookie
POST	/api/review/{review_id}/expire	Review Expire	session cookie
POST	/api/review/{review_id}/reject	Review Reject	session cookie
POST	/api/review/{review_id}/request-info	Review Request Info	session cookie
GET	/api/review/pending	Review Pending	session cookie
GET	/api/settings	Settings Get	session cookie

metrics-bridge

Method	Path	Summary	Auth
GET	/api/metrics/hourly	Hourly	session cookie
GET	/api/metrics/overview	Overview	session cookie

mssp-analytics

Method	Path	Summary	Auth
GET	/api/mssp/analytics/heatmap	Heatmap	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/mssp/analytics/ranking	Ranking	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/mssp/analytics/trends	Trends	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)

mssp-dashboard

Method	Path	Summary	Auth
GET	/api/mssp/dashboard/open-by-tenant	Open By Tenant	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/mssp/dashboard/pending-reviews	Pending Reviews	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/mssp/dashboard/repeated-iocs	Repeated Iocs	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/mssp/dashboard/stuck-investigations	Stuck Investigations	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/mssp/dashboard/tenant-health	Tenant Health	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)

mssp-tenant-branding

Method	Path	Summary	Auth
PATCH	/api/mssp/tenants/{tenant_id}/branding	Update Tenant Branding	session (roles: mssp_admin / platform_admin)

mssp-tenant-llm

Method	Path	Summary	Auth
GET	/api/mssp/tenants/{tenant_id}/llm	Get Tenant Llm	session (roles: mssp_admin / platform_admin)
PATCH	/api/mssp/tenants/{tenant_id}/llm	Update Tenant Llm	session (roles: mssp_admin / platform_admin)
DELETE	/api/mssp/tenants/{tenant_id}/llm/api-key	Clear Tenant Llm Api Key	session (roles: mssp_admin / platform_admin)

mssp-tenants

Method	Path	Summary	Auth
GET	/api/mssp/tenants	List Tenants	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
POST	/api/mssp/tenants	Create Tenant	session (roles: mssp_admin / platform_admin)
GET	/api/mssp/tenants/{tenant_id}	Get Tenant	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
POST	/api/mssp/tenants/{tenant_id}:decommission	Decommission Tenant	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/{tenant_id}:issue-agent	Issue Agent	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/{tenant_id}:resume	Resume Tenant	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/{tenant_id}:retry	Retry Provisioning	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/{tenant_id}:retry-install	Retry Install	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/{tenant_id}:suspend	Suspend Tenant	session (roles: mssp_admin / platform_admin)
GET	/api/mssp/tenants/{tenant_id}/adapter-status	Get Tenant Adapter Status	session (roles: mssp_admin / platform_admin)
GET	/api/mssp/tenants/{tenant_id}/events	List Events	session (roles: analyst / mssp_admin / mssp_manager / platform_admin)
GET	/api/mssp/tenants/{tenant_id}/external-siem	Get Tenant External Siem	session (roles: mssp_admin / platform_admin)
PATCH	/api/mssp/tenants/{tenant_id}/external-siem	Update Tenant External Siem	session (roles: mssp_admin / platform_admin)
POST	/api/mssp/tenants/onboard	Onboard Tenant	session (roles: mssp_admin / platform_admin)

mssp-users

Method	Path	Summary	Auth
GET	/api/mssp/users	List Mssp Users	session cookie
POST	/api/mssp/users	Create Mssp User	session cookie
PATCH	/api/mssp/users/{user_id}	Update Mssp User	session cookie
POST	/api/mssp/users/{user_id}/deactivate	Deactivate Mssp User	session cookie

public-tenant

Method	Path	Summary	Auth
GET	/api/public/mssp-by-slug/{slug}	Mssp By Slug	none (public)
GET	/api/public/scope-by-slug/{slug}	Scope By Slug	none (public)
GET	/api/public/tenant-by-slug/{slug}	Tenant By Slug	none (public)

tenant-authz-facts

Method	Path	Summary	Auth
GET	/api/tenant/authorization/facts	Tenant List Own Facts	tenant session
POST	/api/tenant/authorization/facts	Tenant Assert Fact	tenant session

tenant-branding

Method	Path	Summary	Auth
GET	/api/tenant/branding	Get Own Branding	tenant session (customer_viewer / tenant_admin / tenant_analyst / tenant_manager)

tenant-engagements

Method	Path	Summary	Auth
GET	/api/tenant/engagements	Tenant List Engagements Route	tenant session
POST	/api/tenant/engagements	Tenant Declare Engagement Route	tenant session
POST	/api/tenant/engagements/{engagement_id}/revoke	Tenant Revoke Engagement Route	tenant session

tenant-llm

Method	Path	Summary	Auth
GET	/api/tenant/llm	Tenant Get Llm	tenant session (tenant_admin)
PUT	/api/tenant/llm/api-key	Tenant Put Llm Key	tenant session (tenant_admin)
DELETE	/api/tenant/llm/api-key	Tenant Clear Llm Key	tenant session (tenant_admin)

tenant-users

Method	Path	Summary	Auth
GET	/api/tenant/users	List Tenant Users	tenant session
POST	/api/tenant/users	Create Tenant User	tenant session
PATCH	/api/tenant/users/{user_id}	Update Tenant User	tenant session
POST	/api/tenant/users/{user_id}/deactivate	Deactivate Tenant User	tenant session

Esquema de autenticación

Los navegadores usan una session cookie establecida por POST /api/auth/login. Los clientes programáticos pueden:

1. Ejecutar el flujo de login (preferido para scripts de vida corta):

   curl -c jar -X POST https://mssp.../api/auth/login \
     -H 'Content-Type: application/json' \
     -d '{"email":"admin@example","password":"..."}'
   curl -b jar https://mssp.../api/mssp/tenants

2. Emitir un token de API de larga vida (planificado; aún no expuesto en la UI). Hoy, los únicos llamadores sin cookie son los pods adapter y runs-worker por tenant, que se autentican en /api/internal/* con tokens con alcance de tenant que la API acuña y rota (ver Endpoints internos).

En SOCTALK_AUTH_MODE=proxy, la API confía en los headers upstream X-Forwarded-User / X-Forwarded-Email / X-Forwarded-Groups y toda la superficie de autenticación de sesión se desmonta; /api/auth/* (login, logout, me, assume-tenant, password/change) y/api/mssp/users/{id}/password/reset devuelven 404 (no 405). Tu IdP es dueño de la superficie de identidad.

CSRF

El CSRF se aplica de forma global, no por prefijo: internal_session_middleware valida el header Origin / Referer en cada solicitud que modifica estado (POST / PUT / PATCH / DELETE) que lleva la session cookie. Es validación de header, no un token de cookie de doble envío (ese patrón apareció en borradores anteriores, pero el runtime usa validación de header). Los orígenes aceptados provienen de SOCTALK_PUBLIC_ORIGIN (y SOCTALK_PUBLIC_ORIGIN_BASE para hosts de cliente con comodín de slug), que el chart deriva de ingress.hostnames. Las solicitudes que no llevan session cookie (p. ej. las llamadas con token bearer del adapter/worker, o la propia solicitud de login) están exentas. Los navegadores envían Origin automáticamente; los clientes que no son navegadores pueden:

• Hacer coincidir Origin con uno de los hostnames aceptados, o
• Establecer Host: <accepted-hostname> + Origin: https://<accepted-hostname> independientemente del destino TCP real (el paso de onboarding de firstboot.sh usa este truco).

Flujos comunes

Dar de alta un tenant

curl -b jar -X POST https://mssp.../api/mssp/tenants/onboard \
  -H 'Content-Type: application/json' \
  -d '{
    "slug": "acme-corp",
    "display_name": "Acme Corp",
    "profile": "persistent"
  }'

profile se valida en el servidor contra ^(poc|persistent|provided)$. Ver ciclo de vida del tenant / perfiles para la semántica de cada valor. Para provided (BYO-Wazuh), el payload requiere adicionalmente un objeto external_siem (URL del indexer, URL de la API del Manager, credenciales de basic-auth) más un llm_api_key por tenant; el servidor devuelve 422 con errores a nivel de campo si falta alguno.

Devuelve 202 con el ID del nuevo tenant. Observa GET /api/mssp/tenants/{id} para ver las transiciones de estado, o consulta GET /api/mssp/tenants/{id}/events para la lista de eventos del ciclo de vida. (/api/events/stream existe pero en esta versión solo emite pings de keep-alive.)

Obtener el log de auditoría

curl -b jar 'https://mssp.../api/audit?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z&event_type=review.completed&page=1&page_size=50'

El router de auditoría es de nivel superior (/api/audit), no está bajo /api/mssp/. Filtros: start_date / end_date (ISO 8601), event_type, aggregate_type e investigation_id. Los resultados se paginan por offset con page / page_size.

Enviar una decisión de revisión humana

El router de revisión expone un endpoint por decisión (no hay una única ruta /decision). Elige el que corresponda:

# Aprobar — el campo del payload es `feedback` (texto libre), no `rationale`
curl -b jar -X POST https://mssp.../api/review/<review-id>/approve \
  -H 'Content-Type: application/json' \
  -d '{"feedback":"Confirmed brute-force pattern."}'

# Rechazar — cierra el caso como auto_closed_fp; `feedback` es opcional
curl -b jar -X POST https://mssp.../api/review/<review-id>/reject \
  -d '{"feedback":"Looks like a known scanner; benign."}'

# Se necesita más información — el payload es `questions: list[str]` (cada uno se renderiza como una viñeta)
curl -b jar -X POST https://mssp.../api/review/<review-id>/request-info \
  -d '{"questions":["What is the source IP geo?","Any prior alerts on this user?"]}'

# Expirar — retira una revisión pendiente sin veredicto (razón opcional)
curl -b jar -X POST https://mssp.../api/review/<review-id>/expire \
  -d '{"reason":"superseded by newer investigation"}'

Las cuatro devuelven 409 si la revisión ya no está pending.

Para las propuestas de IR (la superficie de gestión de casos), los endpoints equivalentes están bajo /api/mssp/proposals/{id}/approve y /api/mssp/proposals/{id}/reject.

Transmitir eventos

curl -N -b jar 'https://mssp.../api/events/stream'

Server-Sent Events. En esta versión el stream solo emite pings de keep-alive (un ping aproximadamente cada 25 s); la difusión de eventos de dominio (actualizaciones de investigaciones, ciclo de vida de tenants, etc.) está en el roadmap. Trata el endpoint como una prueba de conectividad a nivel de cable por ahora.

Generar un cliente de Python

El esquema se genera limpiamente, así que la forma más rápida de llamar a la API desde Python es generar un cliente tipado con openapi-python-client en lugar de armar solicitudes a mano. Aquí está de principio a fin, leyendo investigaciones.

1. Generar + instalar el cliente

pip install openapi-python-client
openapi-python-client generate \
  --url https://mssp.your-mssp.example/api/openapi.json --meta setup
pip install ./soc-talk-v1-client   # el nombre del paquete deriva del título del esquema

2. Consumir investigaciones

import httpx
from soc_talk_v1_client import Client
from soc_talk_v1_client.api.investigations_bridge import (
    list_investigations_api_investigations_get as list_investigations,
    get_investigation_api_investigations_investigation_id_get as get_investigation,
)

BASE = "https://mssp.your-mssp.example"

# 1. Inicia sesión para obtener una session cookie (las rutas de investigaciones usan una sesión).
with httpx.Client(base_url=BASE) as h:
    h.post("/api/auth/login",
           json={"email": "admin@example", "password": "..."}).raise_for_status()
    session = h.cookies["soctalk_session"]

# 2. Maneja el cliente tipado generado con esa cookie.
client = Client(base_url=BASE, cookies={"soctalk_session": session})

page = list_investigations.sync(client=client, page=1, page_size=5)  # -> InvestigationList
print(f"{page.total} investigations")
for inv in page.items:                                               # -> Investigation
    print(inv.id, inv.status, inv.max_severity, inv.title)

detail = get_investigation.sync(client=client, investigation_id=str(page.items[0].id))
print(detail.phase, detail.alert_count, detail.verdict_decision)

Las funciones de endpoint se nombran según el operationId que FastAPI deriva de la ruta (list_investigations_api_investigations_get); asígnales un alias al importarlas, como arriba, para mayor legibilidad. sync() devuelve el modelo deserializado (InvestigationList, cuyos .items son Investigation); sync_detailed() devuelve el Response en bruto con el código de estado si lo necesitas.

Una versión ejecutable, generar, iniciar sesión, listar + leer, se distribuye como la prueba de humo de codegen tests/e2e/smoke_openapi_client.py, que el pipeline de despliegue ejecuta contra la API en vivo, de modo que un esquema que deja de generar un cliente funcional hace fallar la build.

Endpoints internos (/api/internal/*)

Usados por el adapter y el runs-worker por tenant (ver los grupos internal-adapter e internal-worker en el catálogo de arriba). No son para consumo humano; se listan para que los MSSP puedan ver qué hacen esos pods.

Cada llamada lleva un token con alcance de tenant que la API acuña en el aprovisionamiento y auto-renueva antes de que expire (los tokens de adapter viven 7 días, los de worker 30 días; el plano de control los vuelve a acuñar bien dentro de esa ventana). Los tokens están vinculados al tenant; un adapter solo puede actuar sobre las URLs de su propio tenant.

Límites de tasa

La API en sí no impone límites de tasa por ruta en esta versión. Usa la capa de ingress para el rate limiting global (middleware de Traefik, anotaciones de ingress-nginx) si lo necesitas.

Versionado

El documento OpenAPI lleva la versión de la app. Apuntamos a cambios aditivos dentro de una minor; cambios que rompen compatibilidad solo en un salto de major. Las notas de la versión señalan cada cambio que afecta a la API.

Punteros al código fuente

Todos los routers viven bajo src/soctalk/core/api/.

Concepto	Archivo
Router de auth + middleware de sesión	core/api/auth.py, core/auth/middleware.py
Ciclo de vida del tenant MSSP	core/api/tenants.py
Configuración de LLM por tenant	core/api/llm_config.py
Investigaciones / IR / propuestas	core/api/investigations_bridge.py, core/api/ir.py
Auditoría / revisión / analítica / configuración / eventos (stubs)	core/api/legacy_stubs.py
Chat	core/api/chat.py
Rutas de worker (internas)	core/api/worker_runs.py
Rutas de adapter (internas)	core/api/adapter.py
Generador de OpenAPI	scripts/dump_openapi.py