Agents and the API
You can let an AI assistant like Claude write into your docs, or connect your own scripts. Here is how, and how you stay in control of what they can do.
Connect Claude or another AI app
AI apps talk to Markpad through MCP, an open standard that lets an assistant use other tools for you. Once connected, you can ask something like "write up today's meeting as a doc in Markpad", and it does.
Every app connects to the same address, https://api.markpad.md/mcp. There's no key to copy: the first time, the app opens Markpad so you can sign in, and shows you what it's asking to do. That's reading and writing your docs, plus sharing them or moving them to Trash only if you switch those on. Choose Allow when you're happy.
Run this once in your terminal. Then sign in: run /mcp inside Claude Code, or claude mcp login markpad.
claude mcp add --transport http --scope user markpad https://api.markpad.md/mcpYou can see every app you've allowed under Connected apps on your profile. Disconnect one and it loses access within 15 minutes.
Here's what a connected app can do:
| Tool | What it does |
|---|---|
list_docs | List your docs and folders |
search_docs | Find docs by title or text |
get_doc | Read a doc, and its images if asked |
create_doc | Write a new doc |
edit_doc | Change one passage in a doc |
replace_doc | Rewrite a whole doc |
append_to_doc | Add text to the end of a doc |
share_doc | Change who can open a doc |
trash_doc | Move a doc to Trash |
create_folder, update_folder, trash_folder | Make, rename, move or remove a folder |
list_pinned, pin, reorder_pinned | See and change your pins |
Each app can make up to 120 requests a minute.
API keys
If you write your own scripts, for example a nightly backup, you'll want an API key. It's a password just for that script.
Go to Profile → API keys → Create key. Give it a name you'll recognise, like "Laptop backup script". Then choose what it's allowed to do (read your docs, create and edit them, share them, move them to Trash) and when it should stop working: after 30 days, 90 days, a year, or never.
The key starts with mp_ and is shown only once, so copy it straight away and keep it somewhere safe. You can have up to 20 keys. Delete a key and it stops working immediately.
The REST API
The API lets a script do what you do in the editor. Its address is https://api.markpad.md/v1, and the full reference is at api.markpad.md/v1/docs. Send your key with every request, like this:
Authorization: Bearer mp_…
| Method | Path | What it does | The key needs |
|---|---|---|---|
GET | /documents | List your docs (?q= to search, ?folderId= for one folder) | Read |
POST | /documents | Create a doc | Create and edit |
GET | /documents/{id} | Read a doc and its version | Read |
PUT | /documents/{id} | Rewrite a whole doc | Create and edit |
PATCH | /documents/{id} | Change one passage | Create and edit |
POST | /documents/{id}/append | Add text to the end | Create and edit |
PUT | /documents/{id}/access | Change who can open it | Share |
PUT | /documents/{id}/address | Give it a custom address | Share |
PUT | /documents/{id}/pin | Pin or unpin it | Create and edit |
DELETE | /documents/{id} | Move it to Trash | Trash |
GET | /folders | List your folders | Read |
POST | /folders | Create a folder | Create and edit |
PATCH | /folders/{id} | Rename or move a folder | Create and edit |
PUT | /folders/{id}/pin | Pin or unpin a folder | Create and edit |
DELETE | /folders/{id} | Move a folder to Trash | Trash |
GET | /pins | List your pinned folders and docs | Read |
PUT | /pins/documents | Reorder pinned docs | Create and edit |
PUT | /pins/folders | Reorder pinned folders | Create and edit |
A doc's text is markdown. If you don't send a title, the doc's first # heading becomes its title. For example, this creates a doc:
curl https://api.markpad.md/v1/documents \
-H "Authorization: Bearer $MARKPAD_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "# From my script\n\nHello from the API."}'
Two things worth knowing:
- Edits never overwrite someone else's work. When you change a doc, send the
versionyou read. If the doc has changed since, Markpad refuses the change, so you can read it again and redo yours. - There's a speed limit of 120 requests a minute per key.