# Books & Authors API — search books/authors, full book details by ISBN, author bibliographies, all editions, genre/subject browse, trending books, and public-domain ebooks (OpenLibrary + Project Gutenberg)

> merged book record by ISBN-10/13 or OLID (work OL..W / edition OL..M): title/authors/covers/subjects/description/pages/publishers/languages/editions/identifiers/ratings+distribution/reading-log; queried ISBN always injected
> ReefAPI engine `books` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/books/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /books/v1/book_detail — 1 credit
merged book record by ISBN-10/13 or OLID (work OL..W / edition OL..M): title/authors/covers/subjects/description/pages/publishers/languages/editions/identifiers/ratings+distribution/reading-log; queried ISBN always injected

**Parameters:**
- `id` (string, required) — ISBN-10/13, OR OpenLibrary work id (OL..W), OR edition id (OL..M).

**Returns:** book{} — title, authors[], covers, subjects, description, number_of_pages, publishers, languages, editions_count, isbn_10/13, ratings{average,distribution}, reading_log

**Example request body:**
```json
{
  "id": "9780439023528"
}
```

### POST /books/v1/search — 1 credit
search books: q OR fielded (title/author/subject/publisher/place/person/isbn/language); rich cards (ratings/reading-log/ebook_access/IA); sort=new|old|rating|want_to_read|editions; pagination

**Parameters:**
- `q` (string, optional) — Free-text search. Supply `q` OR at least one fielded param (title/author/subject/publisher/place/person/isbn/language).
- `title` (string, optional) — Fielded search filter — match on title (OpenLibrary search). Combinable with other fielded params.
- `author` (string, optional) — Fielded search filter — match on author (OpenLibrary search). Combinable with other fielded params.
- `subject` (string, optional) — Fielded search filter — match on subject (OpenLibrary search). Combinable with other fielded params.
- `publisher` (string, optional) — Fielded search filter — match on publisher (OpenLibrary search). Combinable with other fielded params.
- `place` (string, optional) — Fielded search filter — match on place (OpenLibrary search). Combinable with other fielded params.
- `person` (string, optional) — Fielded search filter — match on person (OpenLibrary search). Combinable with other fielded params.
- `isbn` (string, optional) — Fielded search filter — match on isbn (OpenLibrary search). Combinable with other fielded params.
- `language` (string, optional) — Fielded search filter — match on language (OpenLibrary search). Combinable with other fielded params.
- `sort` (enum, optional) — Result ordering (OpenLibrary sort). Common keys shown; other OpenLibrary sort keys also pass through. [one of: new, old, rating, want_to_read, editions]
- `limit` (integer, optional, default 20) — Results per page (1-100, default 20); out-of-range values are clamped.
- `page` (integer, optional, default 1) — 1-based page number (clamped to 1-1000).

**Returns:** results[] (title, authors[], olid, first_publish_year, ratings, ebook_access, ia ids, cover), numFound, page

**Example request body:**
```json
{
  "q": "the hunger games"
}
```

### POST /books/v1/author — 1 credit
author by OLID (OL..A) → bio/photo/dates/alternate-names/remote-ids(goodreads/wikidata/viaf/gutenberg)/links + include_works; or query/name → best-match-ranked author list

**Parameters:**
- `id` (string, optional) — OpenLibrary author id (OL..A) for a profile. Supply `id` OR a query (`query`/`name`/`q`) for author search.
- `query` (string, optional) — Author search text → best-match-ranked list. Supply this OR `id`.
- `include_works` (boolean, optional, default false) — Profile mode only: also return the author's top works.
- `works_limit` (integer, optional, default 20) — Max works when include_works=true (1-50).
- `limit` (integer, optional, default 10) — Results per page (1-50, default 10); out-of-range values are clamped.

**Returns:** profile: author{name,bio,photo,birth/death,alternate_names,remote_ids,top_works[]}; OR search: results[] (name, olid, work_count)

**Example request body:**
```json
{
  "query": "j r r tolkien"
}
```

### POST /books/v1/author_works — 1 credit
full paginated bibliography of an author (OL..A): every work with cover, first-publish year and subjects; page/limit pagination over the author's complete catalog

**Parameters:**
- `id` (string, required) — OpenLibrary author id (OL..A). Get one from the `author` action.
- `limit` (integer, optional, default 50) — Results per page (1-100, default 50); out-of-range values are clamped.
- `page` (integer, optional, default 1) — 1-based page number (clamped to 1-1000).

**Returns:** results[] (title, olid, covers, first_publish_date, subjects), total, page, has_next

**Example request body:**
```json
{
  "id": "OL26320A",
  "limit": 5
}
```

