Referencia de la API de Jenova Agent

URL base: https://api.jenova.ai/v1

Autenticación: Token Bearer en el encabezado Authorization

Tabla de contenido

• Descripción general
• Guía de inicio rápido
• Conceptos básicos
• Autenticación
• Puntos de conexión de la API
  • Mensajes
  • Sesiones
  • Operaciones
  • Créditos
  • Agentes
  • Modelos
  • Documentación
• Transmisión (SSE)
• Integración con servidor MCP
• Facturación
• Límites de solicitudes
• Manejo de errores
• Paginación
• Localización
• Privacidad y datos
• Soporte

Descripción general

Ejecuta agentes personalizados en tu producto o flujo de trabajo en cuestión de minutos. Configura tus agentes para cualquier tarea, elige el modelo y las herramientas que quieras, y deja que Jenova se encargue del harness de agentes, la base de datos y el escalado.

El stack completo de agentes:

• Harness de agentes gestionado: Entra una llamada, sale el trabajo terminado. Tu agente investiga, razona, llama a las herramientas y genera los archivos —exactamente como lo indicas.
• Contexto y memoria sin límites: La gestión del contexto basada en RAG y el seguimiento propietario del estado de la sesión permiten una memoria ilimitada dentro de cada conversación.
• Biblioteca de herramientas y MCP: Conéctate a nuestra biblioteca de 30+ herramientas y servidores MCP, como búsqueda, generación de imágenes, correo electrónico y más, o integra tus propios servidores MCP.
• Cambia a cualquier modelo sin fricciones: Despliega modelos de OpenAI, Anthropic, Google, xAI o de los principales proveedores de código abierto, y cambia de modelo con un solo parámetro.
• Conocimiento y RAG gestionados: Jenova gestiona el pipeline de RAG de extremo a extremo —chunking, indexación, almacenamiento y recuperación.
• Probada a gran escala: Despliega sobre una infraestructura probada en combate que ejecuta cientos de agentes activos en producción. Cero clústeres que aprovisionar, escalar o mantener.

Guía de inicio rápido

1. Obtenga su clave de API

Genere una Clave de API desde el Panel de control para desarrolladores en www.jenova.ai/platform. Las claves utilizan el formato jnv_sk_* y se envían como tokens Bearer.

2. Elija o cree un Agente

Elija un Agente prediseñado de la plataforma, o cree un Agente personalizado en el Panel de control con instrucciones, configuración de Modelo, archivos de Base de conocimientos, Herramientas y servidores MCP.

3. Envíe su primer Mensaje

Cree una Sesión y envíe un Mensaje en una sola llamada:

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "What can you help me with?"
  }'

La respuesta se transmite de vuelta como Server-Sent Events:

event: stream_started
data: {"session_id":"ses_xyz789","run_id":"run_abc123","agent":"my-support-agent"}

event: stream_delta
data: {"session_id":"ses_xyz789","run_id":"run_abc123","chunk_content":"I can help you with ","seq":1}

