API de sesiones

La misma clave pk_live_… del canal Widget (API) autoriza llamadas directas a la API de sesiones del agente — conversaciones duraderas con stream de eventos, preguntas y aprobaciones que el agente puede plantear, y control de sesión. El widget web usa exactamente esta API por debajo.

Base: https://agents.juryo.ai
Autenticación: cabecera Authorization: Bearer pk_live_…

¿Qué API?

Ambas usan la misma clave. Elige según lo que necesite tu integración:

	API de chat	API de sesiones (esta página)
Forma	Un `POST` por mensaje, la respuesta en la misma llamada	Crear una sesión, enviar turnos, leer un stream de eventos
Respuesta típica	~2–3 segundos	6–11 segundos
Memoria	Sí — envías un id de conversación y guardamos el historial	Sí — id de sesión duradero
Streaming	Opcional (texto plano o stream de eventos)	Stream de eventos NDJSON
El agente te pregunta / pide una aprobación	No en esta superficie	Sí (`input.requested` + `inputResponses`)
Cancelar / limpiar / compactar / reiniciar la conversación	No	Sí
Ideal para	Webs, formularios, bots — cualquier caso conversacional donde importa la velocidad	Integraciones que necesitan aprobaciones, trabajos largos o control de sesión

Si no necesitas los controles de sesión, usa la API de chat.

La clave identifica a tu despacho como inquilino. Cualquier sistema que la presente puede iniciar conversaciones con tu agente — igual que cualquier visitante de tu web puede abrir el widget.

Cambio incompatible (agosto de 2026): la API de sesiones ya no usa tokens de continuación. Al iniciar una sesión ya no se devuelve un continuationToken, y los cuerpos de las peticiones ya no lo aceptan — un mensaje de seguimiento que aún lo envíe falla con 400 Bad Request. Usa el sessionId de la respuesta inicial en la ruta URL de cada seguimiento, control y stream. Consulta Migrar desde tokens de continuación más abajo.

Rutas

Método	Ruta	Propósito
`GET`	`/eve/v1/health`	Comprobar que la API responde (sin autenticación)
`POST`	`/eve/v1/session`	Iniciar una sesión y enviar su primer mensaje
`POST`	`/eve/v1/session/{sessionId}`	Enviar un mensaje de seguimiento
`GET`	`/eve/v1/session/{sessionId}/stream`	Seguir los eventos de la sesión como NDJSON
`POST`	`/eve/v1/session/{sessionId}/cancel`	Cancelar el turno en curso
`POST`	`/eve/v1/session/{sessionId}/clear`	Vaciar el historial de conversación de la sesión
`POST`	`/eve/v1/session/{sessionId}/compact`	Compactar el contexto de la sesión
`POST`	`/eve/v1/session/{sessionId}/reset`	Retirar la sesión de forma permanente

Las rutas de sesión usan únicamente identificadores de sesión duraderos. Crea la sesión explícitamente y usa el ID devuelto en la ruta de cada seguimiento, control y stream.

Iniciar una sesión

curl -X POST https://agents.juryo.ai/eve/v1/session \
  -H 'Authorization: Bearer pk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{"message": "Hola, quiero información sobre una reclamación."}'

{"ok": true, "sessionId": "wrun_A", "status": "accepted"}

sessionId es el identificador permanente de la sesión. Guárdalo — va en la ruta URL de todas las llamadas posteriores. El mismo id se devuelve también en la cabecera x-eve-session-id.
status: "accepted" significa que el mensaje quedó encolado de forma duradera. La respuesta del agente no viene en esta respuesta — léela del stream de eventos.

Enviar un mensaje de seguimiento

Cuando la sesión espera el siguiente mensaje del usuario:

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A \
  -H 'Authorization: Bearer pk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{"message": "Fue un accidente de tráfico."}'

El cuerpo de un seguimiento acepta exactamente uno de message o inputResponses. Usa inputResponses para responder a una pregunta o solicitud de aprobación pendiente del agente (un evento input.requested en el stream):

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A \
  -H 'Authorization: Bearer pk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{"inputResponses": [{"requestId": "req_A", "optionId": "approve"}]}'

Enviar un mensaje a un ID de sesión desconocido o retirado devuelve 409 con {"code": "session_not_active", "error": "The session is no longer active.", "ok": false}. La ruta nunca crea una sesión de reemplazo — inicia una nueva explícitamente con POST /eve/v1/session.

