Documentation

Versioning policy

The API is versioned by date and each key is pinned to one version; adding fields, endpoints, events, errors or values of open lists breaks nothing, and any other change ships as a new version.

How the version is chosen

The version is a date, the current one is 2026-10-01, and it travels in the Nouron-Version header.
When a key is created a version is pinned to it. If the request does not send the header, the key's version is used: an agent that is left untouched does not break because of an update.
If you send a version that exists, it applies to that request only. If you send one that does not exist, the response is 400 unsupported_version.
Every response carries Nouron-Version (the one actually used) and Request-Id.

What is compatible (does not change the version)

Adding an optional field to a response or a request.
Adding a new endpoint or method.
Adding an event type (webhook endpoints only receive the ones they asked for).
Adding a new error code.
Adding a value to an open enumeration (x-open-enum: true in openapi.json).
Adding an optional parameter.

What breaks (ships as a new version)

Removing or renaming a field, an endpoint or a parameter.
Changing the type of a field.
Making a field or a parameter required when it was not.
Adding a value to a closed enumeration, such as the status of a payment.
Removing a value from any enumeration.
Turning an open enumeration into a closed one.
Changing the meaning of a status or a reason.
Changing the description or the arguments of an MCP tool.

How it is communicated

Every compatible change is recorded in the «Change history» section of the versioning page.
A breaking change ships as a new dated version (Nouron-Version: YYYY-MM-DD); the previous one keeps working.
Each key is pinned to a version: an agent that is left untouched does not break because of an update.
Before a version is retired, owners are told in advance; the notice period is published with the first new version.

Open lists

Five lists can grow without changing the version. In openapi.json they carry x-open-enum: true. The lists of states your code handles with a switch, such as the status of a payment, stay closed.

List
List	Where	What to do with an unknown value
Error codes	`error.code`	Handle it by the HTTP status and by `error.retry`.
Error types	`error.type`	Handle it by the HTTP status.
Event types	the event `type`	Ignore it and answer 2xx.
Next actions	`next_action.code`	Treat it as `contact_support`.
Audit actions	the record `action`	Show it as it is; it is recognized by its `resource.action` shape.

How to tolerate an unknown value

Always keep a default branch. Never force the switch to be exhaustive over these lists.

Example

function onEvent(event: { id: string; type: string }) {
  switch (event.type) {
    case 'spend.settled':
      return markPaid(event);
    default:
      // Tipo que no conoces: ignóralo y responde 2xx.
      return;
  }
}

Receipts

The signed receipt carries its own version. Version 1 always says x402 in payment.rail; version 2 leaves the rail open. A version 1 receipt is still verified the same way: the verifier recomputes the chain with the published recipe and does not decide by version.

Change history

2026-10-12. Compatible. The lists of error codes and types, event types, next actions and audit actions were opened (x-open-enum). The codes capability_unavailable, verification_required, account_on_hold and partner_unavailable were defined; they are not returned yet. Receipt version 2 was added. The text of missing_api_key was unified (<api_key>).
2026-10-01. Initial version of the API v1.