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	lookup_isbn	Exact, cached, cheapest
Edition id fds_ed_…	GET /v1/books/:id	get_book	Point lookup
Work id fds_wk_…	GET /v1/works/:id	get_work	Synopsis lives on the work
Author id fds_au_…	GET /v1/authors/:id	—	Contributor record
A title to identify the book	POST /v1/match	resolve_book	Ranked candidates; take the first
An author name only	GET /v1/authors/search	search_authors	Not search_books
Genre browse	GET /v1/books/search?genre=	search_books + genre=	Closed facet, not q=epic fantasy
Books like these	POST /v1/recommend	recommend_books	Content similarity, not social taste
Exploratory / filtered browse	GET /v1/books/search	search_books	Not the first choice for a known title
GTIN / UPC / EAN	GET /v1/gtin/:gtin	lookup_gtin	Exact, cached
Food id fds_fo_…	GET /v1/foods/:id	get_food	Point lookup
Brand id fds_fb_…	GET /v1/brands/:id	—	Brand record (same idea as authors)
A product name	POST /v1/match	resolve_food	Same match route as books; take candidates[0]
A brand name	GET /v1/brands/search	search_brands	Not search_foods
Foods like this	GET /v1/foods/:id/similar or GET /v1/gtin/:gtin/similar	similar_foods	Same category, label macros
IMDb id tt… / nm…	GET /v1/imdb/:imdb_id	lookup_imdb	Exact; returns a title or a person
Title id fds_fi_… fds_tv_… fds_se_… fds_ep_…	GET /v1/titles/:id	get_title	Point lookup
Person id fds_pe_…	GET /v1/people/:id	get_person	Person record with known_for
A film or show to identify	POST /v1/match	resolve_title	dataset=movies_tv; take candidates[0]
A person name only	GET /v1/people/search	search_people	Not search_titles
Episodes of a series	GET /v1/titles/:id/episodes	get_episodes	season= narrows
Sync since a cursor	GET /v1/changes	get_changes	dataset=food or dataset=movies_tv; books empty on 2026-09.2
Parquet dump	GET /v1/datasets/books/releases/latest	—	Also `/v1/datasets/{food
Dataset catalog / freshness	GET /v1/datasets	—	latest_release plus per-source cadence

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|foods|brands|titles|people}/: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. Barcode present → lookup_gtin / GET /v1/gtin/:gtin. Never pass a GTIN as q on food search.
9. User named a food → resolve_food / POST /v1/match with name / gtin (or dataset=food).
10. IMDb id present → lookup_imdb / GET /v1/imdb/:imdb_id. Never pass an IMDb id as q on title search.
11. User named a film or show → resolve_title / POST /v1/match with title (+ year, kind, or dataset=movies_tv).
12. You are syncing a cache → get_changes. On books release 2026-09.2 the list is empty. Pass dataset=food or dataset=movies_tv.

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.