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.

Team tier? Every curl below works identically for team tokens — the wire format is the same, the endpoints are the same. The only difference is where the writes land: a team token's POST /notes creates a team note, increments the team's storage pool, and shows up in the team audit log. Mint team tokens at /team/api_tokens.

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.

One curl, one event

Two patterns. Append-only for log streams; standard CRUD for editable notes.

Sending the bearer token — two ways:

A. Export it once, then reference it as $MYNOTES_API_TOKEN in any curl in the same shell session:

export MYNOTES_API_TOKEN="mn_yourrealtokenhere"

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-26 03:00"}'

B. Paste the raw token inline — no $. Fine for one-off testing; the token will sit in your shell history, so rotate it after:

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

The endpoint examples below use option A. The $MYNOTES_API_TOKEN in them is a shell-variable reference — leave the $ in. Replacing the variable name with your literal token (e.g. $mn_realtoken) breaks the request because bash interprets $mn_realtoken as a different (undefined) variable.

Create-or-append by filename

First call creates the note, every subsequent call appends a line — one curl, no id lookup, no setup step. A cron job hitting this URL hourly creates cron-jobs-prod on its first run and adds a line on every run after. By default the note is created as append-only (PATCH/DELETE return 403 note_locked); pass "append_only": false in the body if you'd rather have an editable note instead. Bonus: appends push to an open browser tab via Turbo — the viewer sees new lines land in real time, no refresh needed.

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"}'

Create an editable (CRUD) note

When you want a note that can be PATCHed, appended, and deleted through the API, hit the standard create endpoint. 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 -X POST https://freshjots.com/api/v1/notes \
  -H "Authorization: Bearer $MYNOTES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note":{"title":"engineering-journal","plain_body":"fixed the auth bug"}}'

Alternative: create an append-only note via `/notes`

Equivalent to the create-or-append form above — passing "append_only": true on the standard create endpoint locks the note (PATCH/DELETE return 403 note_locked; only further appends work). Prefer the by-filename form for new streams; reach for this one when you need to set folder_id or another field at creation time.

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

List recent notes

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.