GET/api/v1/meread
The reader, the token's scopes, and how many books sit on each shelf.
curl https://luku.app/api/v1/me \
-H "Authorization: Bearer $LUKU_API_TOKEN"Everything the web app and the iPhone app can do, over HTTP or through Claude. Your reading is yours: read it, write it, back it up, take it elsewhere.
Mint a personal access token in Luku under Settings, API, choose read-only or read and write, and send it as a bearer token. That is the whole setup.
curl https://luku.app/api/v1/now \
-H "Authorization: Bearer luku_pat_..."The base URL is https://luku.app. A self-hosted Luku serves the same endpoints at its own address.
Two credentials reach the same API. Both are stored hashed, carry a scope, and belong to one account.
| Credential | Prefix | Source |
|---|---|---|
| Personal access token | luku_pat_ | Settings, API in the web app |
| OAuth access token | luku_at_ | The OAuth flow below, used by Claude.ai |
A read token can read everything. Writing needs read write, and a read-only token asking to write is refused with 403 rather than quietly doing nothing.
Luku is its own authorisation server, so signing a client in is the Luku login you already have: email, Google or Apple. There is no separate connector password.
GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource
POST /api/oauth/register dynamic client registration (RFC 7591)
GET /oauth/authorize sign in, then approve what is being asked for
POST /api/oauth/token PKCE S256, refresh rotation
POST /api/oauth/revokeAuthorisation codes last a minute and are single use, access tokens an hour, refresh tokens thirty days and rotate on use. Tokens are bound to https://luku.app/mcp as their audience, so one minted elsewhere is not accepted here.
Luku speaks MCP at https://luku.app/mcp. In Claude.ai, go to Settings, Connectors, Add custom connector, and paste that URL. Leave the client ID and secret empty: Claude registers itself, sends you to the Luku sign-in page, and shows what it is asking for before anything is granted.
claude mcp add --transport http luku https://luku.app/mcp --scope userClaude Code can skip the browser by sending a personal access token instead, or run luku-mcp over stdio.
36 tools. Read tools work with any token; write tools need a read-write one.
| Tool | Description | Scope |
|---|---|---|
luku_me | The reader, their settings and shelf sizes | read |
luku_library | A shelf, or the whole library | read |
luku_book | One book, with its sessions and bookmarks | read |
luku_now | What is being read right now | read |
luku_sessions | Reading sessions, by book or date range | read |
luku_stats | Minutes, pages, books finished, goals | read |
luku_monthly_stats | One month day by day | read |
luku_goals | Yearly and daily goals | read |
luku_bookmarks | Saved links | read |
luku_search_books | Search every source for a book | read |
luku_book_info | Metadata for a book not in the library | read |
luku_find_covers | Cover candidates | read |
luku_author_books | More by the same author | read |
luku_recommendations | Recommendations already generated | read |
luku_export | The library as JSON or markdown | read |
luku_changelog | Published changelog entries | read |
luku_roadmap | Planned features and votes | read |
luku_add_book | Add a book, metadata looked up for you | write |
luku_update_book | Edit metadata, rating or notes | write |
luku_set_status | Move a book between shelves | write |
luku_set_progress | Set the position in page, percent or seconds | write |
luku_delete_book | Remove a book and its sessions | write |
luku_start_timer | Start reading | write |
luku_pause_timer | Pause reading | write |
luku_resume_timer | Resume reading | write |
luku_stop_timer | Stop, and carry the position onto the book | write |
luku_log_session | Record reading that already happened | write |
luku_edit_session | Correct a session | write |
luku_delete_session | Delete a session and give back its progress | write |
luku_set_goal | Set a yearly or daily goal | write |
luku_add_bookmark | Save a link to a book | write |
luku_update_bookmark | Edit a saved link | write |
luku_delete_bookmark | Remove a saved link | write |
luku_set_settings | Theme, tracking method, recommendations | write |
luku_import_books | Import from a Bookshelf export | write |
luku_vote_roadmap | Vote on the roadmap | write |
Who the token belongs to, and the preferences that shape the apps.
/api/v1/mereadThe reader, the token's scopes, and how many books sit on each shelf.
curl https://luku.app/api/v1/me \
-H "Authorization: Bearer $LUKU_API_TOKEN"/api/v1/settingsreadTheme, default tracking method and whether recommendations are on.
/api/v1/settingswriteChange any of those.
| Name | Type | Description |
|---|---|---|
theme | light | dark | system | Colour scheme |
defaultTrackingMethod | time | pages | percent | What a new book is tracked in |
aiRecommendationsEnabled | boolean | Whether recommendations are generated |
Books live on one of five shelves: reading, next-up, to-read, finished and abandoned. Lists are uncapped, so a request for a shelf returns the whole shelf.
/api/v1/libraryreadEvery book, or one shelf of it.
| Name | Type | Description |
|---|---|---|
status | string | Limit to one shelf |
q | string | Match against title, subtitle and author |
curl "https://luku.app/api/v1/library?status=reading" \
-H "Authorization: Bearer $LUKU_API_TOKEN"/api/v1/bookswriteAdd a book. Only the title is required: everything else is looked up the way the app looks it up when a book is added from search.
| Name | Type | Description |
|---|---|---|
titlerequired | string | A trailing subtitle is split off |
author | string | Improves the metadata lookup |
status | string | Defaults to to-read |
progressType | pages | percent | minutes | Defaults to pages |
enrich | boolean | Set false to skip the lookup entirely |
curl -X POST https://luku.app/api/v1/books \
-H "Authorization: Bearer $LUKU_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Piranesi", "author": "Susanna Clarke"}'/api/v1/books/{id}readOne book in full.
/api/v1/books/{id}writeEdit metadata, rating or notes. Passing status moves the shelf and stamps the date that shelf is defined by.
/api/v1/books/{id}writeRemove a book and its sessions.
/api/v1/books/{id}/progresswriteMove the reader's position. The percentage is derived, a book on the to-read shelf starts being read, and the start date is stamped the first time progress appears.
| Name | Type | Description |
|---|---|---|
page | number | For a book tracked in pages |
percent | number | For one tracked in percent |
seconds | number | For an audiobook |
curl -X POST https://luku.app/api/v1/books/$ID/progress \
-H "Authorization: Bearer $LUKU_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"page": 214}'/api/v1/books/{id}/sessionsreadEvery reading session for one book.
A session is the unit of reading. Starting one captures where the book stands; ending one carries the new position back onto the book. Paused time accumulates rather than being subtracted at the end, so a session paused twice still reports reading time and not wall clock.
/api/v1/nowreadThe running or paused session, its elapsed time, and the reading shelf behind it.
/api/v1/users/{username}/nowpublicNow reading, like a now playing feed: the book in the running or paused timer, or null, and the reading shelf. Needs no token and answers from any site, so a personal page can show it. Works when the reader's Currently reading is public, otherwise 403.
curl https://luku.app/api/v1/users/rolle/now
{
"username": "rolle",
"nowReading": {
"state": "active",
"kind": "book",
"startedAt": "2026-11-03T17:05:00Z",
"elapsedSeconds": 1260,
"book": { "title": "...", "author": "...", "coverUrl": "https://..." }
},
"currentlyReading": [{ "title": "...", "author": "...", "coverUrl": "https://...", "lastRead": "..." }]
}/api/v1/sessionsreadSessions newest first.
| Name | Type | Description |
|---|---|---|
bookId | uuid | Only this book |
since | ISO timestamp | Started at or after |
until | ISO timestamp | Started at or before |
/api/v1/sessionswriteStart a session. Passing endedAt writes a finished session in one call, which is how reading typed in after the fact gets logged.
| Name | Type | Description |
|---|---|---|
bookIdrequired | uuid | The book being read |
startedAt | ISO timestamp | Defaults to now |
endedAt | ISO timestamp | Makes this a finished session |
/api/v1/sessions/activereadThe session that has not ended, if there is one.
/api/v1/sessions/{id}writeEdit a session, or end it. Passing endedAt, or finish: true, also carries the end position onto the book.
| Name | Type | Description |
|---|---|---|
endPage | number | Where the reading stopped |
endPercent | number | For a book tracked in percent |
endSeconds | number | For an audiobook |
/api/v1/sessions/{id}writeDelete a session. A finished one takes the book's position back to what the remaining sessions account for.
/api/v1/sessions/{id}/timerwritePause or resume a running session.
| Name | Type | Description |
|---|---|---|
actionrequired | pause | resume | What to do |
Totals derived from the same sessions the other endpoints serve.
/api/v1/statsreadMinutes and pages read today, this week, this month and this year, books finished, and the goals in force.
/api/v1/stats/monthlyreadOne month, day by day.
| Name | Type | Description |
|---|---|---|
year | number | Defaults to this year |
month | number | 1-12, defaults to this month |
/api/v1/goalsreadEvery year's goals.
/api/v1/goalswriteSet a year's goals. Pass null to clear one.
| Name | Type | Description |
|---|---|---|
year | number | Defaults to this year |
yearlyBookGoal | number | null | Books to finish this year |
dailyMinutesGoal | number | null | Minutes to read a day |
Links saved against a book.
/api/v1/bookmarksreadSaved links, optionally for one book.
/api/v1/bookmarkswriteSave a link.
| Name | Type | Description |
|---|---|---|
bookIdrequired | uuid | The book it belongs to |
urlrequired | string | Where it points |
label | string | What to call it |
/api/v1/bookmarks/{id}writeEdit a saved link.
/api/v1/bookmarks/{id}writeRemove a saved link.
The same sources the app searches: Goodreads, Google Books, BookBeat, Open Library, Finna, the Internet Archive and Wikimedia.
/api/v1/searchreadSearch for a book to add.
| Name | Type | Description |
|---|---|---|
qrequired | string | At least two characters |
/api/v1/book-inforeadDescription, page count, publisher, ISBNs and cover for one book.
| Name | Type | Description |
|---|---|---|
title | string | Title, or pass isbn |
author | string | Narrows the match |
isbn | string | Either ISBN form |
/api/v1/coversreadCover candidates from every source, best guesses first.
/api/v1/author-booksreadOther books by the author of a Goodreads book page.
| Name | Type | Description |
|---|---|---|
goodreadsUrlrequired | string | A book page on Goodreads |
excludeTitle | string | Leave this one out |
/api/v1/recommendationsreadRecommendations already generated in the app.
Luku is a place to keep reading, not to trap it. The export is the whole library, and the import fills in what is already there rather than duplicating it.
/api/v1/export/{format}readThe whole library. Formats: json, csv, markdown, goodreads.
curl https://luku.app/api/v1/export/json \
-H "Authorization: Bearer $LUKU_API_TOKEN" -o luku-backup.json/api/v1/importwriteImport books. A book already in the library gets its empty fields filled in, so a re-import never overwrites a correction made by hand.
| Name | Type | Description |
|---|---|---|
csv | string | Contents of a Bookshelf CSV export |
books | array | Parsed rows, instead of csv |
What changed, and what is planned.
/api/v1/changelogreadPublished changelog entries.
/api/v1/roadmapreadPlanned features and their votes.
/api/v1/roadmapwriteVote for a feature, or take the vote back.
| Name | Type | Description |
|---|---|---|
featureIdrequired | uuid | The feature to vote for |
Every failure has the same shape, with the HTTP status to match.
{ "error": "This token is read-only", "code": "forbidden" }| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Something in the request was missing or malformed |
| 401 | unauthorized | No token, an unknown one, or an expired one |
| 403 | forbidden | A read-only token tried to write |
| 404 | not_found | No such book, session or bookmark on this account |
| 429 | rate_limited | Too many requests; wait and retry |
Lists are not capped. A request for a shelf returns the whole shelf, and a request for sessions returns every session in the range asked for.