# Radio Index API — Complete Reference

> REST API for the Radio Index catalog by The Archive of American Radio. Structured JSON for 3,054 radio series and 233,264 episode files spanning 1920 to 1982.

The Archive of American Radio is a 501(c)(3) nonprofit that builds digital infrastructure for American radio history. Radio Index is our streaming platform and public API.

---

## Authentication

The Search API is public — no key needed. All other APIs require an API key.

Get a key from your Radio Index dashboard at https://radioindex.org/dashboard#api

Pass the key as a Bearer token:

```
Authorization: Bearer ri_your_key_here
```

Rate limits are per-key with an hourly window. Exceeding the limit returns `429` with `Retry-After` and `X-RateLimit-Remaining` headers.

---

## Pagination

All list endpoints use cursor-based pagination:

```json
{
  "data": [...],
  "pagination": {
    "limit": 50,
    "cursor": "next_cursor_or_null",
    "has_more": true
  }
}
```

Pass `?cursor=VALUE` to fetch the next page. Default limit is 50, max is 100.

---

## Search API

Base URL: `https://search-api.the-archive-of-american-radio.workers.dev`

No authentication required. CORS enabled.

### GET /search

Full-text search across episodes with faceted filtering.

Parameters:
- `q` (required) — Search query. Supports exact phrases with quotes, exclusions with minus, OR groups.
- `page` — Page number (default: 1)
- `series` — Filter by radio show ID
- `genre` — Filter by genre
- `network` — Filter by network (CBS, NBC, Mutual, etc.)
- `sort` — Sort field
- `dir` — Sort direction (asc/desc)
- `dateFrom` — Filter from date (YYYY-MM-DD)
- `dateTo` — Filter to date (YYYY-MM-DD)
- `hasTranscript` — Filter to episodes with transcripts (true/false)
- `includeStats` — Include search statistics
- `statsOnly` — Return only statistics, no results
- `skipFacets` — Skip facet computation for faster response

Returns: Episodes array with facets (shows, genres, networks, date range).

### GET /all

Combined search across all types.

Parameters:
- `q` (required) — Search query

Returns: Results grouped by type (shows, episodes, genres, loglines, transcripts, people, dates).

### GET /shows

Search shows by name.

Parameters:
- `q` (required) — Search query

Returns: Array of `{ radio_show_id, name }`.

### GET /episodes

Search episodes by name.

Parameters:
- `q` (required) — Search query

Returns: Array of `{ episode_id, name, show_name, broadcast_date }`.

### GET /genres

Search genres.

Parameters:
- `q` (required) — Search query

Returns: Array of `{ genre_id, name }`.

### GET /people

Search cast and crew.

Parameters:
- `q` (required) — Search query

Returns: Array of `{ person_id, name, episode_count, credit_types }`.

### GET /loglines

Search episode loglines.

Parameters:
- `q` (required) — Search query

Returns: Array of `{ text, episode_id, episode_name, show_name }`.

### GET /transcripts

Search transcripts.

Parameters:
- `q` (required) — Search query

Returns: Array of `{ excerpt, episode_id, episode_name, show_name }`.

### GET /dates

Find episodes by broadcast date pattern.

Parameters:
- `pattern` (required) — Date pattern

Returns: Array of `{ episode_id, name, broadcast_date, show_name }`.

### GET /episode/:id

Episode detail with transcript excerpt.

Parameters:
- `q` — Optional search term for transcript highlighting

Returns: `{ name, logline, broadcast_date, duration_ms, snr_db, has_transcript, transcript_excerpt, transcript_timestamp }`.

### GET /card/:id

Rich episode card with full context.

Returns: `{ show, airdate, title, logline, prev_episode, next_episode, cast: [{ name, role, character, image, wikipedia }], genres, has_audio, audio_token }`.

---

## Shows API

Base URL: `https://api.radioindex.org`

Authentication required. Cursor-based pagination.

### GET /shows

List radio shows with filtering.

Parameters:
- `q` — Search by name
- `network` — Filter by network
- `genre` — Filter by genre
- `year` — Filter by broadcast year
- `cursor` — Pagination cursor
- `limit` — Results per page (max: 100)

Returns: Array of `{ radio_show_id, name, audio_id, years, episode_count, networks }`.

### GET /shows/:id

Show detail.

Returns: `{ radio_show_id, name, audio_id, years, episode_count, networks, genres, recent_episodes }`.

`recent_episodes` includes the 10 most recent episodes.

---

## Episodes API

Base URL: `https://api.radioindex.org`

Authentication required. Cursor-based pagination.

### GET /episodes

List episodes with filtering.

Parameters:
- `show` — Filter by radio_show_id
- `genre` — Filter by genre_id
- `person` — Filter by person_id
- `airdate` — Exact broadcast date (YYYY-MM-DD)
- `year` — Broadcast year
- `q` — Search by name
- `cursor` — Pagination cursor
- `limit` — Results per page (max: 100)

