delete_collection
Permanently delete a collection.
Hard-deleting removes the collection resource itself.
For membership-only changes, use note add/remove collection endpoints.
When to use:
- You need irreversible hard-delete behavior for a collection resource.
When NOT to use:
- You only need note membership changes in a collection (`add_note_to_collection` or `remove_note_from_collection`).
add_note_to_collection
Add an existing note to an existing collection.
This operation only creates the membership link and does not modify note or collection content.
Use create endpoints to create notes or collections.
When to use:
- You need to link an existing note to an existing collection.
When NOT to use:
- You need to create notes or collections first (`create_note` or `create_collection`).
remove_note_from_collection
Remove a note from a collection while keeping both resources.
This operation only removes the membership link between IDs.
Use `trash_note` to remove a note from active notes, or `delete_collection` to remove a collection resource.
When to use:
- You need to unlink a note from a collection while keeping both resources.
When NOT to use:
- You need to remove the note from active notes (`trash_note`) or delete the collection resource (`delete_collection`).
list_notes
List notes visible to the authenticated caller with cursor pagination.
When multiple `contains_*` fields are true, a note may match any of them.
Results are ordered by `order_by` and return `next_page` when additional rows are available.
For relevance-ranked retrieval by query, use `search_notes`.
When to use:
- You need deterministic cursor pagination ordered by `updated_at` or `created_at`.
- You are iterating through all accessible notes page by page.
When NOT to use:
- You need relevance-ranked retrieval from open-ended text (`search_notes`).
create_note
Create a note with optional caller-provided ID, timestamps, and collection links.
If `id` already exists, the request behaves as an upsert for that note ID.
The first line of `content` becomes the note title.
When to use:
- You are creating a new note.
- You need idempotent upsert behavior with caller-provided IDs.
When NOT to use:
- You need to overwrite a known existing note by ID (`update_note`).
- You only need to change note/collection membership (`add_note_to_collection` or `remove_note_from_collection`).
search_notes
Search notes using a required free-text query and structured filters.
When multiple `filter_by_contains_*` fields are true, a note may match any of them.
Returns note results from a bounded search snapshot with deterministic offset pagination.
Query-based searches are relevance-ranked within the bounded search snapshot window.
Reuse the returned `snapshot_id` when requesting later pages.
The returned `total` reflects the bounded search snapshot, capped by the 100-result search window.
For deterministic chronological pagination across all accessible notes, use `list_notes`.
When to use:
- You need relevance-ranked retrieval from a natural-language or keyword query.
- You need query + filter retrieval instead of full feed traversal.
When NOT to use:
- You need deterministic chronological pagination (`list_notes`).
get_note
Fetch the full current state of a single note by ID.
For discovery flows, use `list_notes` or `search_notes`.
When to use:
- You already have a note ID and need canonical content + metadata.
When NOT to use:
- You need note discovery without known IDs (`list_notes` or `search_notes`).
update_note
Submit a complete markdown body for a note and optionally set `updated_at`.
Send the full desired body in `content` (not a partial markdown patch).
The first line of `content` becomes the updated title.
When to use:
- You need full-body replacement for an existing note ID.
When NOT to use:
- You need partial patch semantics (not supported).
- You need create/upsert-by-ID behavior (`create_note`).
trash_note
Soft-delete a note by moving it to trash.
Trashed notes can be restored via `restore_note`.
When to use:
- You need reversible removal from active notes.
restore_note
Restore a previously trashed note to the active note set.
This only reverses soft-delete lifecycle state.
When to use:
- You need to undo a prior trash operation.
When NOT to use:
- The note is already active and does not need restoration.