# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/albumoftheyear/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/albumoftheyear/get-album-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/albumoftheyear/get-best-albums \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/albumoftheyear/get-genres \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/albumoftheyear/get-new-releases \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/albumoftheyear/search-albums \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.