# Internet Archive API — search and scrape archive.org's open catalogue of free books, texts, audio, music, concerts, movies, TV, software, games and images: full-text search with mediatype/collection/creator/year filters, complete item metadata with every downloadable file and direct download URLs, collection browsing, user reviews and ratings, and in-book full-text 'search inside' — no API key required

> Search archive.org's catalogue. Filter by mediatype (texts/audio/movies/software/image/etree…), collection, creator, subject, language and year range; sort and paginate. Returns items with identifier, title, mediatype, creator, year, downloads, rating, collections and thumbnail/details URLs.
> ReefAPI engine `internet-archive` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/internet-archive/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 /internet-archive/v1/search — 1 credit
Search archive.org's catalogue. Filter by mediatype (texts/audio/movies/software/image/etree…), collection, creator, subject, language and year range; sort and paginate. Returns items with identifier, title, mediatype, creator, year, downloads, rating, collections and thumbnail/details URLs.

**Parameters:**
- `query` (string, optional) — Free-text search across titles, descriptions, creators and subjects. Accepts Lucene syntax (e.g. 'title:moon AND year:[1960 TO 1970]'). Optional if you pass a mediatype/collection/creator filter instead.
- `mediatype` (enum, optional) — Filter to one archive.org media bucket: texts, audio, movies, software, image, etree (concerts), data, web, collection. [one of: texts, audio, movies, software, image, etree, data, web, collection, account]
- `collection` (string, optional) — Restrict to items in a named collection (its identifier, e.g. 'nasa', 'librivoxaudio', 'prelinger', 'GratefulDead').
- `creator` (string, optional) — Restrict to items by a creator/author/artist name.
- `subject` (string, optional) — Restrict to items tagged with a subject/topic keyword.
- `language` (string, optional) — Restrict to a language (e.g. 'English', 'French', 'Spanish').
- `year_from` (integer, optional) — Only items from this year onward.
- `year_to` (integer, optional) — Only items up to and including this year.
- `sort` (enum, optional) — Result ordering. Defaults to most-downloaded. [one of: downloads desc, downloads asc, week desc, publicdate desc, publicdate asc, date desc, date asc, avg_rating desc, titleSorter asc, titleSorter desc]
- `rows` (integer, optional, default 25) — Results per page (1-100, default 25); clamped.
- `page` (integer, optional, default 1) — Page number (1-based). Page until meta.has_more is false.

**Returns:** results[]{identifier, title, mediatype, creator[], year, date, description, downloads, item_size, collections[], subjects[], languages[], num_reviews, avg_rating, details_url, thumbnail_url} + meta{num_found, page, has_more}

**Example request body:**
```json
{
  "query": "apollo 11"
}
```

### POST /internet-archive/v1/item — 1 credit
Full metadata for one archive.org item by identifier: title, creator, description, date, publisher, language, subjects, collections, license, rating — plus the COMPLETE file list (name, format, size, duration, source) with direct download URLs, and the item's reviews. Set include_files=false / include_reviews=false to slim the payload.

**Parameters:**
- `identifier` (string, required) — The archive.org item identifier (the slug in archive.org/details/<identifier>). From a search result's 'identifier'.
- `include_files` (boolean, optional, default true) — Include the full file list with download URLs (default true).
- `include_reviews` (boolean, optional, default true) — Include the item's reviews (default true).
- `files_limit` (integer, optional, default 200) — Cap on files returned (1-2000, default 200); clamped.

**Returns:** item{identifier, title, mediatype, creator[], description, date, publisher, language[], subjects[], collections[], licenseurl, uploader, num_reviews, avg_rating, item_size, files_count, files[]{name,format,size,length,source,download_url}, reviews[]{reviewer,stars,title,body,date}, details_url, thumbnail_url}

**Example request body:**
```json
{
  "identifier": "OTRR_Dragnet_Singles"
}
```

### POST /internet-archive/v1/collection — 1 credit
Browse the items inside an archive.org collection by its identifier (e.g. 'nasa', 'librivoxaudio', 'prelinger', 'GratefulDead'). Same rich item rows as search, paginated and sortable; optionally narrow by mediatype within the collection.

**Parameters:**
- `collection` (string, required) — The collection identifier to browse (from a search result's 'collections', or a known name).
- `mediatype` (enum, optional) — Filter to one archive.org media bucket: texts, audio, movies, software, image, etree (concerts), data, web, collection. [one of: texts, audio, movies, software, image, etree, data, web, collection, account]
- `query` (string, optional) — Free-text search across titles, descriptions, creators and subjects. Accepts Lucene syntax (e.g. 'title:moon AND year:[1960 TO 1970]'). Optional if you pass a mediatype/collection/creator filter instead.
- `sort` (enum, optional) — Result ordering. Defaults to most-downloaded. [one of: downloads desc, downloads asc, week desc, publicdate desc, publicdate asc, date desc, date asc, avg_rating desc, titleSorter asc, titleSorter desc]
- `rows` (integer, optional, default 25) — Results per page (1-100, default 25); clamped.
- `page` (integer, optional, default 1) — Page number (1-based). Page until meta.has_more is false.

**Returns:** results[] (same shape as search) + meta{num_found, page, has_more, collection}

**Example request body:**
```json
{
  "collection": "librivoxaudio"
}
```

### POST /internet-archive/v1/reviews — 1 credit
All public reviews and star ratings for one archive.org item: reviewer handle, star rating (0-5), review title, body and date. Reviews are embedded in the item record, so this returns every review in one call (no pagination needed).

**Parameters:**
- `identifier` (string, required) — The archive.org item identifier (the slug in archive.org/details/<identifier>). From a search result's 'identifier'.

**Returns:** reviews[]{reviewer, title, body, stars, date} + meta{record_count, avg_rating, num_reviews}

**Example request body:**
```json
{
  "identifier": "OTRR_Dragnet_Singles"
}
```

### POST /internet-archive/v1/files — 1 credit
Just the downloadable files for one archive.org item (no heavy metadata/reviews): name, format, size, duration, source and a direct download URL for each. Useful for fetching the actual book PDF / MP3 / video / ZIP.

**Parameters:**
- `identifier` (string, required) — The archive.org item identifier (the slug in archive.org/details/<identifier>). From a search result's 'identifier'.
- `format` (string, optional) — Optional case-insensitive substring filter on the file format (e.g. 'PDF', 'MP3', 'MPEG4', 'EPUB').
- `files_limit` (integer, optional, default 500) — Cap on files returned (1-5000, default 500); clamped.

**Returns:** files[]{name, format, size, length, source, md5, download_url} + meta{record_count, files_count, server, dir}

**Example request body:**
```json
{
  "identifier": "OTRR_Dragnet_Singles"
}
```

### POST /internet-archive/v1/search_inside — 1 credit
Full-text 'search inside' one digitized book on archive.org: find a phrase within the book's OCR text and get the matching snippets with page numbers. The item must be a texts/book item with OCR (most scanned books are).

**Parameters:**
- `identifier` (string, required) — The archive.org item identifier (the slug in archive.org/details/<identifier>). From a search result's 'identifier'.
- `query` (string, required) — The phrase to find inside the book's text.

**Returns:** matches[]{text, page, par[]} + meta{record_count, query}

**Example request body:**
```json
{
  "identifier": "adventuresoftoms00twaiiala",
  "query": "whitewash"
}
```

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