Referencia de API · Sesiones y Mensajes

API de sesiones y mensajes de chat

Crear, listar, renombrar, anclar, marcar con estrella y eliminar sesiones de chat, y gestionar mensajes individuales dentro de ellas — incluyendo historial de ediciones rastreado y deshacer.

← Volver a la documentación Ir a endpoints

Endpoints de sesión

POST /api/v1/sessions

GET /api/v1/sessions

GET /api/v1/sessions/{session_id}/messages

PATCH /api/v1/sessions/{session_id}

DELETE /api/v1/sessions/{session_id}

Endpoints de mensaje

GET /api/v1/messages/{message_id}

PATCH /api/v1/messages/{message_id}

GET /api/v1/messages/{message_id}/history

POST /api/v1/messages/{message_id}/undo

DELETE /api/v1/messages/{message_id}

Crear sesión — Cuerpo de la solicitud

json

{
  "title": "Untitled Chat",
  "kind": "chat",
  "folder_id": null,
  "agent_id": null,
  "metadata": {}
}

workspace_id no se acepta desde el cliente en el entorno de ejecución personal, y se requiere que coincida con el contexto de ejecución del workspace activo — de otro modo nunca se toma como una anulación arbitraria por parte del cliente.

Listar — Parámetros de consulta y respuesta

kindagent_idpinnedlimit (por defecto 50, máximo 200)offset (por defecto 0)

json

{
  "items": [ { "id": "...", "title": "...", "pinned": false, "...": "..." } ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Actualizar sesión (PATCH)

Al menos un campo debe estar presente en el cuerpo de la solicitud — un PATCH vacío es rechazado.

titlepinnedstarredmarked_unread

json

{
  "pinned": true,
  "starred": false
}

Comportamientos de la sesión

Una sesión pertenece exactamente a un propietario (un usuario, opcionalmente asociado a un workspace) — determinado por el contexto de la solicitud autenticada, no por la entrada del cliente.
Eliminar una sesión es una eliminación suave (se establece deleted_at); la sesión y sus mensajes permanecen en la base de datos pero se excluyen de todas las consultas estándar.
GET /sessions/{session_id}/messages devuelve un recuento de mensajes calculado en vivo a partir de los propios mensajes, no un contador en caché.
Los parámetros de ruta session_id y message_id se validan como UUIDs — un ID malformado devuelve un error de validación claro, no un error de servidor.
Las sesiones de demostración del sitio web de marketing están limitadas a 3 por usuario y devuelven 403 una vez alcanzado ese límite.

Historial de ediciones de mensajes y deshacer

Cada edición del contenido o payload de un mensaje se registra antes de aplicar el cambio, preservando la versión anterior.

json

[
  {
    "id": "8f14e...",
    "old_content": "Original message text",
    "old_payload": null,
    "edited_at": "2026-07-30T16:40:00Z"
  }
]

Un mensaje solo puede ser editado o eliminado por el propietario de la sesión a la que pertenece.
Deshacer restaura la versión registrada más reciente y elimina esa entrada del historial — no retrocede más allá de la última edición.
Editar o eliminar un mensaje no ajusta actualmente el campo de recuento de mensajes en caché de la sesión; en su lugar, siempre refleja el recuento en vivo.

Modelos de error

400

Solicitud inválida — incluyendo un cuerpo PATCH vacío o ausencia de cambios detectados.

401

Autenticación faltante o inválida.

404

Sesión o mensaje no encontrado (o no perteneciente al solicitante).

Ejemplos

Crear una sesión

bash

curl -X POST "/api/v1/sessions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Chat", "kind": "chat"}'

Fijar una sesión

bash

curl -X PATCH "/api/v1/sessions/[session_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'

Editar un mensaje

bash

curl -X PATCH "/api/v1/messages/[message_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"content": "Corrected message text"}'

Deshacer la última edición

bash

curl -X POST "/api/v1/messages/[message_id]/undo" \
  -H "Authorization: Bearer [token]"