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
Guide4 min read

Your first API call

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

Open in the app

Start building

  • Your first API call
  • Limits, versions and headers

API

  • Brand API

MCP

  • MCP server

Connectors

  • Brand connectors
Português
Русский
한국어
日本語
中文
हिन्दी
Open the app
Where
Your account › Developers
On this page
  • 1. Create a personal token
  • 2. Check who you are
  • 3. List your brands
  • 4. Read a brand's works
  • 5. Connect an agent over MCP
  • Personal token or service account
  • Next steps

This guide takes you from zero to a working call against your real brands. It fits a script, an automation or an integration that acts as you. If the integration belongs to the organisation rather than a person, the end of the page tells you when to use a service account.

You need a Nömad account with access to at least one brand, and curl or any HTTP client.

1. Create a personal token

  1. Open Your account › Developers and click New token.
  2. Give it a Name that tells you where you use it, for example "Reporting script".
  3. Leave Expiration at 90 days (recommended).
  4. In What it can do, choose Read only for this guide.
  5. In Brands, leave it empty so it reaches all your brands, or pick only the ones you need.
  6. Click Create token and copy it with Copy token.

Important

Creating or rotating a token needs a sign-in from the last 10 minutes. If it has been longer, the form asks you to Confirm it is you (email code, password or Google) and keeps what you typed.

The full token is shown only once; Nömad keeps only its fingerprint. It looks like this:

nmu_live_v1_<prefix 10 hex>_<secret 64 hex>_<checksum 8 hex>

Keep it in your secrets manager or an environment variable, never in code:

export NOMAD_TOKEN="nmu_live_v1_…"

2. Check who you are

curl https://app.nomad.ooo/api/v1/me \
  -H "Authorization: Bearer $NOMAD_TOKEN"

The answer says who the token acts as, which brands it reaches and with which permissions:

{
  "data": {
    "id": "…",
    "type": "me",
    "attributes": { "profile": { "full_name": "Pegu Jurado", "username": "pegujurado", "locale": "en" } },
    "relationships": { "brands": [{ "id": "…", "type": "brand", "attributes": { "short_id": "BRD-8C1TZA", "name": "My brand" }, "membership": { "role": "admin" } }] },
    "credential": { "kind": "personal_token", "name": "Reporting script", "scopes": ["brands:read", "works.read"], "brand_ids": null, "expires_at": "…" }
  }
}

If you get 401 unauthenticated, check that the token is complete and still active. Every answer carries X-Request-Id: quote it if you write to us.

3. List your brands

To walk through the brands only, without their members:

curl "https://app.nomad.ooo/api/v1/me/brands?limit=50" \
  -H "Authorization: Bearer $NOMAD_TOKEN"

Note the short_id (BRD-8C1TZA) or the id of the brand you will work with. Any token can list its brands, even if you gave it no other permission.

4. Read a brand's works

Every Nömad operation is a method: POST to its name with the brand and the input in the body.

curl https://app.nomad.ooo/api/v1/works.list \
  -H "Authorization: Bearer $NOMAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "brand": "BRD-8C1TZA", "status": "active", "limit": 10 }'
{
  "data": {
    "items": [
      { "id": "…", "name": "Visual identity", "productName": "Visual identity", "status": "in_progress",
        "statusCategory": "started", "dueDate": null, "progress": { "done": 3, "total": 7 }, "waitingOnBrand": 1 }
    ],
    "nextCursor": null
  }
}

waitingOnBrand counts the tasks waiting for your brand. If nextCursor is not null, send it as cursor in the next call.

You now have a working integration. To write, create another token with change permissions on the areas you need and send Idempotency-Key on every write you may retry: it is explained in Brand API.

5. Connect an agent over MCP

If what you want is for Claude, ChatGPT, Cursor or VS Code to work with your brands, you need no token: they connect to the Nömad MCP server with OAuth.

  1. In your client, add a remote MCP connector or server with this address:

    https://app.nomad.ooo/api/mcp
    
  2. Authorise on the Nömad screen that opens and choose which brands it reaches.

  3. Ask it something, for example "Which works of my brand are waiting on me?".

It can always read, with your permissions. Changes follow each brand's agent policy (read only, with approval, or direct) and the ones waiting for your approval reach Your account › Approvals. Client-by-client steps are in MCP server and the brand side in External access.

Personal token or service account

Personal token (nmu_) Service account (nmw_)
Where it is created Your account › Developers In the workspace, Developers
Who creates it Anyone, for themselves The workspace's owner or an admin
Acts as You, never with more than your role in each brand An identity of the organisation with its own role in the brands
If whoever created it leaves It stops reaching what that person leaves; it is revoked if they delete their account It keeps working
Use it for Your own scripts and automations The store, the ERP or a company integration

Creating, limiting, rotating and revoking both is covered in Tokens and service accounts.

Next steps

  • Limits, versions and headers: how many calls you can make and which headers to read.
  • Errors: every code, its HTTP status and what to do.
  • Permissions and roles: which scope each operation needs.
  • Events and webhooks: hear about changes without asking.

Keep reading

  • Limits, versions and headersThe 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.
  • Brand APIMethods, authentication, writes, idempotency, pagination and errors.
  • MCP server

Updated on November 16, 2026

PreviousGet helpNextLimits, versions and headers
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

  • 1. Create a personal token
  • 2. Check who you are
  • 3. List your brands
  • 4. Read a brand's works
  • 5. Connect an agent over MCP
  • Personal token or service account
  • Next steps
Connect Claude, ChatGPT or Cursor to your brands.
  • Tokens and service accountsCreate, limit, rotate and revoke personal and organisation tokens.