event: stream_ended
data: {"session_id":"ses_xyz789","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Capture session_id de stream_started para solicitudes posteriores. Para respuestas JSON síncronas, consulte Enviar Mensaje.

Conceptos básicos

Agente

Un Agente de IA con el que usted interactúa a través de la API. Cada Agente tiene un slug único (por ejemplo, my-support-agent) que se utiliza como el valor agent en las llamadas a la API.

• Prediseñado: Seleccione entre los Agentes existentes en la plataforma.
• Personalizado: Configure el suyo propio en el Panel de control con instrucciones, Modelo, Base de conocimientos, Herramientas y servidores MCP.

Sesión

Un hilo de conversación independiente entre un Usuario final y un Agente.

• Identificador: ID con prefijo (por ejemplo, ses_abc123).
• Alcance: Pueden existir varias Sesiones para el mismo Agente y Usuario final, cada una con un estado de conversación independiente.
• Ciclo de vida: Las Sesiones persisten indefinidamente hasta que se eliminan mediante la API. Para tareas puntuales que no necesitan una Sesión, use POST /messages con ephemeral: true.
• Aislamiento de plataforma: Las Sesiones de la API son independientes de las conversaciones en la aplicación web de Jenova. Los Usuarios finales, el historial de Sesiones y la Facturación son independientes entre la API y la aplicación web.

Mensaje

Una entrada individual en el historial de conversación de una Sesión, devuelta por los puntos de conexión de Mensajes. Cada Mensaje incluye un objeto from estructurado con type (user o agent) y name, además de un type de Mensaje:

• external - un Mensaje de conversación destinado a mostrarse como contenido de chat.
• internal - un Mensaje opcional que representa los pasos de trabajo del Agente durante una Ejecución, como llamadas a Herramientas o recuperación.

Ejecución

Una única ejecución de Agente creada al enviar un Mensaje. Una Ejecución tiene un run_id, puede transmitir Eventos mientras está activa y puede producir uno o más Mensajes completados. Cada Sesión solo puede tener una Ejecución activa a la vez.

Usuario final

El campo user asocia las Sesiones a un Usuario final dentro de su aplicación. Use un ID opaco y estable, como su ID de usuario interno o un UUID. Evite correos electrónicos u otra información de identificación personal, a menos que su aplicación lo requiera. Las Sesiones creadas con el mismo valor de user se agrupan entre sí, lo que permite listar Sesiones por usuario.

Si se omite user, la Sesión queda asociada a su cuenta de desarrollador y no podrá filtrarse posteriormente por Usuario final. Envíe user en producción.

En las solicitudes sobre Sesiones existentes (cualquier punto de conexión con {session_id} en su ruta), user funciona como una verificación opcional de propiedad. Si lo proporciona, debe coincidir con el valor de user utilizado al crear la Sesión; de lo contrario, la API devuelve 404 session_not_owned. Envíelo como Parámetro de consulta en las solicitudes GET y DELETE, y en el cuerpo JSON en las solicitudes POST y PATCH. Un Parámetro de consulta user en POST o PATCH devuelve 400 bad_request.

Autenticación

Autentique cada solicitud con un token Bearer en el encabezado Authorization:

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Las claves de API se generan desde el panel de control para desarrolladores.

User-Agent es opcional. Los SDKs pueden configurarlo con fines de diagnóstico, pero la API no lo requiere.

Formato de clave: Las claves comienzan con el prefijo jnv_sk_ seguido de una cadena aleatoria codificada en base62.

Límites: Cada cuenta de desarrollador puede tener hasta 10 claves de API activas.

Puntos de conexión de la API

Mensajes

El envío de Mensajes es la ruta principal de la API. Use POST /messages para el primer Mensaje; este crea la Sesión e inicia la Ejecución en una sola solicitud. Use POST /sessions/{session_id}/messages al continuar una Sesión capturada mediante su session_id.

Enviar Mensaje

POST /messages

Crea una Sesión persistente y envía el primer Mensaje en una única solicitud. Establezca ephemeral: true para una solicitud de una sola vez con Transmisión que no devuelve un ID de Sesión y no se puede continuar. Sus datos se eliminan poco después de que se complete la solicitud.

Cuerpo de la solicitud

Ejemplo - Transmisión (predeterminado)

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account"
  }'

La respuesta es un flujo SSE (consulte Transmisión (SSE) para conocer el formato de los Eventos). Las solicitudes persistentes incluyen el nuevo session_id; las solicitudes con ephemeral: true omiten session_id y deben usar Transmisión.

Ejemplo - JSON (sin Transmisión)

curl -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account",
    "stream": false
  }'

Respuesta

Las respuestas con Transmisión emiten los Eventos SSE documentados en Transmisión (SSE). Las respuestas sin Transmisión devuelven el objeto de Mensaje con stop_reason y usage para la solicitud, como se muestra en Continuar Sesión. stop_reason es end_run, o user_cancelled si la Ejecución se canceló después de que el Agente produjera un Mensaje.

Si la Ejecución se cancela antes de que el Agente produzca un Mensaje, la API devuelve 200 OK con status: "cancelled", session_id, run_id, stop_reason: "user_cancelled" y usage.

Si una Ejecución sin Transmisión sigue procesándose después de 90 segundos, la API devuelve 202 Accepted con status: "processing", session_id, run_id y un message legible para humanos. La Ejecución continúa después de la respuesta o de la desconexión del cliente; verifique los Mensajes de la Sesión, o use Transmisión para flujos de trabajo más largos.

Errores

Continuar Sesión

POST /sessions/{session_id}/messages

Envía un Mensaje a una Sesión persistente existente y recibe la respuesta del agente. Las respuestas se transmiten mediante SSE de forma predeterminada; establezca stream: false para JSON.

Cuerpo de la solicitud

Ejemplo - Transmisión (predeterminado)

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?"
  }'

Ejemplo - JSON (sin Transmisión)

curl -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "stream": false
  }'

Respuesta 200 OK

