API

API de Chat Shares

Crea, lista y revoca share links públicos para sesiones de chat.

La API de Chat Shares permite compartir sesiones de AI chat como link público read-only — p. ej. para review de cliente o como evidencia de un análisis del Master Agent. El owner crea vía /v1/chat-shares, el destinatario lee vía /share/{token} (público, noindex). Documentación completa del módulo: Agentic Chat.

Todos los endpoints API autenticados con Sanctum, scope al team.

Endpoints

Method	Endpoint	Descripción
GET	`/v1/chat-shares`	Shares propios (paginado 25/página)
POST	`/v1/chat-shares`	Crear nuevo share link para una sesión propia
GET	`/v1/chat-shares/{id}`	Detalle + stats
PATCH	`/v1/chat-shares/{id}`	Update de settings (incluido `freeze`)
DELETE	`/v1/chat-shares/{id}`	Revocar (soft-delete)
GET	`/v1/chat-shares/{id}/views`	Log de views paginado (anonimizado por GDPR)
GET	`/v1/agentic/sessions/{session}/shares`	Shares de una sesión concreta

POST /v1/chat-shares

Body:

Campo	Obligatorio	Default	Descripción
`session_id`	sí	—	ID de una `AiChatSession` que pertenezca al usuario
`title`	no	—	Título de la share page
`expires_at`	no	+7 días	ISO datetime, debe estar en el futuro
`password`	no	—	mín 4 caracteres — activa el password gate
`max_views`	no	—	Hard cap de views únicas (≥1)
`show_user_messages`	no	`true`	Mostrar bubbles del usuario
`show_assistant_messages`	no	`true`	Mostrar bubbles del assistant
`show_tool_results`	no	`false`	On/off de las cards de tool call — si está off, el destinatario solo ve inputs+outputs
`show_reasoning_steps`	no	`false`	Bloques de reasoning/thinking
`show_uploaded_files`	no	`true`	Files subidos (capturas, PDFs)

Al menos una opción show_* debe ser true, si no la API devuelve 422.

curl -X POST "$BASE/chat-shares" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "session_id": 42,
    "title": "Backlinks-Analyse fuer Kunde X",
    "expires_at": "2026-06-01T00:00:00Z",
    "show_tool_results": true
  }'

Response 201:

{
  "data": {
    "id": 1,
    "token": "f3a9b2c4...",
    "url": "https://rankion.ai/share/f3a9b2c4...",
    "title": "Backlinks-Analyse fuer Kunde X",
    "session_id": 42,
    "expires_at": "2026-06-01T00:00:00Z",
    "frozen_at": null,
    "has_password": false,
    "max_views": null,
    "view_count": 0,
    "unique_viewer_count": 0,
    "last_viewed_at": null,
    "revoked_at": null,
    "status": "active",
    "show_user_messages": true,
    "show_assistant_messages": true,
    "show_tool_results": true,
    "created_at": "2026-05-01T09:14:01Z"
  }
}

PATCH /v1/chat-shares/{id}

Acepta los mismos campos que POST más freeze: bool:

freeze: true — congela el snapshot de contenido. Los cambios posteriores en la sesión origen ya no se ven en el share.
freeze: false — vuelve a live; el share refleja de nuevo la sesión actual.

DELETE /v1/chat-shares/{id}

Soft revoke. Asigna revoked_at — el public link entrega a partir de ese momento 410 Gone. La fila permanece 90 días en la BD (configurable vía CHAT_SHARES_RETENTION_DAYS), luego un job daily prune la borra definitivamente.

Public route (NO está en la API)

Estas rutas no viven bajo /api/v1/ — son HTML público:

Method	Path	Descripción
GET	`/share/{token}`	View HTML read-only, `noindex` vía meta + `X-Robots-Tag` + disallow en `robots.txt`
POST	`/share/{token}/unlock`	Form de password (throttle 5/min) — setea cookie httpOnly path-scoped
GET	`/share/{token}/print`	Variante print-CSS para export PDF

Estadísticas y view log

GET /v1/chat-shares/{id}/views entrega el histórico de views anonimizado por GDPR — IP hash, user agent family, referrer domain, timestamp. Sin datos personales.

curl "$BASE/chat-shares/1/views?per_page=50" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {viewed_at, ua_family, referrer_domain}'

Códigos de status

Code	Significado
201	Share creado
200	List/Detail/Update/Views OK
204	DELETE exitoso
403	La sesión no pertenece al usuario
404	Share o sesión no encontrada
410	Share revocado (solo public route)
422	Ninguna opción `show_*` en `true`, `expires_at` inválido o `password` demasiado corto

Pitfalls

show_tool_results=false es default. Por defecto el destinatario no ve cards de tool call — solo la conversación. Actívalo cuando quieras compartir, p. ej., datos SERP o tablas de backlinks.
freeze no es reversible sin PATCH. Una vez congelado, el snapshot queda fijo — aunque la sesión continúe.
El public link no se revoca por token. La revocación va solo vía DELETE /v1/chat-shares/{id} con auth token del owner.
El throttle de password es duro. 6+ intentos fallidos / minuto → 429 durante 60 s; un segundo intento de bypass alarga el lockout.

Relacionado: Agentic Chat · API de Agentic Plans · API de Auth.

Letzte Aktualisierung: 1 de mayo de 2026