Agents, trash and errors: API examples

The same call as in the ⚡ API quickstart, with a different tool name and arguments.

Agents

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"agents","arguments":{"action":"list"}}}'

Workspace agents (0):
Global agents (3):
- @planner Planner (id: c72985b9-…, workspace default model, tools: read, switched off here)
- @reporter Reporter (id: e7a35409-…, workspace default model, tools: read, switched off here)
- @reviewer Reviewer (id: 864ab080-…, workspace default model, tools: read, connectors, switched off here)

Changing agents with agents_write needs a workspace owner or admin.

Trash

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"trash","arguments":{"action":"list"}}}'

- Hello from the API (id: cmvp00soi0000qe7dmm9pb073, deleted 2026-10-26T08:32:43.731Z)

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"trash","arguments":{"action":"restore","page_id":"cmvp00soi0000qe7dmm9pb073"}}}'

What a failed call looks like

There are two kinds, and both keep the HTTP status 200 unless the sign-in failed.

The call was understood but refused. The result carries isError: true and says why in plain words. Nothing was changed.

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pages","arguments":{"action":"get","page_id":"nope"}}}'

{"result":{"content":[{"type":"text","text":"Page \"nope\" not found in workspace \"your-workspace\"."}],"isError":true},"jsonrpc":"2.0","id":1}

Refusals you will meet: a page, form, sheet or collection that is locked (the text starts with LOCKED and names the unlock step), a value that breaks a field rule, a plan limit, and a read-only workspace.

The token is missing or wrong. The answer is HTTP 401, with a WWW-Authenticate header for clients that sign in with OAuth:

{"jsonrpc":"2.0","error":{"code":-32001,"message":"Unauthorized. Send an API token as `Authorization: Bearer nm_...` (create one in Workspace settings → MCP & API), or connect via OAuth."},"id":null}

A token made for another workspace answers HTTP 403 and names the right address. Look at the message, fix the cause and call again.

A version the server does not speak. Send X-API-Version: 1 or leave the header out; any other value answers HTTP 400 with the sentence "This server speaks API version 1".

Public endpoints answer in application/problem+json. Form submission, form upload and public search send a JSON document with type, title, status and detail, plus RateLimit-* headers on the counted routes and Retry-After on a 429:

{"type":"about:blank","title":"Too many requests","status":429,"detail":"Too many submissions. Try again in a few minutes."}

Retrying: send an Idempotency-Key header on the call. If the first request did get through, the retry returns its answer with Idempotency-Replayed: true; the same key with a different body answers 422, and a key whose first call is still running answers 409.