# Build with the API

NoteMaker has one programming interface: an [MCP](https://modelcontextprotocol.io) server over HTTPS. AI tools such as Claude Code and Cursor use it, and so can your own scripts, because every call is a plain JSON request. Each workspace has its own address, and a token acts as the person who created it, inside that workspace only.

## Start here

-   [⚡ API quickstart](https://docs.wrightdesk.com/build-with-the-api/api-quickstart) creates a token and makes your first call with curl, JavaScript and Python.
-   [📄 Pages and collections: API examples](https://docs.wrightdesk.com/build-with-the-api/pages-and-collections-api-examples) lists, searches, reads, creates, updates and trashes.
-   [🧩 Forms, sheets and boards: API examples](https://docs.wrightdesk.com/build-with-the-api/forms-sheets-and-boards-api-examples) reads responses, adds rows and moves cards.
-   [🛟 Agents, trash and errors: API examples](https://docs.wrightdesk.com/build-with-the-api/agents-trash-and-errors-api-examples) covers the rest of the tools and what a failed call looks like.

## The fourteen tools

Every call names one tool and an `action`. Reading tools never change anything; the `_write` tools do.

| Tool | What it does |
| --- | --- |
| `workspace` | Shows the workspace, its members, collections and forms. |
| `pages`, `pages_write` | Lists, searches and reads pages; creates, updates, moves, locks, shares and trashes them. |
| `collections`, `collections_write` | Lists collections; creates, renames, shares, locks and exports them. |
| `forms`, `forms_write` | Lists forms and reads responses; creates forms and marks responses handled. |
| `sheets`, `sheets_write` | Reads and changes typed tables. |
| `boards`, `boards_write` | Reads boards and cards; creates cards, moves them and sets labels. |
| `agents`, `agents_write` | Lists and manages the workspace's agents. |
| `trash` | Lists, restores and purges deleted pages. |

## Good to know

-   **Create the token yourself.** In **Settings → MCP & API**.
-   **Locked things stay locked.** A write to a locked page, form or collection fails and changes nothing.
-   **Field rules apply.** A value that breaks a field's rule is refused with the reason.
-   **Retrying.** Send an `Idempotency-Key` header (any unique value, such as a UUID) on a call you may repeat. A repeat of the same request within 24 hours gets the first answer back, marked `Idempotency-Replayed: true`, instead of making a second page or card. Without a key, reads and updates are safe to repeat and a create makes another object.
-   **Limits.** Public form submissions, uploads and public search are limited; their answers carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`, and a `429` carries `Retry-After`. Every answer carries `X-API-Version: 1`, and you can send the same header to pin the version.
-   **Testing.** There is no separate sandbox server. Start a free-trial workspace, create a token there and try everything on it; a token only reaches the workspace it was made in.
-   **What changed.** Every release is described in the [release notes](https://app.thenotemaker.com/c/release-notes-6g0q2r7g), also as a [JSON Feed](https://app.thenotemaker.com/c/release-notes-6g0q2r7g/feed.json). The machine-readable contract is at `/openapi.json`, the API catalog (RFC 9727) at `/.well-known/api-catalog` and a ready-to-run collection at `/postman/notemaker.postman_collection.json`.
-   **For tools and models:** every page of this site has a Markdown version at its address ending in `.md`, `/llms.txt` lists them all and `/llms-full.txt` has the text of every page in one file.