API v2

La API v2 es una API REST estructurada para administrar agentes y crear experiencias de chat personalizadas. Agrega administración de agentes, chat en streaming, historial de conversaciones, comentarios sobre mensajes, contactos, leads, fuentes, configuraciones y endpoints de entrenamiento.

El acceso a la API requiere un plan Hobby o superior con facturación activa.

URL base

https://your-domain.com/api/v2

Autenticación

Excepto en la verificación de estado (health check), envía la clave de API de tu espacio de trabajo como token bearer:

Authorization: Bearer YOUR_API_KEY

Crea y revoca claves de API desde Configuración > Claves de API.

Formato de respuesta

La mayoría de las respuestas exitosas devuelven un objeto de recurso o un envoltorio data:

{
  "data": []
}

Los endpoints de listado incluyen paginación por cursor:

{
  "data": [],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 0
  }
}

Los errores usan un objeto error estructurado:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Cada respuesta de v2 incluye un encabezado x-request-id. Inclúyelo al contactar a soporte sobre una solicitud a la API.

Alcance de las conversaciones

Los endpoints de conversaciones de solo lectura usan source=api_v2 de forma predeterminada. Configura source=widget para devolver conversaciones del widget y del Playground; las filas del Playground se almacenan con el origen widget. Configura source=all para devolver conversaciones de la API v2, del widget y del Playground. Los resultados siempre se limitan al agente de la cuenta autenticada. Un valor de source inválido o más de un parámetro de consulta source devuelve 400 VALIDATION_INVALID_BODY. La continuación de chat, los reintentos, los comentarios, el listado de mensajes y las lecturas por usuario siguen limitados a las conversaciones de la API v2.

Verificación de estado

GET /api/v2/health

La verificación de estado no requiere autenticación.

Éxito: 200 OK

{
  "status": "ok",
  "timestamp": 1784332800
}

timestamp es la marca de tiempo Unix actual en segundos.

Chat

POST /api/v2/agents/{agentId}/chat

Solicitud:

{
  "message": "What plans do you offer?",
  "conversationId": "optional-existing-conversation-id",
  "userId": "optional-user-id",
  "stream": true
}

Las respuestas en streaming usan Server-Sent Events. El stream incluye los eventos message-start, text-start, text-delta, text-end, message-metadata, finish y [DONE]. Un fallo en el stream o en el hook de finalización emite un evento error con error.code establecido en CHAT_STREAMING_ERROR; este código de protocolo exclusivo de SSE es independiente del catálogo de errores REST estructurado. message-metadata contiene el ID del mensaje del asistente cuando la persistencia se realiza correctamente, además del ID de conversación, el ID de usuario, el motivo de finalización y el uso. Su messageId es null cuando no se persistió ningún mensaje del asistente. Cuando la respuesta se pausa en una acción del lado del cliente, el stream también emite un evento tool-call con { "id", "name", "arguments" }; envía el resultado al endpoint de tool-result para reanudar la conversación — la respuesta a esa solicitud transmite la continuación.

Las respuestas sin streaming devuelven:

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "..." }],
    "pendingToolCall": null,
    "metadata": {
      "userMessageId": "122",
      "conversationId": "abc123",
      "userId": "user_123",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

Los valores data.id y metadata.userMessageId de las respuestas sin streaming son ID de mensaje numéricos serializados como strings, o null cuando el mensaje correspondiente no se persistió. metadata.userId es el ID de usuario proporcionado o almacenado, o null. pendingToolCall es null, salvo que la respuesta se haya pausado en una llamada a una herramienta del lado del cliente; en ese caso contiene { "id", "name", "arguments" } para el endpoint de resultados de herramientas.

Resumen de endpoints

Comentarios

Usa los comentarios para marcar los mensajes del asistente de la API v2 como positive, negative o null. Consulta Conversaciones, mensajes y comentarios para conocer el esquema de la solicitud, la respuesta y el comportamiento de errores.

Paginación

Trata los cursores como tokens opacos devueltos por la API. Reenvía el valor de pagination.cursor sin modificarlo en la siguiente solicitud; no lo construyas ni lo decodifiques.

Contacts también admite search. Leads admite los filtros de fecha y hora ISO 8601 inclusivos createdAfter y createdBefore. Sources admite sourceType con web_crawl, file_upload, text_snippet o qna_entry.

Los formatos de cursor son un detalle interno de implementación. Los clientes deben tratar todos los cursores como opacos y reenviarlos sin modificarlos, sin construirlos ni decodificarlos.

Errores comunes

Consulta el catálogo completo de errores de la API v2 para ver los 27 códigos declarados, los estados HTTP, sus disparadores y los códigos reservados.

Referencia

• Catálogo de errores
• Agentes y configuración
• Conversaciones, mensajes, reintentos y comentarios
• Fuentes y entrenamiento
• Contactos y leads
• Canal de Instagram

Próximos pasos

• Crea una clave de API
• Configura la verificación de identidad
• Revisa los errores de la API v2
• Administra agentes y configuraciones
• Trabaja con conversaciones
• Administra fuentes y entrenamiento
• Administra contactos y leads
• Administra el canal de Instagram