First Steps With the Plainpad REST API

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

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.

Services

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