/v1, autenticada con una clave de API de espacio de trabajo que creas en la consola. Te permite automatizar todo lo que hace el producto (agentes, proyectos, páginas, conocimiento, recursos, marca, tema, uso) y hablar con un agente directamente: recuperación, y un turno generativo headless. Las páginas de endpoints de esta pestaña se generan a partir del documento OpenAPI de wondeya, así que describen exactamente lo que el servidor acepta. Las páginas generadas de endpoints (el grupo Endpoints) se sirven en inglés.
URL base
http://localhost:8080/v1.
Autenticación en una línea
Cada solicitud lleva una clave como token bearer:tenantId, así que una clave solo puede alcanzar su propio espacio de trabajo. Crea una clave y mira el flujo completo en la página de Autenticación.
El modelo
agent (la opción por defecto, que nombra al agente que responde en ella) o bien una página document (que renderiza un cuerpo en markdown, sin agente). Varias páginas pueden compartir un agente, y por eso los agentes son de nivel de espacio de trabajo.
Convenciones
La creación responde201, las transiciones de estado responden 200. Publicar y despublicar una página son endpoints propios (/publish, /unpublish), nunca un campo en el patch de configuración.
Las actualizaciones son parciales y se fusionan. Un PATCH lleva solo lo que cambió. Un patch de tema lleva solo los tokens que cambiaron, pero un token fuera del conjunto cerrado es un 400, nunca un campo ignorado.
La ingesta es asíncrona. POST /v1/knowledge/text y /urls responden 202 con la fuente pending; consulta periódicamente GET /v1/knowledge/sources hasta que esté ready o failed. El código que asuma que la subida es síncrona leerá chunkCount: 0 y parecerá roto.
Las listas se paginan por cursor. Toda lista responde { data, hasMore, nextCursor }; sigue nextCursor como ?after=. Mira Paginación.
Los reintentos son seguros cuando lo pides. Envía un Idempotency-Key en una creación y un reintento repite la primera respuesta en lugar de crear un segundo recurso o gastar un segundo crédito de chat. Mira Idempotencia.
Las URLs firmadas expiran. Las URLs de los recursos están firmadas y son de corta vida (unos 15 minutos). Vuelve a pedir la lista en lugar de cachearlas.
Límites de tasa
Cada solicitud a/v1 tiene límite de tasa por clave, y cada respuesta anuncia el presupuesto tanto en los encabezados X-RateLimit-* como en los encabezados RateLimit del IETF. Superar el límite es un 429 con Retry-After. Mira Límites de tasa.
Errores
Todo error es un documento de problema RFC 9457 (application/problem+json) con un code estable y legible por máquina. Errores los lista y explica sobre qué ramificar tu código.
Versionado
La superficie se versiona en la ruta (/v1). Dentro de v1 los cambios son aditivos (endpoints y campos nuevos, nunca uno eliminado o renombrado), y un cambio incompatible sale como un nuevo /v2. Todo lo que está por retirarse se marca deprecated en estas páginas antes de eliminarse. Mira Versionado.
El servidor MCP es una superficie distinta para un
llamador distinto: se autentica con OAuth 2.1 (un inicio de sesión en el
navegador que tú apruebas), para clientes de IA como Claude. Las claves de API
de máquina son para ESTA API REST.