Skip to content

Privacy and analytics

We use necessary technical cookies and, only with your consent, analytics and marketing pixels to improve the website and measure campaigns.

Privacy policyCookie policy
Docs
GuidesDevelopers
English
EspañolEnglishFrançaisDeutschItaliano

Start building

  • Your first API call
  • Limits, versions and headers

API

  • Brand API

MCP

  • MCP server

Connectors

  • Brand connectors
Start building
Reference4 min read

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.

Português
Русский
한국어
日本語
中文
हिन्दी
Open the app
On this page
  • Addresses
  • Request limits
  • The RateLimit header
  • Size and format
  • Pagination
  • Headers
  • The ones you send
  • The ones you get
  • Versions
  • Tokens

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.

Addresses

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.

Request limits

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.

The RateLimit header

Every 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.

Size and format

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.

Pagination

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.

Headers

The ones you send

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.

The ones you get

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.

Versions

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.

Tokens

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.

Keep reading

  • Your first API callCreate a personal token, check who you are with GET /api/v1/me, list your brands and read their works; then connect an agent over MCP.
  • Brand APIMethods, authentication, writes, idempotency, pagination and errors.
  • ErrorsEvery error code, its HTTP status and what to do.
  • Tokens and service accountsCreate, limit, rotate and revoke personal and organisation tokens.

Updated on November 16, 2026

PreviousYour first API callNextBrand API
Can't find what you need? Write to usWrite to usGo to the app
© 2026 Nömad · Nömad documentationLinkedInInstagramThreadsFacebookTikTokYouTubeX
Go to nomad.oooBack to top

On this page

  • Addresses
  • Request limits
  • The RateLimit header
  • Size and format
  • Pagination
  • Headers
  • The ones you send
  • The ones you get
  • Versions
  • Tokens