Privacy and analytics

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

English

Español English Français Deutsch Italiano Português

Guide2 min read

Brand API

Methods, authentication, confirmations, pagination and errors.

On this page

Calling a method
Authentication
Brand
Writes and confirmation
Pagination
Errors
Versioning

Updated on January 1, 1970

Everything that can be done inside a Nömad brand is defined once as a capability. The same capability serves Nödo in chat, an external agent over MCP and an integration over HTTP. There are 46 capabilities across 18 areas; 8 are available and the rest roll out in phases.

Status. This is the API specification. Capabilities marked «Available» work today through Nödo and the pilot MCP; HTTP methods and scoped keys turn on in the «Registry and MCP» phase. This page changes with the code.

Calling a method

Each capability is a method: POST to its id with a JSON body carrying the brand and the input. The response is JSON with the typed output.

curl https://app.nomad.ooo/api/v1/works.list \
  -H "Authorization: Bearer nmu_…" \
  -H "Content-Type: application/json" \
  -d '{ "brand": "WP-000", "status": "active", "limit": 10 }'

{
  "ok": true,
  "data": {
    "items": [{ "id": "…", "name": "Identidad visual", "status": "in_progress", "dueDate": null,
                "progress": { "done": 3, "total": 7 }, "waitingOnBrand": 1 }],
    "nextCursor": null
  }
}

Authentication

Personal keys nmu_… created in Settings › Security and access. A key acts as the person who created it, with scopes and optionally limited to some brands.
A key never grants more than the person can do in the app: access is the granted scope intersected with the live permissions of their role on every call.
Revoking the key, removing the person from the brand or closing the brand cuts access on the next call.

Brand

The brand field accepts the short id (WP-121) or the UUID. Call brands.list to see which brands a key can use.

Writes and confirmation

Writes that change something other people see require confirmation. Over HTTP the first call returns confirmation_required with a summary and a single-use confirmationToken; repeat the call with that token to run it. In chat this is the «Confirm» widget.

Every write with expectedRevision fails with revision_conflict if the record changed meanwhile: read again and retry.

Pagination

Lists return items and nextCursor. Pass cursor for the next page; limit goes from 1 to 50.

Errors

Code	HTTP	Meaning
`unauthenticated`	401	Missing or invalid key.
`insufficient_scope`	403	The key lacks the scope; the response names it.
`forbidden`	403	The person role does not allow this capability in this brand.
`brand_not_operational`	409	The brand is closed or archived: read-only.
`confirmation_required`	409	Confirmation needed; repeat with the token.
`revision_conflict`	409	The record changed; read again.
`invalid_input`	422	Input does not match the schema; the field is named.
`budget_exceeded`	402	No AI budget left for the brand this month.
`rate_limited`	429	Too many calls; honor `Retry-After`.

Versioning

Changes are additive: new optional fields and new capabilities. A published id never changes meaning; when one must be replaced the old one keeps working while the new one is announced.