Referência da API › Fundamentos
Visão geral da API
Endereço, autenticação, formato das requisições e respostas, streaming e convenções da API HTTP.
A API do DoubleX Agentes é a mesma que o app usa. Com ela você cria e configura agentes, conversa com eles em streaming, chama modelos direto, usa as ferramentas dos conectores, alimenta o Brain, gerencia skills e gatilhos e baixa os arquivos de Criações.
Endereço#
https://doublex.ai/apiTodas as rotas desta referência são relativas a esse endereço: GET /api/agents é GET https://doublex.ai/api/agents.
Autenticação#
Mande uma chave de API no cabeçalho Authorization:
curl https://doublex.ai/api/me -H "Authorization: Bearer $DOUBLEX_API_KEY"A chave age como a pessoa dona dela. Cada rota aplica as mesmas regras de acesso da tela: você só vê e altera o que essa pessoa vê e altera.
Requisições#
- Corpos em JSON, com
Content-Type: application/json. A exceção é o envio de arquivos para o Brain, emmultipart/form-data. - Textos em UTF-8.
- Campos que a rota não conhece são ignorados.
- Datas em ISO 8601, em UTC (
2026-10-27T14:03:11.482Z).
Respostas#
As respostas de sucesso são JSON com o recurso dentro de uma chave com o nome dele:
{ "agent": { "id": "agt_8f3a2b1c9d0e", "name": "Analista de CRM", "...": "..." } }As listas vêm num array com o nome no plural ({ "agents": [...] }) e trazem tudo o que você pode ver, sem paginação. Ações sem conteúdo para devolver respondem { "ok": true }.
Novos campos podem aparecer nas respostas a qualquer momento. Ignore os que você não conhece.
Os erros têm o formato { "error": "mensagem" }, às vezes com um code estável. Veja Erros e limites.
Streaming (NDJSON)#
As rotas que geram texto com IA podem responder em partes, no formato NDJSON: um objeto JSON por linha, separado por \n, com Content-Type: application/x-ndjson. Leia linha a linha:
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: "Resuma as vendas de ontem" }),
});
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#
Os IDs são textos com um prefixo que diz o tipo do recurso:
| Prefixo | Recurso |
|---|---|
agt_ | Agente |
task_ | Conversa (na CLI, session) |
trg_ | Gatilho |
con_ | Conector |
kno_ | Documento do Brain |
skl_ | Skill |
team_ | Time |
usr_ | Pessoa |
key_ | Chave de API |
Escopos e permissões#
Agentes, skills, documentos do Brain e conectores têm um escopo:
| Escopo | Quem vê e usa | Quem edita |
|---|---|---|
personal | Só o dono | O dono e os administradores da organização |
team | Os membros do time (teamId) | O dono, os administradores do time e os da organização |
organization | Todas as pessoas da organização | O dono e os administradores da organização |
Itens que você não pode ver respondem 404, como se não existissem. Itens que você vê mas não pode editar respondem 403 (ou 404 em algumas rotas) quando você tenta alterá-los. Os campos canEdit das respostas dizem o que você pode editar.
Recursos#
| Recurso | Rotas |
|---|---|
| Conta | Quem você é, idioma, chaves de API |
| Agentes | Criar, listar, configurar e apagar agentes |
| Conversas | Conversar em streaming, continuar, cancelar e ler o histórico |
| Chat | Chamar um modelo direto, sem agente |
| Modelos e créditos | Catálogo de modelos, saldo e consumo |
| Conectores | Listar conexões e executar ferramentas |
| Brain | Notas, pastas, links e busca no Brain |
| Skills | Instruções reutilizáveis |
| Criações | Arquivos criados pelos agentes |
| Gatilhos | Agendamentos, webhooks e eventos de apps |
| Times | Times da organização |