{
  "id": "msg_xyz789",
  "session_id": "ses_abc123",
  "sequence": 4,
  "from": {
    "type": "agent",
    "name": "my-support-agent"
  },
  "type": "external",
  "time": "2026-05-19T10:31:05Z",
  "content": "To reset your password, go to Settings > Security > Change Password...",
  "model": "claude-sonnet-5",
  "files": [],
  "stop_reason": "end_run",
  "usage": {
    "cost": "0.0015"
  }
}

Si la Sesión ya tiene una Ejecución activa o Mensajes en cola, la API devuelve JSON 202 Accepted con status: "queued", session_id, run_id y message_id. El Mensaje del usuario es procesado por la Ejecución activa. Las solicitudes con additional_context devuelven 409 busy en su lugar.

Las respuestas sin Transmisión siguen las mismas reglas que Enviar Mensaje, incluida la respuesta status: "cancelled" cuando la Ejecución se cancela antes de que el Agente produzca un Mensaje.

Errores

Idempotencia

POST /messages, POST /sessions/{session_id}/messages y POST /invoke aceptan un Encabezado opcional Idempotency-Key (máx. 255 caracteres). Utilice una clave única para cada envío lógico de usuario para que los reintentos de red o los envíos duplicados no generen Ejecuciones duplicadas. Las claves se conservan durante 24 horas.

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-user_12345-2026-05-19T10:30:00Z" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello"
  }'

Sin transmisión: Reintentar devuelve la Respuesta guardada con el Encabezado Idempotent-Replayed: true, incluidos los errores devueltos después de que la solicitud comenzara a procesarse. Una Respuesta 202 Accepted guardada se reproduce sin cambios; utilice Obtener estado de Ejecución o Listar Mensajes para verificar el resultado. Las solicitudes rechazadas antes de que comience el procesamiento, como los errores de validación o de créditos, no se guardan, por lo que un reintento se evalúa de nuevo.

Transmisión: El flujo no se reproduce nuevamente. Para POST /messages y POST /sessions/{session_id}/messages, reintentar mientras se está ejecutando o después de completarse devuelve un error de idempotencia con el run_id original y, para solicitudes persistentes, session_id. Para solicitudes persistentes, utilice Obtener estado de Ejecución para verificar una Ejecución activa, o Listar Mensajes para obtener los resultados persistidos. Los resultados de POST /invoke con Transmisión no se pueden recuperar después de que se cierra el flujo. Los reintentos de POST /invoke devuelven el id original en lugar de run_id y session_id.

Ejemplo de reintento de transmisión completada:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key has already completed. Streaming responses cannot be replayed; use the returned session_id and run_id to retrieve the result."
  },
  "idempotency": {
    "status": "completed",
    "session_id": "ses_abc123",
    "run_id": "run_abc123"
  }
}

Errores de idempotencia

Listar Mensajes

GET /sessions/{session_id}/messages

Devuelve una lista paginada de los mensajes de la sesión. De forma predeterminada, solo se devuelven los mensajes de conversación external. La primera página contiene los mensajes más recientes; dentro de cada página, los mensajes están en orden cronológico (los más antiguos primero). sequence es el número de orden del mensaje dentro de la sesión.

Parámetros de consulta

Ejemplo

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=50" \
  -H "Authorization: Bearer jnv_sk_xxx"

Respuesta 200 OK

{
  "items": [
    {
      "id": "msg_002",
      "session_id": "ses_abc123",
      "sequence": 4,
      "from": {
        "type": "agent",
        "name": "my-support-agent"
      },
      "type": "external",
      "time": "2026-05-19T10:31:05Z",
      "content": "To reset your password, go to Settings > Security...",
      "model": "claude-sonnet-5",
      "stop_reason": "end_run"
    }
  ],
  "next_cursor": "",
  "has_more": false
}

Objeto de Mensaje

Objeto de archivo

Errores

Obtener Mensaje

GET /sessions/{session_id}/messages/{message_id}

Recupera un único mensaje por ID.

Parámetros de consulta

Respuesta 200 OK

Devuelve un único objeto de mensaje con la misma estructura que la respuesta de la lista.

Errores

Archivos adjuntos

Proporcione URLs HTTPS públicamente accesibles en el campo file_urls.

Formatos admitidos

• Imágenes: JPG, JPEG, PNG, WebP
• Documentos: PDF, DOCX, XLSX, PPTX, TXT, CSV, RTF, MD, HTML, XML, JSON, LOG
• Código: JS, TS, TSX, JSX, PY, Java, Go, C, CPP, H, HPP, CS, RB, PHP, RS, Swift, KT, Scala, SQL, CSS, YAML, YML

