Folders

Folders are mode-agnostic containers — a folder can hold both rich and plain notes — and they're per-user (max 100 per account). The API endpoints below let you create folders, place notes inside them on creation, move existing notes around, and bulk-upload a batch directly into a folder. For auth, error envelope, and rate limits, see the main API docs.

Folder endpoints

Method	Path	Purpose
GET	/folders	List your folders, alphabetical.
GET	/folders/:id	Show a single folder.
POST	/folders	Create a folder. Body: `{folder: {name}}`.
PATCH	/folders/:id	Rename a folder. Body: `{folder: {name}}`.
DELETE	/folders/:id	Delete a folder. Notes inside survive — they lose their folder assignment.
POST	/notes/:id/move	Move a note into a folder. Body: `{folder_id}`.

Folder names are unique per account (case-insensitive), max 80 characters. A duplicate name returns 422 validation_failed. Folder ids belonging to another account return 404 not_found — there's no existence leak.

Manage folders

Create a folder

Name is required and must be unique within your account. The response carries the folder's id — keep it; you'll pass it as folder_id on note creates and moves.

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/folders \
  -H "Authorization: Bearer $MYNOTES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder":{"name":"deploy-logs"}}'

List your folders

Returned alphabetically by name. Each row carries the folder's id and current note count.

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/folders \
  -H "Authorization: Bearer $MYNOTES_API_TOKEN"

Rename a folder

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 PATCH https://freshjots.com/api/v1/folders/42 \
  -H "Authorization: Bearer $MYNOTES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder":{"name":"deploy-logs-2026"}}'

Delete a folder

Notes inside the folder are preserved — they survive the delete and become "un-foldered" (their folder_id drops to null).

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 DELETE https://freshjots.com/api/v1/folders/42 \
  -H "Authorization: Bearer $MYNOTES_API_TOKEN"

Place notes inside folders

Two ways in

On create: pass folder_id in the note body and the new note lands inside the folder in a single round-trip.
After create: use POST /notes/:id/move to relocate a note that already exists.

A foreign or non-existent folder_id returns 404 not_found — same shape as a wrong-id note lookup. Resolve folder ids once (e.g. on script start) and cache them.

Create a note directly in a folder

Same shape as a regular create — just add folder_id. The filename is still derived from the title, so this note is also addressable via /notes/by-filename/2026-04-27 for later appends.

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 '{"note":{"title":"2026-04-27","plain_body":"deploy ok","folder_id":42}}'

Move an existing note into a folder

The dedicated /move endpoint reassigns one note's folder. The note's id, title, filename, body, and append-only flag don't change.

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/123/move \
  -H "Authorization: Bearer $MYNOTES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":42}'

Bulk-upload into folders (Dev-pro)

The bulk endpoint accepts up to 50 notes per call, with a per-row folder_id. Rows can mix folders, and any row may omit folder_id to land at the root.

Folder ids are pre-validated against your account before any row is written. If a single row references a folder you don't own (or that doesn't exist), the entire batch is rejected with 422 validation_failed and the offending row index is in the failed array — nothing partial lands.

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/bulk \
  -H "Authorization: Bearer $MYNOTES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "notes": [
          {"title":"deploy-2026-04-26", "plain_body":"green",        "folder_id":42},
          {"title":"deploy-2026-04-27", "plain_body":"green",        "folder_id":42},
          {"title":"scratch",           "plain_body":"misc thought"}
        ]
      }'

Need to land 200 notes into a folder? Page through the bulk endpoint 50 at a time. Each call is its own atomic transaction.

Caveats

Filename uniqueness is account-wide, not folder-scoped. Two notes can't share a filename even when they're in different folders. A title clash returns 422 validation_failed; pick a different title.
Append-by-filename ignores folders. /notes/by-filename/:filename/append resolves the filename across your whole account — placement inside a folder doesn't change the route.
Folder-scoped listings aren't a single endpoint yet. List with GET /notes, then filter client-side on folder_id from each note's payload.

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