# OpenAPI spec

> Download the Nodaro OpenAPI 3.1 spec from /v1/openapi.json, see which endpoints it covers, and generate typed clients in Go, Rust, Python and other languages.

Source: https://nodaro.ai/docs/developers/api/openapi

The **Nodaro OpenAPI spec** is a machine-readable description of the core of the Nodaro REST API, in OpenAPI 3.1, served live by the server. Use it to generate a typed client in Go, Rust, Python or any language that has an OpenAPI generator, or to explore the API in any tool that reads OpenAPI. For TypeScript and JavaScript, the [SDK](https://nodaro.ai/docs/developers/sdk) is the ready-made client.

## Get the spec

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

The spec is public, so no token is needed, and it is cached for 5 minutes. A self-hosted install serves its own spec at the same path, `/v1/openapi.json`. The **API Tokens** page in Settings links to it too.

## What the spec covers

The spec is a **curated part** of the API: it describes the automation core, not every route. It covers:

| Area | Paths |
| --- | --- |
| 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` |
| Node discovery | `GET /v1/nodes`, `GET /v1/nodes/{type}` |
| Generation | `POST /v1/generate-image`, `POST /v1/generate-video` |
| OAuth | `POST /v1/oauth/token`, `GET /v1/oauth/app-info`, and the plugin connect routes under `/v1/oauth/plugin/` |
| Credits | `POST /v1/credits/model-costs`, `POST /v1/credits/video-pro-estimate` |

It defines four shared schemas: `WorkflowSummary`, `Job`, `JobStatus` and `NodeDescriptor`. The server builds the spec from its own route definitions, so read the live file for the exact list.

A few things to know when you use it:

- **One security scheme.** `bearerAuth` is an HTTP bearer token. The spec labels its format `JWT`, but the scheme accepts a personal API token, an OAuth access token or a session JWT. See [Authentication](https://nodaro.ai/docs/developers/api/authentication).
- **A relative server.** The spec's server is `/`, so set the base URL, such as `https://app.nodaro.ai`, when you create the client.
- **Public discovery routes.** The spec marks every path with `bearerAuth`, but `GET /v1/nodes` and `GET /v1/nodes/{type}` also answer without a token.
- **Generation fields.** `POST /v1/generate-image` and `POST /v1/generate-video` list their full request bodies, including `connectedReferences`, `direction` and `subject`. See [Nodes](https://nodaro.ai/docs/developers/api/nodes) for what the fields do.

## Generate a client

```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
```

Then point the client at your base URL and send `Authorization: Bearer <token>` with every request. Everything else works as described on the other pages: JSON bodies, the `{ "error": { "code", "message" } }` envelope from [Errors](https://nodaro.ai/docs/developers/api/errors), and polling for results from [Jobs](https://nodaro.ai/docs/developers/api/jobs).

## Call endpoints outside the spec

The REST API works from any language even where the spec is silent: send a bearer token, JSON in, JSON out.

- **Every node has the same route.** `POST /v1/{node-type}`, with the node's settings as the body, runs any node, not only the two in the spec. Read a node's fields from `GET /v1/nodes/{type}`, under `inputSchema`, and from its page in the [node reference](https://nodaro.ai/docs/nodes).
- **Every other endpoint is described on these pages**, from [Workflows](https://nodaro.ai/docs/developers/api/workflows) and [Executions](https://nodaro.ai/docs/developers/api/executions) to [Uploads](https://nodaro.ai/docs/developers/api/uploads) and [Credits](https://nodaro.ai/docs/developers/api/credits). Call them with your generated client's raw request method or any HTTP library.

## Frequently asked questions

### Where is the Nodaro OpenAPI spec?

At https://app.nodaro.ai/v1/openapi.json for Nodaro Cloud. It is public, so no token is needed, and a self-hosted install serves its own spec at the same path.

### Does the OpenAPI spec cover every Nodaro endpoint?

No. It is a curated part of the API that covers the automation core, workflow runs, job status, node discovery, image and video generation, the OAuth token exchange and credit cost lookups. The other endpoints are described on these pages.

### How do I call a node that is not in the spec?

Every node follows the same route, POST /v1/ followed by the node type, with the node's settings as the body. Read the node's fields from GET /v1/nodes/:type, then send the request with your generated client's raw request method or any HTTP library.

### Which authentication does the spec declare?

One scheme, bearerAuth, an HTTP bearer token. The spec labels its format JWT, but the scheme accepts a personal API token, an OAuth access token or a session JWT.