# Listen Notes API — podcast search engine scraper: search podcasts by keyword, get full podcast details (publisher, description, episode count, genres, hosts, latest episodes, cover art, rating) and episode details (audio URL, duration, publish date, description), browse the best podcasts by country and by genre, and read the complete podcast genre taxonomy — from Listen Notes (listennotes.com, 3.7M+ podcasts / 190M+ episodes), no API key required

> Search Listen Notes for podcasts by keyword. Returns up to 10 matching podcasts with title, publisher, cover image and the podcast id (feed into `podcast` for full details).
> ReefAPI engine `listennotes` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/listennotes/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 /listennotes/v1/search — 1 credit
Search Listen Notes for podcasts by keyword. Returns up to 10 matching podcasts with title, publisher, cover image and the podcast id (feed into `podcast` for full details).

**Parameters:**
- `query` (string, required) — What to look for — a topic, show name or person ('startup', 'true crime', 'Joe Rogan', 'bitcoin').

**Returns:** podcasts[]{id, uuid, title, publisher, image, thumbnail, url, is_claimed, explicit}

**Example request body:**
```json
{
  "query": "startup"
}
```

### POST /listennotes/v1/podcast — 1 credit
Full detail for one podcast by id (from search) or a Listen Notes podcast URL: title, publisher, description, cover art, language, country, genres, hosts, rating, total episode count, social links and its latest episodes.

**Parameters:**
- `id` (string, optional) — Podcast id (the short id returned by `search`, e.g. 'ynkdVHl_OTE').
- `url` (string, optional) — Alternatively a full Listen Notes podcast URL.

**Returns:** podcast{id, uuid, title, publisher, description, image, url, language, country, genre_ids[], hosts[], rating, rating_count, total_episodes, extra_urls{}, rss, itunes_url, nlp_entities[], latest_episodes[]{episode_id, title, audio, duration, duration_sec, image, url}}

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

### POST /listennotes/v1/episode — 1 credit
Full detail for one episode by id or a Listen Notes episode URL: title, description, audio URL, duration, publish date, cover art and the parent podcast.

**Parameters:**
- `id` (string, optional) — Episode id (32-char uuid, e.g. from a podcast's latest_episodes[].episode_id).
- `url` (string, optional) — Alternatively a full Listen Notes episode URL.

**Returns:** episode{id, uuid, title, description, audio, audio_length, audio_length_sec, image, url, published, transcript, podcast{title, id, url}}

**Example request body:**
```json
{
  "id": "5d3f3a3fc4534c2ca63c3245f8c2b894"
}
```

### POST /listennotes/v1/best_podcasts — 1 credit
The curated 'best podcasts' list for a country, paginated. Each entry has the podcast title, publisher, cover image, id, Listen Score and global rank.

**Parameters:**
- `region` (enum, optional, default "us") — ISO-3166 country code for the curated list (common set listed; others fall back to the global list). [one of: us, gb, ca, au, de, fr, es, it, nl, se, br, mx, in, jp, kr, cn, tw, hk, sg, ru, tr, za, ph, my, id, th, nz, pt, pl, be]
- `page` (integer, optional, default 1) — Result page (each page is one curated batch). Page until the returned list is empty.

**Returns:** podcasts[]{id, title, publisher, url, image, listen_score, global_rank} + meta{region, page, has_more}

**Example request body:**
```json
{
  "region": "us"
}
```

### POST /listennotes/v1/genre — 1 credit
Browse the best podcasts in a genre, paginated. Use the `genres` action to get the genre id → name list. Each entry has title, publisher, image, id, Listen Score and global rank.

**Parameters:**
- `genre_id` (integer, required) — Numeric genre id (e.g. 93=Business, 127=Technology, 133=Comedy, 135=True Crime, 134=Music). See `genres`.
- `page` (integer, optional, default 1) — Result page (each page is one curated batch). Page until the returned list is empty.

**Returns:** podcasts[]{id, title, publisher, url, image, listen_score, global_rank} + meta{genre_id, genre_name, page, has_more}

**Example request body:**
```json
{
  "genre_id": 93
}
```

### POST /listennotes/v1/genres — 0 credits
The complete Listen Notes genre taxonomy — every genre id mapped to its name. These ids are the input vocabulary for the `genre` action.

**Parameters:** none

**Returns:** genres[]{id, name}, count

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