# Especificação OpenAPI

> Baixe a especificação OpenAPI 3.1 do Nodaro em /v1/openapi.json, veja os endpoints que ela cobre e gere clientes tipados em Go, Rust, Python e mais.

Source: https://nodaro.ai/pt-BR/docs/developers/api/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](https://nodaro.ai/docs/developers/sdk) é o cliente pronto.

## Obter a especificação
```bash
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:

| Área | Caminhos |
| --- | --- |
| Workflows | `GET /v1/projects/{projectId}/workflows`, `POST /v1/workflows/{id}/run`, `POST /v1/workflows/{id}/move` |
| Jobs | `GET /v1/jobs/{id}`, `GET /v1/jobs/{id}/status` |
| Descoberta de nós | `GET /v1/nodes`, `GET /v1/nodes/{type}` |
| Geração | `POST /v1/generate-image`, `POST /v1/generate-video` |
| OAuth | `POST /v1/oauth/token`, `GET /v1/oauth/app-info` e as rotas de conexão de plugins em `/v1/oauth/plugin/` |
| Créditos | `POST /v1/credits/model-costs`, `POST /v1/credits/video-pro-estimate` |

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](https://nodaro.ai/docs/developers/api/authentication).
- **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](https://nodaro.ai/docs/developers/api/nodes) para saber o que os campos fazem.

## Gerar um cliente
```bash
# 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](https://nodaro.ai/docs/developers/api/errors) e a consulta periódica de resultados de [Jobs](https://nodaro.ai/docs/developers/api/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](https://nodaro.ai/docs/nodes).
- **Todos os outros endpoints estão descritos nestas páginas**, de [Workflows](https://nodaro.ai/docs/developers/api/workflows) e [Execuções](https://nodaro.ai/docs/developers/api/executions) a [Envio de arquivos](https://nodaro.ai/docs/developers/api/uploads) e [Créditos](https://nodaro.ai/docs/developers/api/credits). Chame-os com o método de requisição bruta do seu cliente gerado ou com qualquer biblioteca HTTP.

## Frequently asked questions

### Onde fica a especificação OpenAPI do Nodaro?

Em https://app.nodaro.ai/v1/openapi.json, no Nodaro Cloud. Ela é pública, então não é preciso token, e uma instalação self-hosted serve a própria especificação no mesmo caminho.

### A especificação OpenAPI cobre todos os endpoints do Nodaro?

Não. Ela é uma parte selecionada da API que cobre o núcleo de automação, as execuções de workflows, o status dos jobs, a descoberta de nós, a geração de imagem e de vídeo, a troca de tokens OAuth e as consultas de custo em créditos. Os outros endpoints estão descritos nestas páginas.

### Como chamo um nó que não está na especificação?

Todo nó segue a mesma rota, POST /v1/ seguido do tipo do nó, com as configurações do nó no corpo. Leia os campos do nó em GET /v1/nodes/:type e envie a requisição com o método de requisição bruta do seu cliente gerado ou com qualquer biblioteca HTTP.

### Qual autenticação a especificação declara?

Um único esquema, bearerAuth, um bearer token HTTP sem formato fixo. Ele aceita um JWT de sessão, um token de API pessoal, um token de acesso OAuth ou uma chave de integração de cobrança. Nove operações públicas, como GET /v1/nodes, estão marcadas com security: [] e não recebem token.