### POST /books/v1/subjects — 1 credit
browse a subject / genre / theme → ranked work cards PLUS facets (top authors, publishers, related subjects, people, places, time-periods) and work_count/ebook_count; optional ebooks-only and published_in year-range filters; page/limit pagination

**Parameters:**
- `subject` (string, required) — Subject / genre / theme to browse (free text; spaces are fine, e.g. 'science fiction', 'historical fiction', 'love', 'cooking').
- `ebooks` (boolean, optional, default false) — Only return works that have a readable/borrowable ebook.
- `published_in` (string, optional) — Restrict the subject browse to a publish-year range, e.g. 2000-2010.
- `sort` (enum, optional) — Ordering of the subject's works. Known keys shown; others pass through. [one of: editions, new, old]
- `limit` (integer, optional, default 24) — Results per page (1-100, default 24); out-of-range values are clamped.
- `page` (integer, optional, default 1) — 1-based page number (clamped to 1-1000).

**Returns:** subject{name,work_count,ebook_count,related_subjects[],authors[],publishers[],people[],places[],times[]}, results[] (work cards), total, page, has_next

**Example request body:**
```json
{
  "subject": "fantasy",
  "limit": 5
}
```

### POST /books/v1/trending — 1 credit
most popular / trending books for a time window (now|daily|weekly|monthly|yearly) → ranked work cards (title, authors, cover, year, ebook access); page/limit pagination

**Parameters:**
- `period` (enum, optional, default "daily") — Trending window. One of now|daily|weekly|monthly|yearly. [one of: now, daily, weekly, monthly, yearly]
- `limit` (integer, optional, default 24) — Results per page (1-100, default 24); out-of-range values are clamped.
- `page` (integer, optional, default 1) — 1-based page number (clamped to 1-1000).

**Returns:** results[] (title, authors[], olid, first_publish_year, covers, ebook_access), period, page

**Example request body:**
```json
{
  "period": "daily",
  "limit": 5
}
```

### POST /books/v1/editions — 1 credit
every printing / edition of a book (give a work OLID, an edition OLID, or any ISBN) → each edition's ISBN-10/13, publisher, format, publish date/place, page count, language and cover; page/limit pagination

**Parameters:**
- `id` (string, required) — A work OLID (OL..W), an edition OLID (OL..M), or any ISBN of the book — all resolve to the work whose editions are listed.
- `limit` (integer, optional, default 50) — Results per page (1-100, default 50); out-of-range values are clamped.
- `page` (integer, optional, default 1) — 1-based page number (clamped to 1-1000).

**Returns:** results[] (olid, title, isbn_13/10, publishers, publish_date, physical_format, number_of_pages, languages, covers), work_olid, total, page, has_next

**Example request body:**
```json
{
  "id": "OL5735363W",
  "limit": 5
}
```

### POST /books/v1/ebook — 1 credit
public-domain full-text (Project Gutenberg): query OR id=Gutenberg-id OR ids=batch; filters languages/topic/sort; returns formats{epub/txt/html/kindle/cover}+download_url+read_url; gutenberg.org OPDS fallback when gutendex is down

**Parameters:**
- `query` (string, optional) — Full-text search of Project Gutenberg. Supply `query` OR `id` (Gutenberg id) OR `ids` (batch) OR a filter.
- `id` (string, optional) — A single Project Gutenberg ebook id (digits).
- `ids` (array, optional) — Batch of Gutenberg ids (list or comma-separated string).
- `languages` (string, optional) — Gutendex language filter — comma-separated ISO 639-1 codes (e.g. en, fr).
- `topic` (string, optional) — Gutendex topic filter (matches bookshelf or subject).
- `sort` (enum, optional) — Gutendex ordering. Known keys shown; passed through if Gutendex adds more. [one of: popular, ascending, descending]
- `mime_type` (string, optional) — Gutendex mime_type filter (e.g. application/epub+zip, text/plain).
- `author_year_start` (integer, optional) — Gutendex filter: author alive on/after this year.
- `author_year_end` (integer, optional) — Gutendex filter: author alive on/before this year.
- `copyright` (string, optional) — Gutendex copyright filter: true|false|null (comma-separated to combine).
- `limit` (integer, optional, default 32) — Results per page (1-32, default 32); out-of-range values are clamped.
- `page` (integer, optional, default 1) — 1-based page number (clamped to 1-1000).

**Returns:** single: ebook{title,authors,languages,formats{epub/txt/html/kindle/cover},download_url,read_url}; OR list: results[], count, next

**Example request body:**
```json
{
  "id": "1342"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=books
- Human docs page: https://reefapi.com/docs/books
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt