Referencia de la API › Fundamentos
Visión general de la API
Dirección, autenticación, formato de las solicitudes y respuestas, streaming y convenciones de la API HTTP.
La API de DoubleX Agentes es la misma que usa la app. Con ella creas y configuras agentes, conversas con ellos en streaming, llamas a modelos directamente, usas las herramientas de los conectores, alimentas el Brain, gestionas skills y disparadores y descargas los archivos de Creaciones.
Dirección#
https://doublex.ai/apiTodas las rutas de esta referencia son relativas a esa dirección: GET /api/agents es GET https://doublex.ai/api/agents.
Autenticación#
Envía una clave de API en el encabezado Authorization:
curl https://doublex.ai/api/me -H "Authorization: Bearer $DOUBLEX_API_KEY"La clave actúa como la persona dueña de ella. Cada ruta aplica las mismas reglas de acceso que la pantalla: solo ves y cambias lo que esa persona ve y cambia.
Solicitudes#
- Cuerpos en JSON, con
Content-Type: application/json. La excepción es el envío de archivos al Brain, enmultipart/form-data. - Textos en UTF-8.
- Los campos que la ruta no conoce se ignoran.
- Fechas en ISO 8601, en UTC (
2026-10-27T14:03:11.482Z).
Respuestas#
Las respuestas exitosas son JSON con el recurso dentro de una clave con su nombre:
{ "agent": { "id": "agt_8f3a2b1c9d0e", "name": "Analista de CRM", "...": "..." } }Las listas vienen en un array con el nombre en plural ({ "agents": [...] }) y traen todo lo que puedes ver, sin paginación. Las acciones sin contenido que devolver responden { "ok": true }.
Pueden aparecer campos nuevos en las respuestas en cualquier momento. Ignora los que no conozcas.
Los errores tienen el formato { "error": "mensaje" }, a veces con un code estable. Consulta Errores y límites.
Streaming (NDJSON)#
Las rutas que generan texto con IA pueden responder por partes, en formato NDJSON: un objeto JSON por línea, separado por \n, con Content-Type: application/x-ndjson. Léelo línea por línea:
const res = await fetch("https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.DOUBLEX_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ message: "Resume las ventas de ayer" }),
});
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = "";
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buffer += value;
let nl;
while ((nl = buffer.indexOf("\n")) >= 0) {
const line = buffer.slice(0, nl).trim();
buffer = buffer.slice(nl + 1);
if (!line) continue;
const event = JSON.parse(line);
if (event.type === "text") process.stdout.write(event.delta);
}
}IDs#
Los IDs son textos con un prefijo que indica el tipo de recurso:
| Prefijo | Recurso |
|---|---|
agt_ | Agente |
task_ | Conversación (en la CLI, session) |
trg_ | Disparador |
con_ | Conector |
kno_ | Documento del Brain |
skl_ | Skill |
team_ | Equipo |
usr_ | Persona |
key_ | Clave de API |
Alcances y permisos#
Los agentes, skills, documentos del Brain y conectores tienen un alcance:
| Alcance | Quién ve y usa | Quién edita |
|---|---|---|
personal | Solo el dueño | El dueño y los administradores de la organización |
team | Los miembros del equipo (teamId) | El dueño, los administradores del equipo y los de la organización |
organization | Todas las personas de la organización | El dueño y los administradores de la organización |
Los elementos que no puedes ver responden 404, como si no existieran. Los elementos que ves pero no puedes editar responden 403 (o 404 en algunas rutas) cuando intentas cambiarlos. Los campos canEdit de las respuestas indican qué puedes editar.
Recursos#
| Recurso | Rutas |
|---|---|
| Cuenta | Quién eres, idioma, claves de API |
| Agentes | Crear, listar, configurar y borrar agentes |
| Conversaciones | Conversar en streaming, continuar, cancelar y leer el historial |
| Chat | Llamar a un modelo directamente, sin agente |
| Modelos y créditos | Catálogo de modelos, saldo y consumo |
| Conectores | Listar conexiones y ejecutar herramientas |
| Brain | Notas, carpetas, enlaces y búsqueda en el Brain |
| Skills | Instrucciones reutilizables |
| Creaciones | Archivos creados por los agentes |
| Disparadores | Programaciones, webhooks y eventos de apps |
| Equipos | Equipos de la organización |