Returns: Array of `{ episode_id, name, audio_id, radio_show_id, show_name, broadcast_date, duration_ms, logline }`.

### GET /episodes/:id

Episode detail with optional expansions.

Parameters:
- `expand` — Comma-separated list of expansions: `show`, `people`, `files`, `genres`

Expansion details:
- `show`: Full show object `{ radio_show_id, name, audio_id, years }`
- `people`: Array of `{ person_id, name, credit_type, character_name }`
- `files`: Array of `{ episode_file_id, broadcast_date, duration_ms }` (no R2 paths)
- `genres`: Array of `{ genre_id, name }`

### POST /episodes/batch

Batch fetch up to 100 episodes by ID.

Request body:
```json
{
  "ids": ["episode-id-1", "episode-id-2"]
}
```

Returns: `{ episodes: [...] }` with the same fields as the list endpoint.

---

## People API

Base URL: `https://api.radioindex.org`

Authentication required. Cursor-based pagination.

### GET /people

List people with filtering.

Parameters:
- `q` — Search by name
- `role` — Filter by credit type (Actor, Writer, Director, etc.)
- `show` — Filter by radio_show_id
- `cursor` — Pagination cursor
- `limit` — Results per page (max: 100)

Returns: Array of `{ person_id, name, audio_id, episode_count, show_count, credit_types }`.

### GET /people/:id

Person detail.

Returns: `{ person_id, name, audio_id, wikidata_image_url, wikipedia_url, wikidata_qid, episode_count, show_count, roles: [{ credit_type, episode_count }], top_shows }`.

Lookup works by person_id or audio_id (case-insensitive).

---

## Genres API

Base URL: `https://api.radioindex.org`

Authentication required.

### GET /genres

List all genres with counts.

Returns: `{ data: [{ genre_id, name, episode_count, show_count }], total: number }`.

### GET /genres/:id

Genre detail.

Returns: `{ data: { genre_id, name, description, symbol, episode_count, top_shows } }`.

`top_shows` includes up to 20 shows in that genre.

---

## Airdates API

Base URL: `https://api.radioindex.org`

Authentication required. Cursor-based pagination.

### GET /airdates

List distinct airdates with episode counts.

Parameters:
- `year` — Filter by year
- `month` — Filter by month (requires year)
- `cursor` — Pagination cursor
- `limit` — Results per page (1-366, default: 50)

Returns: Array of `{ date, episode_count }` with pagination and total count.

### GET /airdates/:date

Episodes that aired on a specific date.

Date format: `YYYY-MM-DD`

Returns: Array of `{ episode_id, name, audio_id, radio_show_id, show_name, broadcast_date, duration_ms, logline }`.

### GET /airdates/range

Episodes in a date range.

Parameters:
- `from` (required) — Start date (YYYY-MM-DD)
- `to` (required) — End date (YYYY-MM-DD)
- `cursor` — Pagination cursor
- `limit` — Results per page (1-100, default: 50)

Returns: Episodes ordered by airdate ascending, with pagination, total count, and range metadata.

---

## Files API

Base URL: `https://api.radioindex.org`

Authentication required. Cursor-based pagination.

### GET /files

List audio file metadata. Must specify either `episode` or `show`.

Parameters:
- `episode` — Filter by episode_id (required if no `show`)
- `show` — Filter by radio_show_id (required if no `episode`)
- `cursor` — Pagination cursor
- `limit` — Results per page (1-100, default: 20)

Returns: Array of `{ episode_file_id, episode_id, episode_name, radio_show_id, show_name, duration_ms, broadcast_date, broadcast_date_notes, has_commercials, audio_id, file_order, bitrate, file_size, sample_rate, channels, codec }`.

### GET /files/:id

File detail with audio quality metrics.

Returns: All list fields plus `{ is_broadcast_date_unknown, broadcast_time, time_zone, day_of_week, source, quality: { score, grade, label, snr_db, dynamic_range_db } }`.

Note: No R2 file paths are exposed in any response.

---

## Error Responses

All endpoints return standard HTTP status codes:

- `200` — Success
- `400` — Bad request (missing required parameters)
- `401` — Unauthorized (missing or invalid token)
- `404` — Not found
- `429` — Rate limit exceeded
- `500` — Server error

Error response body:

```json
{
  "error": "Description of what went wrong"
}
```

---

## About

The Archive of American Radio is a California nonprofit public benefit corporation (501(c)(3), EIN 41-3077929) that builds and operates the digital infrastructure for American radio history. Founded December 2025 in Los Angeles.

Website: https://archiveofamericanradio.org
Platform: https://radioindex.org
API Docs: https://radioindex.org/developers