Quick API use examples

Ready-to-copy curl for the most common workflows. For auth, error envelope, and rate limits, see the main API docs. Working with folders? Jump to the Folders API page.

Filename = title

On POST /api/v1/notes the filename is derived from your title (NFC-normalized, slashes and control / format characters stripped, truncated to 200 bytes). Same rule the /notes/by-filename/:filename endpoint uses — so a note created here with title cron-jobs-prod is immediately addressable as /notes/by-filename/cron-jobs-prod for later appends.

Blank title → filename auto-generated as YYYYMMDD-HHMMSS-<hex>.txt.
A title that resolves to a filename you already have returns 422 validation_failed — pick a different title.
Bulk endpoint follows the same rule per row, including same-batch dedup.

Create an editable (CRUD) note

Default mode — the note can be PATCHed, appended, and deleted via the API. Filename is set to the (sanitized) title: engineering-journal. Note: API edits to a CRUD note do not push to an open browser tab — refresh the page to see changes made through the API.

curl ... ...<% end %%> Keep the opening `do %%>` glued to the `curl` so the captured block has no leading newline; the layout doesn't trim. %>

curl -X POST https://freshjots.com/api/v1/notes \
  -H "Authorization: Bearer $MYNOTES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"engineering-journal","plain_body":"fixed the auth bug"}'

Create an append-only (log) note

append_only: true locks the note: PATCH and DELETE return 403 note_locked; only POST /notes/:id/append (or by filename) can add to it. Toggle the lock off in the browser if you ever need to edit it. Filename is again the title: cron-jobs-prod. Bonus: appends through the API push to an open browser tab automatically via Turbo — the viewer sees new content land in real time, no refresh needed.

curl ... ...<% end %%> Keep the opening `do %%>` glued to the `curl` so the captured block has no leading newline; the layout doesn't trim. %>

curl -X POST https://freshjots.com/api/v1/notes \
  -H "Authorization: Bearer $MYNOTES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"cron-jobs-prod","plain_body":"backup ok 2026-04-26 03:00","append_only":true}'

Append to a stream by filename

For the append-only log above, subsequent log lines target it by filename — no need to remember the id. Creates the note if it doesn't already exist.

curl ... ...<% end %%> Keep the opening `do %%>` glued to the `curl` so the captured block has no leading newline; the layout doesn't trim. %>

curl -X POST https://freshjots.com/api/v1/notes/by-filename/cron-jobs-prod/append \
  -H "Authorization: Bearer $MYNOTES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"backup ok 2026-04-27 03:00"}'

List recent notes

curl ... ...<% end %%> Keep the opening `do %%>` glued to the `curl` so the captured block has no leading newline; the layout doesn't trim. %>

curl https://freshjots.com/api/v1/notes?format=plain \
  -H "Authorization: Bearer $MYNOTES_API_TOKEN"

Back to the main API docs. Questions? Contact me directly.