Las URLs de archivo se obtienen cuando el agente las lee durante la ejecución, no cuando se acepta la solicitud. Una URL que no se puede obtener, o un archivo de más de 20 MB, no se lee; la solicitud en sí no se rechaza.

Al listar mensajes, los archivos adjuntos aparecen en el arreglo files del mensaje.

Contexto adicional

Pase contexto con nombre para un solo Mensaje en additional_context, como detalles de la cuenta del Usuario final. No se guarda en el historial de Mensajes.

Use un nombre descriptivo como customer_profile o order_details.

Un elemento cuyo name o content falte o no sea una cadena devuelve 400 invalid_payload. Otros elementos no válidos devuelven 400 bad_request.

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "additional_context": [
      {
        "name": "customer_profile",
        "content": "Plan: Pro. Last login: 2026-05-18."
      }
    ]
  }'

Sesiones

Las sesiones son conversaciones persistentes entre un usuario final y un agente. La mayoría de las integraciones pueden crearlas de forma implícita con POST /messages.

Crear Sesión

POST /sessions

Crea una sesión persistente vacía vinculada a un agente específico. Utilice esto cuando necesite un ID de sesión antes del primer mensaje; de lo contrario, prefiera POST /messages.

Nota: ephemeral no se acepta en POST /sessions; use POST /messages con ephemeral: true para solicitudes puntuales.

Cuerpo de la solicitud

Ejemplo

curl -X POST https://api.jenova.ai/v1/sessions \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "session_name": "Billing inquiry"
  }'

Respuesta 201 Created

{
  "id": "ses_abc123",
  "session_name": "Billing inquiry",
  "agent": "my-support-agent",
  "user": "user_12345",
  "model": "claude-sonnet-5",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:00Z"
}

Objeto de sesión

Errores

Listar Sesiones

GET /sessions

Devuelve una lista paginada de sus sesiones, ordenadas por la más recientemente actualizada.

Parámetros de consulta

Ejemplo

curl "https://api.jenova.ai/v1/sessions?user=user_12345&limit=10" \
  -H "Authorization: Bearer jnv_sk_xxx"

Respuesta 200 OK

{
  "items": [
    {
      "id": "ses_abc123",
      "session_name": "Billing inquiry",
      "agent": "my-support-agent",
      "user": "user_12345",
      "model": "claude-sonnet-5",
      "created_at": "2026-05-19T10:30:00Z",
      "updated_at": "2026-05-19T11:15:00Z"
    }
  ],
  "next_cursor": "2026-05-19T11:15:00Z|ses_abc123",
  "has_more": true
}

Errores

Obtener Sesión

GET /sessions/{session_id}

Recupera una sola sesión por ID.

Parámetros de consulta

Respuesta 200 OK

Devuelve un objeto de sesión.

Errores

Renombrar Sesión

PATCH /sessions/{session_id}

Actualiza el nombre visible de una sesión.

Cuerpo de la solicitud

Respuesta 200 OK

Devuelve el objeto de sesión actualizado.

Errores

Eliminar Sesión

DELETE /sessions/{session_id}

Elimina permanentemente una sesión y todos sus mensajes. La sesión no debe tener una ejecución activa.

Respuesta 204 No Content

Errores

Operaciones

Estos puntos de conexión son controles de recuperación y edición para sesiones persistentes. La mayoría de las integraciones solo necesitan Cancelar Ejecución activa; use las demás operaciones cuando desee alterar o recuperar el estado de la sesión de forma intencionada. Todas las operaciones admiten la protección de propiedad opcional user descrita en Usuario final.

Cancelar Ejecución activa

POST /sessions/{session_id}/cancel

Cancela la ejecución activa del agente. Esto no elimina los mensajes que ya se completaron antes de la cancelación.

Cuerpo de la solicitud

Respuesta 204 No Content

Errores

Deshacer Ejecución activa

POST /sessions/{session_id}/undo

Cancela la ejecución activa, espera a que se detenga y luego elimina los mensajes que ya había agregado. No se conserva ninguna salida adicional después de emitir la operación de deshacer.

Cuerpo de la solicitud

Respuesta 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "deleted": ["msg_002", "msg_001"]
}

Si la ejecución se cancela antes de que se complete algún mensaje, deleted es un array vacío.

Errores

Eliminar Mensajes recientes

POST /sessions/{session_id}/messages/delete

Elimina los count Mensajes más recientes de una Sesión inactiva, incluidos los Mensajes internal. Use include=all en Listar Mensajes para verlos. La Sesión no debe tener una Ejecución activa.

