# Albumoftheyear — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for music albums and discover their release dates, genres, and record labels, while browsing the best-rated and newest releases from across the music industry. Find detailed information about any album to stay updated on new music and make informed decisions about what to listen to next.

**Category:** Music | **Website:** [albumoftheyear.org/](https://albumoftheyear.org/) | **Docs:** [parse.bot/marketplace/7e7d9982-b2fa-495d-b421-d2fd98a33f84/albumoftheyear-org-api](https://parse.bot/marketplace/7e7d9982-b2fa-495d-b421-d2fd98a33f84/albumoftheyear-org-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-albumoftheyear-org-api-7e7d9982/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_album_details

Fetch full metadata for one album by its path. Returns critic and user scores, genres, labels, release date, and extra details (producer, writer, tags, format). The path is obtained from search_albums, get_best_albums, or get_new_releases results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `album_path` | string | Yes | The album path from search_albums results[*].path, get_best_albums results[*].path, or get_new_releases results[*].path (e.g. '/album/29250-kendrick-lamar-to-pimp-a-butterfly.php'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-albumoftheyear-org-api-7e7d9982/get_album_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"album_path":"<string>"}'
```

### get_best_albums

Retrieve ranked album lists by year or all-time, ordered by critic score, review count, or user score. Results are paginated. Each album includes rank, scores, genres, and a path for detail lookup.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `list_type` | string | No | Type of ranking list. |
| `page` | integer | No | Page number for pagination. |
| `year` | string | No | The year to filter by (e.g. '2024') or 'all' for all time. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-albumoftheyear-org-api-7e7d9982/get_best_albums \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list_type":"<string>","page":"<integer>","year":"<string>"}'
```

### get_genres

Retrieve the full list of music genres from the genre index. Each genre includes its name, numeric identifier (as used in site URLs and filters), and a direct URL. No pagination — the complete list is returned in a single response.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-albumoftheyear-org-api-7e7d9982/get_genres \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_new_releases

List the most recent album releases in reverse chronological order. Returns a paginated list with artist, title, release info (date and format), scores, review counts, and a path for detail lookup.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-albumoftheyear-org-api-7e7d9982/get_new_releases \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### search_albums

Full-text search over albums. query matches artist names and album titles. Returns paginated results ordered by relevance. Each result carries a path suitable for get_album_details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search query for album or artist name. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-albumoftheyear-org-api-7e7d9982/search_albums \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```