Limits, versions and headers
The exact numbers of the Nömad API and MCP (requests per minute, body size, pagination, token lifetime and count) plus the headers, the version and the machine-readable documents.
Privacy and analytics
We use necessary technical cookies and, only with your consent, analytics and marketing pixels to improve the website and measure campaigns.
The exact numbers of the Nömad API and MCP (requests per minute, body size, pagination, token lifetime and count) plus the headers, the version and the machine-readable documents.
This page gathers the numbers your integration needs to stay clear of a limit: how much you can call, how large a request may be, how long a token lives and which headers to read. How to call a method, idempotency and errors are in Brand API and Errors.
| What | Address |
|---|---|
| API base | https://app.nomad.ooo/api/v1 |
| Call an operation | POST /api/v1/{operation}, for example POST /api/v1/works.list |
| Who you are and what you reach | GET /api/v1/me |
| Your brands, paginated | GET /api/v1/me/brands |
| OpenAPI specification | GET /api/v1/openapi.json, with your token (or signed in to Nömad) |
| Summary for agents | GET /api/v1/llms.txt, with your token (?full=1 adds every operation's description) |
| MCP server | https://app.nomad.ooo/api/mcp |
| Revoke a leaked token | POST /api/credentials/revoke with { "token": "…" } |
The credential goes in Authorization: Bearer <token>. The X-API-Key header is accepted too.
Every limit counts in 60-second windows.
| Who calls | Limit |
|---|---|
| A personal or service account token | 300 requests per minute, per token |
| A person in a Nömad app, with their session | 600 requests per minute |
| Wrong credentials from one network address | 20 per minute; after that, 429 even if the next one is right |
| An MCP connection (person + client) | 240 JSON-RPC requests per minute |
| Wrong MCP tokens from one address | 20 per minute |
When you go over we answer 429 rate_limited with Retry-After in seconds. Wait that long before retrying.
RateLimit headerEvery answer to a valid credential carries:
RateLimit: limit=300, remaining=287, reset=42
| Field | Meaning |
|---|---|
limit |
Requests per minute for this credential |
remaining |
What is left in the current window |
reset |
Seconds until the next window starts |
Tip
Read remaining and slow down before it reaches zero: it is cheaper than handling a 429.
| Rule | Value |
|---|---|
| Maximum body | 64 KB (65,536 bytes). Larger: 413 payload_too_large. |
| Content type | application/json. Any other: 422 invalid_input. |
| Body shape | A JSON object; an array or broken JSON answers 422 invalid_input. An empty body counts as {}. |
| An MCP tool result | At most 25,000 tokens. Larger: result_too_large, with a hint to use limit, format or cursor. |
| Where | limit |
Default | Next page |
|---|---|---|---|
Operations (POST /api/v1/…) |
1 to 50 | 20 | Send the nextCursor you got as cursor |
GET /api/v1/me/brands |
1 to 100 | 50 | Send next_cursor as ?cursor= |
Cursors are opaque: do not build them or keep them for long.
| Header | What for | Rules |
|---|---|---|
Authorization |
Your credential | Bearer nmu_live_v1_… or Bearer nmw_live_v1_… |
Content-Type |
The body's format | application/json |
Idempotency-Key |
So a retry never writes twice | 8 to 128 characters: letters, digits, ., _, : and -. Valid for 24 hours. |
X-Request-Id |
Use your own request id | 8 to 64 characters of the same set. If missing or invalid, we generate one. |
| Header | What it says |
|---|---|
X-Request-Id |
The request's id. Quote it if you write to support. |
X-Nomad-Api-Version |
The major version that answered: v1. |
RateLimit |
Your quota for the minute (see above). |
Retry-After |
On a 429, the seconds to wait. |
Idempotent-Replayed |
true when the answer is the stored one from an earlier call with the same key. |
Cache-Control |
Always no-store: do not keep answers in shared caches. |
WWW-Authenticate |
On a 401 unauthenticated or a 403 insufficient_scope, what is missing. |
| What | Value |
|---|---|
| Major version | v1, in the address (/api/v1) and in X-Nomad-Api-Version |
| Contract revision | 2026-10-25, in openapi.json's info.version (v1 (2026-10-25)) |
| MCP protocol | 2026-07-28 |
Within v1 changes are additive: new optional fields and new operations. A published operation name never changes meaning; when one has to be replaced, the old one keeps working while the new one is announced. Your client should ignore fields it does not know.
To find out whether something changed, compare the revision in openapi.json with the last one you read. llms.txt and openapi.json are generated from the same contract the app uses, so they never describe anything different from what the API answers.
| Rule | Value |
|---|---|
| Format | <kind>_live_v1_<prefix 10 hex>_<secret 64 hex>_<checksum 8 hex>; nmu personal, nmw service account |
| Default lifetime | 90 days |
| Lifetimes the screen offers | 7, 30, 90 or 365 days, a day you pick (366 days at most) or No expiration |
| Expiry notice | Once, 7 days before |
| Live tokens at once | 10 per holder (person or service account) |
| Brands it can be limited to | Up to 50 |
| Name | 3 to 80 characters |
| Rotation overlap | The old secret keeps working 0, 1, 24 or 168 hours |
| Create or rotate | Needs a sign-in from the last 10 minutes |
| MCP OAuth access token | Expires after one hour |
| An agent's pending approval | Expires after 24 hours |
A token limited to some brands answers a brand outside them exactly like one that does not exist (404 brand_not_found) and refuses workspace operations (403 token_brand_restricted).
For your secret scanner to catch them, use this pattern:
\b(?:nma|nmu|nmw)_live_v1_[a-f0-9]{10}_[a-f0-9]{64}_[a-f0-9]{8}\b
Warning
If a token shows up where it should not (a repository, a log, a chat), revoke it in Your account › Developers or send it to POST /api/credentials/revoke. The answer is always 202, whether it exists or not.
Updated on November 16, 2026