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 account. The response carries the folder's id — keep it; you'll pass it as folder_id on note creates and moves.

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

Rename a folder

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

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

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 $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.