First Steps With the Plainpad REST API
Most note apps treat your notes as something you visit. Plainpad exposes a REST API, so they are also something you can script.
That opens up the boring-but-useful things: a nightly export, a script that appends to today’s journal note, a dashboard that shows how much you wrote this month.
Authenticate first
Every request needs a session token. Start by logging in:
curl -X POST https://notes.example.com/api.php/v1/sessions \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"your-password"}'
The response is a small JSON object with user_id, expires_at and token.
Store the token and send it as a bearer header on every later call - there are
no cookies involved:
TOKEN=$(curl -s -X POST https://notes.example.com/api.php/v1/sessions \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"your-password"}' | jq -r '.token')
Keep that token out of your repository and shell history - it is a live
credential until expires_at.
List your notes
curl -H "Authorization: Bearer $TOKEN" \
https://notes.example.com/api.php/v1/notes | jq '.'
jq is not required, but reading raw JSON in a terminal is a punishment.
To pull just the titles:
curl -s -H "Authorization: Bearer $TOKEN" \
https://notes.example.com/api.php/v1/notes \
| jq -r '.[] | .title'
Read a single note
Notes are identified by a UUID, which is the id field in the list:
curl -s -H "Authorization: Bearer $TOKEN" \
https://notes.example.com/api.php/v1/notes/$NOTE_ID | jq -r '.content'
Create one
curl -X POST https://notes.example.com/api.php/v1/notes \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"title":"Scripted note","content":"Scripted note\nWritten by curl.","pinned":false}'
Put the title on the first line of content as well: the app takes a note’s
title from its first line, so a separate title is replaced the next time
someone edits the note in the interface.
That single call is enough to build a capture script - a shell function that takes a line of text and files it into a note, so an idea goes from your head to your own server without opening a browser.
Things worth knowing before you build on it
- The API follows the same permission model as the interface. A user with a limited role through the UI has exactly the same limits through the API. There is no back door, by design.
- Rate limiting applies to login. A script that retries a failed login in a tight loop will lock itself out, which is the correct behaviour and still annoying at 2am. Add a sleep.
- Always use HTTPS. The login request carries your password in the body.
Where to point it next
The useful first project is an exporter: walk the list, fetch each note, write
it to a .txt file named after the title. Twenty lines of shell, and suddenly
your notes exist in a format that outlives any app - including this one.
That is the whole argument for plain text, made executable.
Want a hand with Plainpad?
We can host it for you, help you fix a problem, put your brand on it, build something new or move your notes over.
See our services