Folders

Folder endpoints

Folder names are unique per scope (per personal account or per team workspace), case-insensitive, max 80 characters. A duplicate within the same scope returns 422 validation_failed; a personal "Q4" and a team "Q4" coexist freely. Folder ids outside the token's scope return 404 not_found — there's no existence leak.

Manage folders

Create a folder

Name is required and must be unique within your scope (case-insensitive, max 80 characters). The response carries the folder's id — keep it; you'll pass it as folder_id on note creates and moves. Hitting the per-scope cap returns 413 cap_exceeded with the message "folder limit of 100 reached" — delete an unused folder and retry.

curl -X POST https://freshjots.com/api/v1/folders \
  -H "Authorization: Bearer $FRESHJOTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder":{"name":"deploy-logs"}}'

List your folders

Returned alphabetically by lower-case name under a top-level folders array. Each row carries id, name, created_at, and updated_at — note counts aren't embedded; if you need them, see "List notes in a folder" below. The response is unpaginated because the per-scope cap of 100 keeps it bounded.

curl https://freshjots.com/api/v1/folders \
  -H "Authorization: Bearer $FRESHJOTS_TOKEN"

Rename a folder

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

Place notes inside folders

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 -X POST https://freshjots.com/api/v1/notes \
  -H "Authorization: Bearer $FRESHJOTS_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. Omitting folder_id from the body entirely returns 422 validation_failed — the API won't guess between "no change" and "un-folder"; pass null if you mean the latter.

curl -X POST https://freshjots.com/api/v1/notes/123/move \
  -H "Authorization: Bearer $FRESHJOTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":42}'

Un-folder a note (move back to root)

Pass "folder_id": null (or an empty string) to drop the note's folder assignment. The note stays put — only its folder_id goes to null. Useful when you've reorganized and want a note back at the root without deleting the folder it lives in.

curl -X POST https://freshjots.com/api/v1/notes/123/move \
  -H "Authorization: Bearer $FRESHJOTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":null}'

List notes in a folder

The notes index supports a folder_id query parameter, so you don't have to fetch every note and filter client-side. The same pagination, sort, and format filters that work on plain GET /notes compose here.

curl https://freshjots.com/api/v1/notes?folder_id=42 \
  -H "Authorization: Bearer $FRESHJOTS_TOKEN"

To list un-foldered notes (the ones at the root), pass any of the sentinels none, root, or null — all three resolve to "folder_id IS NULL".

curl https://freshjots.com/api/v1/notes?folder_id=none \
  -H "Authorization: Bearer $FRESHJOTS_TOKEN"

A foreign or non-existent folder_id here returns an empty notes array (not 404) — the filter stays inside your scope, so a stale id reads as "nothing to show" rather than leaking ownership information.

Bulk-upload into folders

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 -X POST https://freshjots.com/api/v1/notes/bulk \
  -H "Authorization: Bearer $FRESHJOTS_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 the token's full scope (your personal account, or the entire team workspace) — placement inside a folder doesn't change the route.