Reference

API reference

A REST API over your notes, drafts, literature notes and collections. JSON in, JSON out, one token.

The REST API gives you full read and write access to the same data your account has inside the app. Every endpoint lives under https://thinkernotes.com/api/v1, accepts and returns JSON, and is scoped to the account that owns the token, so there's no way for a token to see or change another user's data.

Authentication

Send your API token as a bearer header on every request. See Getting started to create one.

Header
Authorization: Bearer tn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Notes

The core content type: a single atomic idea, with text, tags and an optional source. It's called Insight inside the app, and note everywhere in the API. These endpoints cover every note you've kept, including the ones in a collection, but not drafts. A note's source is the collection it belongs to, written as the collection's title and author, so a note in your copy of Meditations comes back with "source": "Meditations, Marcus Aurelius".

MethodPathDescription
GET/notesList notes, most recent first. Add ?query= to search text and tags, ?limit= to cap results (default 10, max 50).
GET/notes/:idFetch one note's full text, source, tags and linked note ids.
POST/notesCreate a note. Add "source" with the name of a collection (a book, an author or a place) if you want to remember where the idea came from. If you don't have a collection by that name yet, one is made for you.
PATCH/notes/:idUpdate a note's text, source or tags. Sending "source": null takes the note out of its collection, and leaving source out keeps it where it is.
DELETE/notes/:idDelete a note.

Create and update take a note object:

FieldTypeRequiredDescription
textstringYesThe note's content, at least 10 characters.
tagsarray of stringsNoReplaces the note's tags.
parent_idinteger or nullNoThe id of the note this one continues, which makes it a follow-up of that note. It has to be one of your notes, and null takes the note out of its trail.
curl https://thinkernotes.com/api/v1/notes \
  -H "Authorization: Bearer tn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "note": { "text": "The obstacle is the way", "tags": ["stoicism"] } }'

A note, as returned by GET /notes/:id, POST /notes or PATCH /notes/:id:

Note
{
  "id": 42,
  "text": "The obstacle is the way",
  "source": "Meditations, Marcus Aurelius",
  "tags": ["stoicism"],
  "created_at": "2026-08-02T10:14:00Z",
  "linked_note_ids": [],
  "parent_id": null,
  "follow_up_ids": [43, 57]
}

parent_id is the note this one continues, if it's a follow-up, and follow_up_ids are the notes that continue it, oldest first. A thought can branch, so a note can have several follow-ups, and deleting a note keeps them.

GET /notes returns the same shape without linked_note_ids, parent_id and follow_up_ids, as an array, with text truncated into an excerpt field.

Drafts

Quick, unstructured inbox notes, the raw material before it becomes a note.

MethodPathDescription
GET/draftsList drafts, most recent first. ?query= and ?limit= supported.
GET/drafts/:idFetch one draft's full text.
POST/draftsCreate a draft. Body: { "draft": { "text": "..." } }.
PATCH/drafts/:idUpdate a draft's text.
DELETE/drafts/:idDelete a draft.

Literature notes

Notes taken on one of your collections, like a book, an article or a podcast. Each one is also a note, so /notes returns it too, though a literature note written before November 2026 has a different id there.

MethodPathDescription
GET/literature_notesList literature notes, most recent first. ?query= and ?limit= supported.
GET/literature_notes/:idFetch one literature note's full text.
POST/literature_notesCreate a literature note. Body: { "literature_note": { "text": "...", "collection_id": 1 } }. The collection_id is required, because every literature note comes from a source, and it has to be one of yours.
PATCH/literature_notes/:idUpdate the text or move it to a different collection.
DELETE/literature_notes/:idDelete a literature note.

Collections

A source you're taking literature notes on, like a book, an article or a podcast.

MethodPathDescription
GET/collectionsList collections, most recent first. ?query= matches title and author, ?limit= caps results.
GET/collections/:idFetch one collection.
POST/collectionsCreate a collection.
PATCH/collections/:idUpdate a collection.
DELETE/collections/:idDelete a collection, along with all the literature notes you saved from it.

Create and update take a collection object:

FieldTypeRequiredDescription
titlestringYesMust be unique within your account.
authorstringNo
current_pageintegerNoOn a book, the page you're on. It starts at 0 and can't go past total_pages. Changing it also sets the book's status, so 0 is not started, the last page is finished and anything in between is in progress.
kindstringNoOne of book, podcast, article, other, subject. A subject is something you're learning, and it can hold other collections. Defaults to book.
parent_idintegerNoDeprecated, so use subject_ids instead. A subject's id puts the collection in that one subject only, and null takes it out of every subject it's in.
subject_idsarray of integersNoThe ids of the subjects this collection is in. A collection can be in several subjects, and its notes count in each of them. Sending it replaces the whole list, so send [] to take the collection out of every subject, and leave it out to keep the subjects as they are. A subject can't go inside another subject.
statusstringNoOne of not_started, in_progress, finished.
total_pagesintegerNoOn a book, how many pages it has. Send null if you don't know.
urlstringNo

Every collection comes back with its subject_ids, in the order it was added to them, which is an empty array when it isn't in a subject. It also still comes back with parent_id, the first of those ids or null, so older integrations keep working. Fetching one collection also returns collection_ids, the ids of the collections inside it, oldest first, and that's an empty array on anything that isn't a subject. It also returns current_page and total_pages, which only mean something on a book.

Errors

StatusCause
401 UnauthorizedMissing or invalid bearer token
404 Not FoundThe record doesn't exist, or belongs to another account
422 Unprocessable EntityValidation failed, the response body has an errors array
204 No ContentA DELETE succeeded

Want read-only, assistant-facing access instead of full read and write? Take a look at the MCP server. Same data, just no write tools.