Visão geral da API REST

A API REST do Nodaro é a interface HTTP do Nodaro: ela executa workflows e nós avulsos, informa o status dos jobs deles, armazena a sua mídia e gerencia personagens, predefinições e espaços de trabalho. Requisições e respostas são JSON por HTTPS, e toda requisição leva um token Bearer. A mesma API atende o Nodaro Cloud e as instalações self-hosted, e o SDK para TypeScript e a CLI são clientes leves dela.

URL base

Todo caminho começa com /v1/, por exemplo https://app.nodaro.ai/v1/nodes. Alguns endpoints existem só no Nodaro Cloud, como os de créditos e de organizações, e respondem 404 nas outras edições. Cada página informa quando um endpoint é limitado.

Autenticação

Envie Authorization: Bearer <token> em toda requisição. Use um token de API pessoal (ndr_…) de Configurações › Tokens de API para a sua própria conta. Use um token de acesso OAuth (ndr_app_…) quando o seu produto age em nome de outros usuários do Nodaro, ou o JWT da sua sessão em uma instalação da Community Edition. Alguns endpoints de descoberta, como GET /v1/nodes e GET /v1/models, não precisam de token. Leia Autenticação para criar um token.

A sua primeira chamada

Este exemplo gera uma imagem com um nó e lê o resultado. A geração é assíncrona: a primeira chamada retorna o ID de um job, e você consulta o job periodicamente até ele ser concluído.

export NODARO_API_KEY="ndr_..."

# 1. Start the job
curl -s -X POST https://app.nodaro.ai/v1/generate-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "a snow leopard on a mountain ridge at dawn",
        "provider": "nano-banana-pro",
        "aspectRatio": "16:9"
      }'
# {"jobId":"0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10"}

# 2. Poll the job until its status is "completed"
curl -s https://app.nodaro.ai/v1/jobs/0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10/status \
  -H "Authorization: Bearer $NODARO_API_KEY"

{
  "data": {
    "id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
    "status": "completed",
    "progress": 100,
    "output_data": { "imageUrl": "https://…/0f1a9c2e.png" },
    "error_message": null
  }
}

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

// Starts the job and polls it until it finishes.
const output = await client.nodes.runAndWait('generate-image', {
  prompt: 'a snow leopard on a mountain ridge at dawn',
  provider: 'nano-banana-pro',
  aspectRatio: '16:9',
})
console.log(output.imageUrl)

nodaro nodes run generate-image \
  --param prompt="a snow leopard on a mountain ridge at dawn" \
  --param provider=nano-banana-pro \
  --param aspectRatio=16:9 \
  --watch --json | jq -r '.output_data.imageUrl'

O mesmo padrão executa qualquer nó de geração: POST /v1/<node-type> com as configurações do nó e, depois, a consulta periódica do job. Veja Executar um único nó.

Convenções de requisição e resposta

• Entra JSON, sai JSON. Envie os corpos como JSON com Content-Type: application/json. Os uploads de arquivos são a exceção: eles usam multipart/form-data.
• Os IDs são UUIDs. Um ID malformado responde 400 validation_error.
• A maioria das respostas vem dentro de data. Uma leitura retorna { "data": … }, e uma exclusão ou um cancelamento retorna { "success": true }. Os endpoints legados de workflow em /v1/api/ retornam o payload diretamente.
• As gerações retornam o ID de um job. POST /v1/<node-type> responde com { "jobId": "…" }, às vezes com adjustments ou warnings ao lado.
• As listas usam cursores. Uma lista retorna um cursor, normalmente nextCursor (next em GET /v1/jobs). Envie esse cursor de volta como ?cursor= para obter a próxima página. Um cursor null significa que não há mais linhas. Os cursores são opacos: nunca analise nem monte um.
• Dois estilos de campo. Os objetos de job usam snake_case, como output_data e created_at. Workflows, execuções e a maioria dos outros recursos usam camelCase.
• As respostas crescem. Novos campos aparecem com o tempo. Ignore os campos que você não conhece em vez de falhar por causa deles.
• Os erros têm um só formato. Uma chamada com falha retorna um status HTTP e { "error": { "code": "…", "message": "…" } }. Decida o tratamento por code. Veja Erros.

Dois cabeçalhos opcionais mudam como uma requisição é tratada:

Síncrono ou assíncrono

A maior parte do trabalho no Nodaro leva de segundos a minutos, então a API é assíncrona. Uma rota de geração responde na hora com um jobId, e uma execução de workflow responde 202 Accepted com um executionId. Depois, você consulta periodicamente o job ou a execução, a cada 2 a 5 segundos, até chegar a um status final. Para um workflow que deve terminar em menos de um minuto, POST /v1/api/run?wait=true mantém a conexão aberta por até 600 segundos e retorna o resultado. Algumas rotas respondem de forma síncrona, como os nós de texto inline, o processamento de mídia gratuito e a chamada de LLM com saída estruturada. Leia Síncrono ou assíncrono para ver os detalhes.

Endpoints por área

Executar

Recursos

Conta

Referência

Limites e erros

Um token de API pessoal permite 30 requisições por minuto por padrão, até no máximo 120, nos endpoints de execução e de listagem de workflows. Algumas rotas têm limites próprios. As consultas periódicas de status não contam para o limite do token. Um 429 significa que você deve diminuir o ritmo e tentar de novo com backoff. Um 4xx significa que você deve corrigir a requisição antes de tentar de novo, e um 5xx costuma ser temporário. Leia Limites de taxa e Erros.

Clientes para a sua linguagem

• TypeScript e JavaScript: npm install @nodaro/sdk. O SDK encapsula estes endpoints com tipos, erros tipados e funções auxiliares de consulta periódica.
• Terminal e CI: npm install -g @nodaro/cli. A CLI executa workflows, apps e nós avulsos, com --watch e --json.
• Qualquer outra linguagem: gere um cliente a partir da especificação OpenAPI ou envie requisições HTTPS simples.
• Assistentes de IA: conecte o servidor MCP em vez de escrever código.