Especificação OpenAPI

A especificação OpenAPI do Nodaro é uma descrição legível por máquina do núcleo da API REST do Nodaro, em OpenAPI 3.1, servida ao vivo pelo servidor. Use-a para gerar um cliente tipado em Go, Rust, Python ou qualquer linguagem que tenha um gerador de OpenAPI, ou para explorar a API em qualquer ferramenta que leia OpenAPI. Para TypeScript e JavaScript, o SDK é o cliente pronto.

Obter a especificação

curl -s https://app.nodaro.ai/v1/openapi.json -o nodaro-openapi.json

A especificação é pública, então não é preciso token, e ela fica em cache por 5 minutos. Uma instalação self-hosted serve a própria especificação no mesmo caminho, /v1/openapi.json. A página Tokens de API, em Configurações, também tem um link para ela.

O que a especificação cobre

A especificação é uma parte selecionada da API: ela descreve o núcleo de automação, não todas as rotas. Ela cobre:

Ela define quatro schemas compartilhados: WorkflowSummary, Job, JobStatus e NodeDescriptor. O servidor monta a especificação a partir das próprias definições de rotas, então leia o arquivo ao vivo para ver a lista exata.

Algumas coisas a saber ao usá-la:

• Um único esquema de segurança. bearerAuth é um bearer token HTTP, sem bearerFormat. A descrição dele lista os tokens que aceita: um JWT de sessão, um token de API pessoal (ndr_…), um token de acesso OAuth (ndr_app_…) ou uma chave de integração de cobrança (ndr_bill_…). Veja Autenticação.
• Um servidor relativo. O servidor da especificação é /, então defina a URL base, como https://app.nodaro.ai, ao criar o cliente.
• Operações públicas. Toda operação exige bearerAuth, exceto nove que estão marcadas com security: [] e não recebem token: GET /v1/nodes, GET /v1/nodes/{type}, POST /v1/oauth/token, GET /v1/oauth/app-info, as quatro rotas de conexão de plugin em /v1/oauth/plugin/ e POST /v1/credits/model-costs.
• Campos de geração. POST /v1/generate-image e POST /v1/generate-video listam os corpos de requisição completos, incluindo connectedReferences, direction e subject. Veja Nós para saber o que os campos fazem.

Gerar um cliente

# Go
oapi-codegen -generate types,client -package nodaro https://app.nodaro.ai/v1/openapi.json

# Rust
openapi-generator generate -i https://app.nodaro.ai/v1/openapi.json -g rust -o nodaro-rs

# Python
openapi-generator generate -i https://app.nodaro.ai/v1/openapi.json -g python -o nodaro-py

Depois, aponte o cliente para a sua URL base e envie Authorization: Bearer <token> em toda requisição, exceto nas operações públicas. O resto funciona como descrito nas outras páginas: corpos JSON, o envelope { "error": { "code", "message" } } de Erros e a consulta periódica de resultados de Jobs.

Chamar endpoints fora da especificação

A API REST funciona em qualquer linguagem, mesmo onde a especificação não diz nada: envie um bearer token, mande JSON e receba JSON.

• Todo nó tem a mesma rota. POST /v1/{node-type}, com as configurações do nó no corpo, executa qualquer nó, não só os dois da especificação. Leia os campos de um nó em GET /v1/nodes/{type}, em inputSchema, e na página dele na referência de nós.
• Todos os outros endpoints estão descritos nestas páginas, de Workflows e Execuções a Envio de arquivos e Créditos. Chame-os com o método de requisição bruta do seu cliente gerado ou com qualquer biblioteca HTTP.