Notes API

Full reference for creating, fetching, updating, pinning, archiving, and managing notes.

The Notes API provides full lifecycle control over your personal notes.

Note Schema

{
  "id": "7b79da93-ca77-4cf0-9dc4-14227363b965",
  "noteType": "text",
  "title": "Project Roadmap 2026",
  "content": "## Goals\n- Launch SNotes Public API\n- Expand MCP tools",
  "color": "#fef08a",
  "isPinned": false,
  "archived": false,
  "trashedAt": null,
  "hasPassword": false,
  "permission": "owner",
  "checkboxes": [],
  "categories": [
    {
      "id": "e4587563-7182-4df3-a16a-a2fcda00a293",
      "name": "Work",
      "color": "#93c5fd"
    }
  ],
  "media": [],
  "reminder": null,
  "createdAt": "2026-08-18T10:00:00Z",
  "updatedAt": "2026-08-18T10:35:00Z"
}

Fields

Field	Type	Description
`id`	`UUID`	Unique identifier for the note.
`noteType`	`string`	Either `"text"` (regular note) or `"checklist"` (task list with checkboxes).
`title`	`string`	Note title (max 255 chars). Defaults to empty string.
`content`	`string`	Markdown text content for `text` notes. Must be empty for `checklist` notes.
`color`	`string \| null`	Hex background color (e.g. `"#fef08a"`), or `null` for default.
`isPinned`	`boolean`	Whether the note is pinned to the top of the grid.
`archived`	`boolean`	Whether the note is moved to the archive.
`trashedAt`	`string \| null`	ISO 8601 timestamp when moved to trash (soft-delete), or `null`.
`checkboxes`	`array`	List of checkbox items for checklist notes.
`categories`	`array`	List of collections the note belongs to.
`media`	`array`	Attached media metadata (images, audio transcripts).
`reminder`	`object \| null`	Optional scheduled reminder configuration.
`createdAt`	`string`	ISO 8601 timestamp of creation.
`updatedAt`	`string`	ISO 8601 timestamp of last modification.

1. List Active Notes

Returns paginated active notes (excluding archived and trashed notes), sorted according to your custom order and pinned state.

GET /v1/public/notes/

Query Parameters

Parameter	Type	Default	Description
`limit`	`integer`	`20`	Number of notes to return (max 100).
`offset`	`integer`	`0`	Number of notes to skip.

Example Request

curl -X GET "https://api.snotes.io/v1/public/notes/?limit=10" \
  -H "Authorization: Bearer sn_live_xxxxxxxxxxxxxxxxxxxxxxxx"

2. Create Note

Create a new text or checklist note.

POST /v1/public/notes/

Request Body

Field	Type	Required	Description
`title`	`string`	No	Title of the note (max 255 chars).
`content`	`string`	No	Body text in markdown format. Leave empty for `checklist`.
`noteType`	`string`	No	`"text"` (default) or `"checklist"`.
`color`	`string`	No	7-character hex color code (e.g. `"#fed7aa"`).
`isPinned`	`boolean`	No	Defaults to `false`.

Example Request

curl -X POST "https://api.snotes.io/v1/public/notes/" \
  -H "Authorization: Bearer sn_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Grocery List",
    "noteType": "checklist",
    "color": "#fef08a"
  }'

3. Retrieve Note

Fetch a single note by its UUID.

GET /v1/public/notes/{note_id}/

Example Request

curl -X GET "https://api.snotes.io/v1/public/notes/7b79da93-ca77-4cf0-9dc4-14227363b965/" \
  -H "Authorization: Bearer sn_live_xxxxxxxxxxxxxxxxxxxxxxxx"

4. Update Note

Partially update an existing note's title, body, color, or pin status.

PATCH /v1/public/notes/{note_id}/

Request Body

Field	Type	Description
`title`	`string`	New title for the note.
`content`	`string`	New body markdown. (Cannot be set on checklist notes).
`color`	`string \| null`	Hex color code or `null` to reset.
`isPinned`	`boolean`	Pin or unpin note.
`expectedUpdatedAt`	`string`	Optional. ISO 8601 timestamp for optimistic concurrency control.

Optimistic Concurrency Control: By supplying expectedUpdatedAt, the server will verify that no other client has modified the note since you last fetched it. If the note was modified elsewhere, the server responds with 409 Conflict.

Example Request

curl -X PATCH "https://api.snotes.io/v1/public/notes/7b79da93-ca77-4cf0-9dc4-14227363b965/" \
  -H "Authorization: Bearer sn_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "content": "New markdown body text."
  }'

5. Delete Note (Permanent)

Permanently destroys the note and all attached checklist rows and media. This operation skips the trash and cannot be undone.

DELETE /v1/public/notes/{note_id}/

Response: 204 No Content

For ordinary user actions, prefer moving notes to trash with POST /v1/public/notes/{note_id}/trash/ so they can be recovered.

6. Pin / Unpin Note

Pins a note to the top of your list, or unpins it.

POST /v1/public/notes/{note_id}/pin/

Request Body

Field	Type	Description
`isPinned`	`boolean`	`true` to pin, `false` to unpin. Omit field to toggle state.

7. Archive / Unarchive Note

Moves a note to the archive or restores it back to active notes. Archiving automatically unpins the note.

POST /v1/public/notes/{note_id}/archive/

Request Body

Field	Type	Description
`archived`	`boolean`	`true` to archive, `false` to unarchive. Omit field to toggle state.

8. Move Note to Trash (Soft Delete)

Moves a note to the trash. Trashed notes are excluded from active list and archive views, but can be restored with restore/.

POST /v1/public/notes/{note_id}/trash/

9. Restore Note from Trash

Restores a trashed note back to the top of your active notes list.

POST /v1/public/notes/{note_id}/restore/

10. List Archived Notes

Returns paginated notes that have been archived.

GET /v1/public/notes/archive/

11. List Trashed Notes

Returns paginated notes currently in the trash, ordered by most recently trashed first.

GET /v1/public/notes/trash/

12. Empty Trash

Permanently and irrevocably deletes all notes currently in the trash.

DELETE /v1/public/notes/trash/

Response

{
  "deleted": 5
}

Notes API

On this page