Cuerpo de la solicitud

Respuesta 200 OK

{
  "deleted": ["msg_002", "msg_001"]
}

Errores

Bifurcar Sesión

POST /sessions/{session_id}/fork

Crea una nueva Sesión copiando la Sesión de origen hasta un Mensaje específico. La Sesión de origen no debe tener una Ejecución activa.

Cuerpo de la solicitud (opcional)

Respuesta 201 Created

Devuelve el objeto de Sesión recién creado con la misma estructura que la creación de una Sesión.

Errores

Obtener estado de Ejecución

GET /sessions/{session_id}/runs/{run_id}

Devuelve el estado actual de una Ejecución activa. Use esto después de una conexión SSE interrumpida o de una respuesta de idempotencia que devolvió un run_id. Una vez que finalice la Ejecución, obtenga los resultados con GET /sessions/{session_id}/messages.

Respuesta 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "status": "streaming",
  "started_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:06Z",
  "content": "Partial visible response text so far"
}

status es running mientras el Agente trabaja, streaming cuando ya se está produciendo el texto de la respuesta, o ended brevemente después de que finaliza la Ejecución. La respuesta también puede incluir progress_events con la actividad reciente, en el mismo formato que stream_progress. Cuando status es ended o la solicitud devuelve 404 not_found, obtenga los Mensajes de la Sesión.

Errores

Créditos

Obtener saldo

GET /credits/balance

Devuelve su saldo actual de Créditos.

Respuesta 200 OK

{
  "balance": "123.45"
}

Agentes

Cree y edite Agentes personalizados en el Panel de control. Próximamente se ofrecerá compatibilidad con la API para crear y editar Agentes.

Los flujos de trabajo programados o en segundo plano no son compatibles actualmente a través de la API. El Soporte para esta función estará disponible próximamente.

Listar Agentes

GET /agents

Devuelve los agentes disponibles para su cuenta. Utilice el valor agent al crear sesiones o enviar mensajes.

Respuesta 200 OK

{
  "agents": [
    {
      "agent": "jenova",
      "display_name": "Jenova",
      "description": "General-purpose Jenova agent"
    },
    {
      "agent": "my-support-agent",
      "display_name": "Support Agent",
      "description": "Answers customer questions"
    }
  ]
}

Modelos

Listar Modelos

GET /models

Devuelve todos los modelos disponibles para usar en el campo model al enviar mensajes o al llamar a POST /invoke.

Respuesta 200 OK

{
  "models": [
    {
      "id": "claude-opus-4-8",
      "name": "Claude Opus 4.8",
      "thinking_variant": "claude-opus-4-8-thinking"
    },
    {
      "id": "claude-opus-4-8-thinking",
      "name": "Claude Opus 4.8 (Thinking)"
    },
    {
      "id": "claude-sonnet-5",
      "name": "Claude Sonnet 5",
      "thinking_variant": "claude-sonnet-5-thinking"
    }
  ]
}

Los modelos con un thinking_variant admiten razonamiento extendido. Utilice el ID de la variante directamente en el campo model para habilitarlo.

Si no se especifica un model al enviar un mensaje, se utiliza el model de la sesión. Se establece en el modelo predeterminado del agente al crear la sesión.

Invocar Modelo

POST /invoke

Envía un prompt directamente a un Modelo, sin agente, Sesión ni herramientas. Las respuestas se transmiten mediante SSE de forma predeterminada; establezca stream: false para JSON.

Cuerpo de la solicitud

Ejemplo

curl -X POST https://api.jenova.ai/v1/invoke \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "content": "Describe a forest in one sentence.",
    "stream": false
  }'

Respuesta 200 OK

{
  "id": "inv_abc123",
  "model": "claude-sonnet-5",
  "content": "Sunlight filters through tall pines onto a quiet, mossy floor.",
  "usage": {
    "cost": "0.0004"
  }
}

Las respuestas con Transmisión envían stream_started, luego eventos stream_delta mientras el modelo genera texto, y terminan con stream_ended, que incluye usage. Concatene los valores de chunk_content en el orden de seq para construir la respuesta transmitida. Si la solicitud falla, se envía stream_error antes de stream_ended. Los eventos incluyen id en lugar de session_id y run_id.

usage.cost es null cuando el costo no está disponible. Si una solicitud sin Transmisión falla después de que se inicia la llamada al modelo, la respuesta de error incluye los campos id y usage de nivel superior.

Las solicitudes con Transmisión están limitadas a 120 minutos. Las solicitudes sin transmisión esperan el resultado hasta 30 minutos en lugar de devolver 202 Accepted, y devuelven un error si el resultado no está listo para entonces.

