Scratchpad
Get started

The API

A token, three scopes, and twelve endpoints, so a shortcut or a script can reach your notes.

An API token lets a phone shortcut, a script, or an app on another computer reach your notes without signing in. Create one in Settings → API tokens.

Scopes

Scope What it can do
capture Create notes, text and all. It cannot read a single one back
read List, read and search notes. It cannot change anything
full Read, search, create, edit, and organise folders

capture and read aren't nested inside each other. A shortcut that files thoughts into an inbox has no need to read everything you've ever written, so a capture token on a lost phone gives nothing away.

Authenticating

Send the token as a bearer credential:

curl -H "Authorization: Bearer scr_..." https://app.scratchpad.sh/api/notes

Endpoints

Only these accept a token. Nothing else does, so a token can never create or revoke a token, or change your account.

Method Path Scope Does
GET /api/notes read Every note stub, plus folders
POST /api/notes capture Create a note; text or markdown, and folderId, all optional
GET /api/notes/:id read One note, including its document JSON
GET /api/notes/:id/export?format=md read One note as Markdown, plain text or JSON
PATCH /api/notes/:id full Edit: doc or markdown, plus title, folderId, pinned
POST /api/notes/:id/append full Add to the end, keeping what is there
GET /api/search?q= read Full-text search across your notes
GET /api/notes/:id/attachments read What files a note has, and the text inside one: ?file= with ?q= to search it, or ?from= and ?to= for a page range
GET /api/folders read Every folder, with parent_id set on the ones inside another
POST /api/folders full Create one: name, and parentId to put it inside another
PATCH /api/folders full Rename with id and name, or move with parentId and order: every folder that should end up inside parentId, in order
DELETE /api/folders full Delete: id. Only an empty folder, over a token

To file a note, PATCH /api/notes/:id with folderId, or null to take it out of its folder.

A token can delete a folder only when it's empty. One still holding notes or sub-folders gets a 409 saying what's in it. Deleting from the app asks first and can be undone, so it isn't limited this way.

Text or Markdown

Anywhere a body is written you can send text or markdown, never both.

text is plain: one paragraph per line, and a line starting with # stays a line starting with #. That suits a shortcut or a mail rule, which is capturing words rather than composing them.

markdown is parsed, so headings, lists, task lists, tables, and code fences arrive as themselves. That suits an assistant. Anything the editor can't hold is flattened to text rather than refused.

Reading works the same way round. GET /api/notes/:id hands back the document JSON, which is exact, but means understanding its structure. GET /api/notes/:id/export hands back Markdown, and that's the one to read prose from.

Appending

Use POST /api/notes/:id/append rather than reading a note, adding a line, and sending the whole thing back with PATCH. Anything typed in the app between your read and your write would be lost by that write. Append adds to the note as it is at that moment.

curl -X POST https://app.scratchpad.sh/api/notes/NOTE_ID/append \
  -H "Authorization: Bearer scr_..." \
  -H "Content-Type: application/json" \
  -d '{"markdown": "- [ ] ring the dentist"}'

An entirely empty note is replaced rather than appended to, so the first line still becomes the title. A note with real text in it keeps every blank line exactly where you left it.

Last updated 21 September 2026