Documentação da API Nodexa¶

Bem-vindo à documentação para desenvolvedores da Nodexa. A Nodexa é uma plataforma de orquestração de IA que expõe uma Responses API compatível com a OpenAI, permitindo que você integre assistentes de IA conversacionais nas suas aplicações usando ferramentas e padrões que você já conhece.

O que é a Nodexa?¶

A Nodexa permite que você construa experiências conversacionais com IA usando um mecanismo de roteamento multi-agente. Em vez de chamar um LLM genérico diretamente, você chama um Assistente Nodexa — uma entidade configurada que:

Roteia requests para o Agente Especialista mais adequado (um agente baseado em LLM com um papel específico e conhecimento dedicado)
Invoca tools em seu nome (busca na web, APIs REST, integrações MCP)
Mantém memória entre sessões para cada usuário
Passa contexto do usuário para os agentes especialistas por meio de claims estruturados
Faz streaming de respostas em tempo real usando Server-Sent Events (SSE)

A API é wire-compatible com a Responses API da OpenAI, então você pode usar o SDK oficial da OpenAI (Node.js ou Python) sem nenhum código customizado no cliente.

Principais Funcionalidades¶

Funcionalidade	Descrição
API compatível com OpenAI	Use o SDK da OpenAI ou qualquer cliente HTTP sem configurações extras
Streaming	Streaming SSE em tempo real com tipos de eventos granulares
Roteamento multi-agente	Requests são automaticamente roteados para o melhor Agente Especialista
Function calling no cliente	Execute funções personalizadas na sua aplicação e retorne os resultados
Busca na web	Busca web integrada para modelos OpenAI, Anthropic Claude e Google Gemini
Continuidade de conversas	Continue conversas entre requests com `previous_response_id`
Memória do usuário	Memória por usuário e por assistente que persiste entre sessões
Dados do usuário (claims)	Armazene e recupere dados estruturados do perfil do usuário
OAuth passthrough	Encaminhe tokens OAuth por provedor para tools que exigem autenticação do usuário

Navegação Rápida¶

Início Rápido

Faça sua primeira chamada de API funcionar em menos de 5 minutos.

Autenticação

Veja como as API keys funcionam e quais escopos usar.

Responses API

Referência completa do endpoint principal de chat.

Streaming

Conecte-se ao stream SSE e trate todos os tipos de eventos.

Function Calling

Execute tools no lado do cliente e retorne resultados.

Dados do Usuário (Claims)

Armazene e recupere dados estruturados do perfil do usuário.

Memória

Memória por usuário, opt-out e exclusão LGPD.

Guia do SDK OpenAI

Use o SDK oficial da OpenAI com a Nodexa — Node.js e Python.

URL Base¶

Todas as requests de API são enviadas para sua instância do Nodexa:

https://seu-admin.exemplo.com/v1

Substitua seu-admin.exemplo.com pelo hostname do seu deploy da Nodexa.

Autenticação em Resumo¶

A Nodexa usa API keys com o prefixo nxk_. Inclua sua chave em cada request:

curl https://seu-admin.exemplo.com/v1/responses \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "SEU_ID_DE_ASSISTENTE",
    "input": "Olá, como você pode me ajudar?"
  }'

Confira Autenticação para detalhes sobre as opções de header e API Keys para informações sobre escopos.

Exemplo Mínimo Funcional¶

Node.js (SDK OpenAI)Python (SDK OpenAI)curl

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://seu-admin.exemplo.com/v1',
  apiKey: 'SUA_CHAVE_DE_API',
});

const response = await client.responses.create({
  model: 'SEU_ID_DE_ASSISTENTE',
  input: 'Com o que você pode me ajudar hoje?',
});

console.log(response.output_text);

from openai import OpenAI

client = OpenAI(
    base_url="https://seu-admin.exemplo.com/v1",
    api_key="SUA_CHAVE_DE_API",
)

response = client.responses.create(
    model="SEU_ID_DE_ASSISTENTE",
    input="Com o que você pode me ajudar hoje?",
)

print(response.output_text)

curl https://seu-admin.exemplo.com/v1/responses \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "SEU_ID_DE_ASSISTENTE",
    "input": "Com o que você pode me ajudar hoje?"
  }'

Obtendo Ajuda¶

Navegue pela seção de Referência completa para eventos SSE, códigos de erro e limites.
Confira os Exemplos com código pronto para copiar e colar dos cenários mais comuns.