# Choose an endpoint

Pick **one** call. Do not search when you already have an ISBN or an id.

| You have | REST | MCP | Why |
|---|---|---|---|
| ISBN-10 or ISBN-13 | [`GET /v1/isbn/:isbn`](/docs/isbn) | `lookup_isbn` | Exact, cached, cheapest |
| Edition id `fds_ed_…` | [`GET /v1/books/:id`](/docs/books) | `get_book` | Point lookup |
| Work id `fds_wk_…` | [`GET /v1/works/:id`](/docs/works) | `get_work` | Synopsis lives on the work |
| Author id `fds_au_…` | [`GET /v1/authors/:id`](/docs/authors) | — | Contributor record |
| A title to identify *the* book | [`POST /v1/match`](/docs/match) | `resolve_book` | Ranked candidates; take the first |
| An author name only | [`GET /v1/authors/search`](/docs/authors) | `search_authors` | Not `search_books` |
| Genre browse | [`GET /v1/books/search?genre=`](/docs/search) | `search_books` + `genre=` | Closed facet, not `q=epic fantasy` |
| Books like these | [`POST /v1/recommend`](/docs/recommend) | `recommend_books` | Content similarity, not social taste |
| Exploratory / filtered browse | [`GET /v1/books/search`](/docs/search) | `search_books` | Not the first choice for a known title |
| Sync since a cursor | [`GET /v1/changes`](/docs/changes) | `get_changes` | Empty on this first release |
| Parquet dump | [`GET /v1/datasets/books/releases/latest`](/docs/bulk) | — | Same Bearer key |

## Decision rules

1. **ISBN present** → `lookup_isbn` / `GET /v1/isbn/:isbn`. Never pass an ISBN as `q` on search.
2. **Stable id present** → the matching `GET /v1/{books|works|authors}/:id`.
3. **User named a book** (“the Andy Weir Hail Mary”) → `resolve_book` / `POST /v1/match`. Read `candidates[0]`.
4. **Author only** → `search_authors` / `GET /v1/authors/search`.
5. **Genre browse** → `search_books` with `genre=fantasy` (not `q=` as a genre name).
6. **Books like these** → `recommend_books` / `POST /v1/recommend`. Content similarity.
7. **User is browsing titles** → `search_books` with filters.
8. **You are syncing a cache** → `get_changes`. On release `2026-09.2` the list is empty.

## Ranking note

Search and match fold articles/apostrophes/subtitles, drop study guides and companions when a real title exists, prefer **primary** over graphic novels unless the query looks graphic, then collapse to **one canonical edition** for that work.

## Check record

`9780593135204` / `Project Hail Mary` / Andy Weir. Expect a description and a non-empty `authors` array.