Errores

Documentación

GET /docs?lang=en
GET /doc?lang=en

Devuelve esta referencia en formato Markdown. Utilice lang para seleccionar el idioma.

Transmisión (SSE)

Cuando se omite stream o se establece en true (valor predeterminado), las respuestas de los mensajes se entregan como Server-Sent Events. Utilice los eventos message_completed para identificar los mensajes listos para recuperar o renderizar.

Tiempo de espera: las conexiones SSE permanecen abiertas hasta que finaliza la ejecución. Las ejecuciones están limitadas a 120 minutos. Las solicitudes de mensajes sin transmisión esperan hasta 90 segundos y luego devuelven 202 Accepted mientras la ejecución continúa. Para POST /invoke sin transmisión, consulte Invocar Modelo.

Encabezados de conexión

Las transmisiones de mensajes establecen estos encabezados:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no
X-Run-Id: run_abc123

X-Run-Id está disponible antes del primer evento SSE. Las transmisiones de POST /invoke no establecen X-Run-Id; use el id de stream_started.

Reconexión y recuperación

Las transmisiones SSE no se reproducen. Si la conexión se interrumpe en una solicitud persistente, utilice los valores capturados session_id y run_id para recuperar el estado:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/runs/run_abc123" \
  -H "Authorization: Bearer jnv_sk_xxx"

Si la ejecución sigue activa, esto devuelve el estado actual, el texto parcial y el progreso reciente. Si devuelve status: "ended" o 404 not_found, la ejecución ya no está activa; recupere los mensajes de la sesión para reconciliar la salida completada:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=20" \
  -H "Authorization: Bearer jnv_sk_xxx"

Formato de trama

Cada trama SSE sigue el formato estándar:

event: <event_type>
data: <json_payload>

Dos saltos de línea terminan cada trama.

Tipos de Evento

Los flujos incluyen eventos de ciclo de vida, delta de texto, pensamiento, progreso, advertencia, finalización de mensaje, conexión MCP, error, final y ping. Algunos tipos de evento solo se envían cuando son relevantes.

En el caso de solicitudes efímeras (ephemeral: true), todos los eventos SSE omiten session_id. Utilice únicamente run_id para correlacionar los eventos dentro de esa única transmisión.

Para la reconciliación final en solicitudes persistentes, espere el Evento stream_ended y luego llame a Listar Mensajes.

Campos comunes en los eventos con ámbito de Ejecución:

stream_started

Se envía una vez cuando comienza la Ejecución.

stream_delta

Se envía repetidamente mientras el Agente genera texto de respuesta visible. Concatene los valores de chunk_content en el orden de seq para construir la respuesta transmitida.

event: stream_delta
data: {"session_id":"ses_abc123","run_id":"run_abc123","chunk_content":"To reset your ","seq":1}

stream_thinking

Se envía repetidamente mientras el Agente emite salida de pensamiento. Utilícelo para un indicador de pensamiento independiente o una vista de trazas; no lo concatene en el texto final de la respuesta.

stream_progress

Informa de actividad visible para el usuario durante la generación, como leer un documento, buscar en la web o esperar una acción del usuario. Estos eventos están destinados a una visualización temporal en la interfaz; ignore los campos desconocidos. Use los mensajes completados como historial de mensajes autoritativo.

Establezca include_progress: false en una solicitud de Mensaje para omitir únicamente stream_progress. Los eventos de ciclo de vida, ping, message_completed, los errores y los eventos terminales se siguen enviando cuando corresponde.

Algunos eventos de progreso pueden incluir url, file_name o server_name como indicaciones opcionales de visualización.

message_completed

Se envía cada vez que un Mensaje está completo y listo para ser recuperado o representado.

Este es un marcador de límite, no el objeto de Mensaje completo. Recupere el Mensaje si necesita su contenido o metadatos.

event: message_completed
data: {"session_id":"ses_abc123","run_id":"run_abc123","message_id":"msg_abc123","sequence":4,"from":{"type":"agent","name":"my-support-agent"},"type":"external"}

mcp_connection

Se envía cuando el agente necesita que el usuario final conecte o autorice uno o más servidores MCP antes de poder continuar. Este evento solo está disponible en modo streaming.

mcp_connection_resolved

Se envía cuando la acción de usuario de conexión MCP se ha resuelto o ha expirado.

No hay campos adicionales además de los campos comunes con ámbito de Ejecución.

warning

Se envía para advertencias no críticas durante una Ejecución.

