---
key: api-reference
title: API reference
audience: developer
section: api/getting-started
routes: []
since: 0.0.1
updated: 0.0.1
status: published
summary: The interactive reference for the documented operations, the index of every operation a key can call, and the OpenAPI document to download.
keywords: [openapi, reference, swagger, scalar, operations]
related: [api-overview, api-authentication, find-what-to-call, api-errors, api-limits, connect-an-ai-agent, nova-mcp-tools]
---

Nova's API is documented in two layers, and the first one is a starting point,
not a limit.

## The documented operations

78 operations are documented in full: request and response shapes, worked
examples and the permission each one checks. They are the common path — read
customers, create work orders, send invoices — and they are where to start.

They are an OpenAPI 3.1 document generated from the running app at release
time, so it always matches the deployed code.

- **Browse it:** [the interactive reference](/help/api/reference/) lists every
  operation with its request and response shapes, the scope it needs and the
  permission it checks.
- **Download it:** [openapi-public.json](/help/api/reference/openapi-public.json)
  for code generation, custom GPT actions or your own tooling.
- **Fetch it from the API:** `GET /v1/public/api-docs/openapi.json`.

Each operation carries three custom fields:

| Field | Meaning |
|---|---|
| `x-nova-scope` | The OAuth scope a token needs |
| `x-nova-permissions` | The permission keys the route checks on the acting principal |
| `x-nova-destructive` | Whether the action cannot be undone from the API |

## Everything else your key can call

Your key is **not** limited to those 78. It can call any operation in Nova it
holds the permissions for — about 3,265 of them. They are listed in the
operation index:

- **Fetch it:** `GET /v1/public/api-docs/operations.json`
- Each entry gives the method, the address, a one-line summary, the exact
  permission keys the operation checks, the address placeholders it takes, and
  whether it only reads or removes something.

It carries no request or response shapes — those are in the OpenAPI document
for the documented operations above. The index answers a different question:
*what can this key call, and what does it need to hold?*

The index is generated from the routes themselves, so an operation added in a
release appears without anyone writing it down.

```bash
curl -s https://app.novabmp.com/v1/public/api-docs/operations.json \
  | jq '.operations[] | select(.path | contains("invoices")) | {operation_id, method, path, permissions}'
```

If a call is refused, the error names the exact permission key to add; search
the index for that key to see everything else it unlocks. [[find-what-to-call]]
walks through it, and [[api-errors]] lists every refusal and how to recover.

## What no key can call

Signing in, the OAuth endpoints, platform administration, and the routes that
manage keys, agents and connected apps. A key that could mint a browser session
or approve its own consent would have escaped every limit placed on it.

## For AI assistants

The operation ids are the tool names an assistant sees through MCP. Because no
assistant can hold 3,265 tools at once, the connection also gets
**find_operations** (search everything it may call) and
**call_nova_operation** (call one by its id). The operation still checks its
own permissions, so those tools give an assistant reach, never extra rights.
See [[nova-mcp-tools]].
See [[connect-an-ai-agent]].