# Agents, trash and errors: API examples

The same call as in the [⚡ API quickstart](https://docs.wrightdesk.com/build-with-the-api/api-quickstart), with a different tool name and arguments.

## Agents

```bash
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"}}}'
```

```text
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

```bash
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"}}}'
```

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

```bash
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.

```bash
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"}}}'
```

```json
{"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:

```json
{"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`:

```json
{"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`.