stream_error

Se envía cuando una Ejecución falla. Puede seguir un Evento final stream_ended con success: false y stop_reason: "error".

stream_ended

Se envía una vez cuando la ejecución finaliza. Este es el evento final de la transmisión.

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Ejemplo de Ejecución cancelada:

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":false,"stop_reason":"user_cancelled","usage":{"cost":"0.0012"}}

ping

Fotogramas de keepalive enviados cada 15 segundos para evitar tiempos de espera de proxy/CDN. Ignórelos en su cliente.

Integración con servidor MCP

Conecte sus agentes a herramientas externas mediante el Model Context Protocol (MCP):

• Servidores MCP administrados por Jenova: servidores alojados por Jenova para búsqueda, recuperación de contenido, generación de documentos y otras capacidades integradas
• Servidores MCP remotos: otros servidores MCP remotos configurados para su Agente

Los servidores MCP deben configurarse en el panel de control al crear o editar su Agente. Para usar su propio servidor MCP, agréguelo a un Agente personalizado y luego invoque a ese Agente a través de la API. La API ejecuta las Herramientas habilitadas en la configuración del Agente; no se requiere configuración adicional en las solicitudes a la API.

Cuando un Agente usa Herramientas MCP durante una respuesta, se envían Eventos de progreso en la transmisión a medida que ocurren:

event: stream_progress
data: {"session_id":"ses_...","run_id":"run_...","state":"running","label":"Searching Google"}

Si el agente necesita que el usuario final conecte o autorice un servidor MCP durante la ejecución, las respuestas en streaming pueden incluir los eventos mcp_connection y mcp_connection_resolved. Presente la lista de servidores de conexión a su usuario final y abra la auth_url proporcionada cuando esté presente. Mantenga abierto el stream SSE mientras el usuario final conecta o autoriza el servidor.

Después de la autorización, Jenova almacena el token, la ventana de autorización muestra una página de finalización y la misma Ejecución continúa automáticamente. El Usuario final no necesita volver a enviar el Mensaje.

Si el usuario final no conecta, autoriza, u omite o silencia antes de user_action_deadline_unix, la ejecución finaliza con stop_reason: "user_action_timeout". También puede cancelar la ejecución activa con POST /sessions/{session_id}/cancel.

Almacene la auth_url en el lado del cliente. Si el cliente se desconecta durante la autorización, la URL sigue siendo válida hasta user_action_deadline_unix. Para solicitudes persistentes, verifique la ejecución con Obtener estado de Ejecución, o recupere los mensajes después de que finalice la ejecución.

Las solicitudes sin streaming (stream: false) no admiten acciones de usuario de conexión MCP; use streaming para agentes que puedan necesitar esta interacción.

Omitir conexión MCP

POST /sessions/{session_id}/mcp/connection/skip

Descarta una acción de usuario de conexión MCP pendiente y permite que la ejecución continúe sin esa conexión.

Para silenciar futuras solicitudes de conexión para un servidor para el mismo usuario final y agente, incluya mcp_server_id y mute. mute acepta una duración como 30m, 24h o 7d, o forever.

Cuerpo de la solicitud

Respuesta 204 No Content

El stream emite mcp_connection_resolved, y luego la ejecución continúa con el mismo run_id.

Errores

Facturación

Todos los costos se deducen de su saldo de Créditos de desarrollador. Consulte el Uso y recargue Créditos en www.jenova.ai/platform.

Precios

El costo de un Mensaje depende de:

• Modelo: distintos Modelos tienen distintos costos por token
• Longitud del contexto: las Sesiones más largas consumen más tokens de entrada por solicitud
• Complejidad del flujo de trabajo: los flujos de trabajo más largos y el uso intensivo de Herramientas (búsqueda web, generación de archivos, análisis de documentos) aumentan el consumo total de tokens

El costo real se devuelve como stream_ended.usage.cost en las solicitudes con Transmisión y como usage.cost en las solicitudes JSON sin Transmisión.

Retenciones de créditos

Cada solicitud POST /messages, POST /sessions/{session_id}/messages y POST /invoke coloca una retención de $0.50 sobre su saldo de Créditos antes de que comience la ejecución. Esto reserva fondos para la solicitud. Un Mensaje en cola dentro de una Ejecución activa (202 Accepted con status: "queued") no genera una retención adicional; el Uso de la Ejecución activa se verifica contra su saldo restante.