Seguir la respuesta en directo

La sesión emite eventos JSON delimitados por saltos de línea (application/x-ndjson) mientras el agente trabaja — un objeto JSON por línea:

curl -N https://agents.juryo.ai/eve/v1/session/wrun_A/stream \
  -H 'Authorization: Bearer pk_live_TU_CLAVE'

{"type": "turn.started", ...}
{"type": "message.appended", "data": {"messageDelta": "Fue ", ...}}
{"type": "message.completed", "data": {"message": "...", ...}}
{"type": "session.waiting", "data": {"wait": "next-user-message", ...}}

Los eventos sobre los que construir:

message.completed — la respuesta completa del agente para ese turno.
session.waiting — el turno terminó y la sesión está lista para tu siguiente seguimiento.
input.requested — el agente pregunta algo o pide una aprobación; respóndela con inputResponses en la ruta de seguimiento.
turn.failed / session.failed — el turno o la sesión fallaron; data.message lleva el motivo.

Los clientes que no muestran texto incremental pueden ignorar los eventos *.appended y quedarse solo con los *.completed.

Por compatibilidad, el evento session.waiting aún incluye un campo data.continuationToken. Es simplemente el ID de sesión — ignóralo y sigue usando el sessionId que ya tienes.

Gestionar una sesión

Todas las rutas de control son asíncronas: "accepted" significa que la petición quedó encolada de forma duradera, y el resultado se confirma en el stream de eventos. Nunca crean sesiones — un ID de sesión inactivo devuelve "no_active_session" (o "no_active_turn" en cancel). Cancelar el turno en curso (cuerpo vacío, o pasa el turnId de los eventos de ese turno para acotarla):

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A/cancel \
  -H 'Authorization: Bearer pk_live_TU_CLAVE'
# 202 {"ok": true, "sessionId": "wrun_A", "status": "accepted"}

Vaciar el historial de conversación sin reemplazar la sesión (el agente olvida los turnos anteriores; la configuración y el estado duradero permanecen):

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A/clear \
  -H 'Authorization: Bearer pk_live_TU_CLAVE'

Compactar una conversación larga en un resumen para liberar contexto:

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A/compact \
  -H 'Authorization: Bearer pk_live_TU_CLAVE'

Reset retira la sesión de forma permanente — el ID antiguo no puede aceptar más mensajes:

curl -X POST https://agents.juryo.ai/eve/v1/session/wrun_A/reset \
  -H 'Authorization: Bearer pk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{"reason": "Empezar de nuevo"}'
# {"ok": true, "previousSessionId": "wrun_A", "status": "reset"}

Errores

Código	Significado
`400`	Cuerpo mal formado — por ejemplo ambos o ninguno de `message` / `inputResponses`, o el campo antiguo `continuationToken`
`401`	Clave `Authorization` ausente o inválida
`409`	`session_not_active` — el ID de sesión es desconocido o está retirado; inicia una sesión nueva

Los cuerpos de error siguen {"code": "...", "error": "...", "ok": false} con un code estable para tratarlos por código.

Migrar desde tokens de continuación

Las integraciones construidas antes de agosto de 2026 usaban un continuationToken devuelto por la ruta de inicio. La correspondencia con la API actual:

Antes	Ahora
La respuesta de inicio incluía `continuationToken` en el cuerpo	La respuesta de inicio incluye `sessionId` en el cuerpo (y en la cabecera `x-eve-session-id`)
Seguimiento: `POST /eve/v1/session` con `{"continuationToken": "...", "message": "..."}`	Seguimiento: `POST /eve/v1/session/{sessionId}` con `{"message": "..."}`
La sesión se direccionaba con el token en el cuerpo de la petición	La sesión se direcciona con el `sessionId` en la ruta URL — el id no cambia durante toda la vida de la sesión

En resumen: guarda el sessionId de la respuesta inicial, ponlo en la ruta URL y elimina continuationToken de todos los cuerpos de petición.

​¿Qué API?

​Rutas

​Iniciar una sesión

​Enviar un mensaje de seguimiento

​Seguir la respuesta en directo

​Gestionar una sesión

​Errores

​Migrar desde tokens de continuación

¿Qué API?

Rutas

Iniciar una sesión

Enviar un mensaje de seguimiento

Seguir la respuesta en directo

Gestionar una sesión

Errores

Migrar desde tokens de continuación