Cuando la solicitud se completa, la retención se liquida al costo real y se libera la diferencia. Si el costo real supera la retención, la diferencia también se cobra, por lo que su saldo puede quedar por debajo de cero. Las solicitudes canceladas y fallidas solo se cobran por el Uso ya incurrido. Si una solicitud falla antes de llegar al Modelo, se libera la retención completa.

Debido a las retenciones, su saldo disponible puede aparecer temporalmente más bajo durante las solicitudes en curso. Necesita al menos $0.50 de saldo disponible para una solicitud POST /sessions/{session_id}/messages, POST /messages efímera o POST /invoke. Una solicitud persistente POST /messages también crea una Sesión y necesita al menos $0.51 para cubrir la retención más la tarifa de creación de la Sesión.

Límites de solicitudes

Toda cuenta de desarrollador está sujeta a tres dimensiones de Límite de solicitudes:

Una Ejecución conserva su espacio concurrente hasta que termina, incluso después de una respuesta 202 Accepted o de la desconexión del cliente. Una solicitud POST /invoke conserva su espacio hasta que finaliza, incluso si el cliente se desconecta.

Las solicitudes GET y HEAD no consumen espacios concurrentes. cancel, undo y mcp/connection/skip tampoco consumen espacios concurrentes, por lo que estas operaciones siguen estando disponibles cuando todos los espacios están en uso. Estas solicitudes siguen contando para RPM y RPD.

También se aplica a todas las solicitudes un límite independiente por IP de 1,200 solicitudes cada 60 segundos, que devuelve el mismo error 429 rate_limit_exceeded.

Encabezados de respuesta

Las respuestas autenticadas de la API incluyen encabezados de límite de solicitudes:

Cuando se supera el límite diario, X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset describen en su lugar la ventana diaria.

Cuando se supera un límite, la API devuelve 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later."
  }
}

Manejo de errores

Los errores HTTP inmediatos y los errores de Ejecución sin Transmisión siguen un formato coherente:

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description"
  }
}

Los mensajes de error se localizan según lang o Accept-Language (consulte Localización).

Los errores de Ejecución en Transmisión se entregan como Eventos stream_error. Una Ejecución fallida puede aún enviar un Evento final stream_ended con success: false y stop_reason establecido. Los errores de Ejecución sin Transmisión incluyen un objeto usage de nivel superior; cost es null cuando el costo no está disponible.

Estos errores pueden producirse en cualquier punto de conexión:

Los errores específicos de cada punto de conexión se documentan directamente en cada punto de conexión.

Errores de Ejecución después del inicio

Los errores de Ejecución aparecen después de que se ha aceptado una solicitud de Mensaje. En modo de Transmisión, aparecen como Eventos stream_error y pueden ir seguidos de stream_ended con success: false. En modo sin Transmisión, se devuelven como una respuesta de error en JSON con el Código de estado HTTP que se indica a continuación.

Paginación

Listar Sesiones y Listar Mensajes utilizan paginación basada en cursor:

{
  "items": [],
  "next_cursor": "2026-05-19T11:15:00Z|ses_abc123",
  "has_more": true
}

Pase next_cursor como el Parámetro de consulta cursor para obtener la página siguiente, codificando el valor para URL. Cuando has_more es false, no hay más resultados. Un limit fuera del rango 1-100 o un cursor no válido devuelve 400 bad_request.

Localización

Todos los puntos de conexión aceptan un Parámetro de consulta opcional lang para controlar el idioma de los mensajes de error y de cualquier contenido localizado.

Puede añadir ?lang=xx a cualquier URL de solicitud:

POST /sessions?lang=zh
GET /sessions/ses_abc123/messages?lang=ja

Idiomas admitidos: en, zh, ja, ko, es, fr, de, it, pt, ru, id, th, vi

Privacidad y datos

Jenova no utiliza los prompts, salidas, historial de conversaciones, archivos cargados, instrucciones de Agentes ni Bases de conocimientos de la API para entrenar los Modelos de Jenova.

En el caso de proveedores de Modelos externos, Jenova utiliza canales de API comerciales, configuraciones de cuenta, compromisos contractuales o mecanismos de exclusión destinados a evitar que el contenido de los clientes se utilice para entrenar los Modelos de dichos proveedores.

Jenova almacena y procesa los datos de la API utilizando infraestructura ubicada en Estados Unidos. Los proveedores externos pueden procesar datos en otras jurisdicciones, según se describe en la Política de Privacidad y las Condiciones de Uso.

Para obtener información completa, consulte las Condiciones de Uso, la Política de Privacidad y la Política de Uso.

Soporte

• Panel de control: www.jenova.ai/platform
• Correo electrónico: [email protected]