# Discogs API — search the world's biggest database of physical music releases, read a pressing with its full tracklist and credits, and read the marketplace: live lowest asking price and every seller's offer with media and sleeve condition. No account.

> Search Discogs for releases, master releases, artists or labels. Combine free text with artist, title, label, catalogue number, barcode, format, country, year, genre, style, track or credit filters.
> ReefAPI engine `discogs` · 10 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/discogs/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 calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **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 /discogs/v1/search — 1 credit
Search Discogs for releases, master releases, artists or labels. Combine free text with artist, title, label, catalogue number, barcode, format, country, year, genre, style, track or credit filters.

**Parameters:**
- `query` (string, optional) — Free-text search across artist, title, label and catalogue number. Optional when you supply at least one of the field filters.
- `type` (enum, optional, default "release") — What kind of record to return: a pressing (release), a master release, an artist or a label. [one of: release, master, artist, label]
- `artist` (string, optional) — Artist name filter.
- `release_title` (string, optional) — Release title filter.
- `label` (string, optional) — Record label name filter.
- `catno` (string, optional) — Catalogue number printed on the release. Discogs matches this loosely, so it narrows rather than pins.
- `barcode` (string, optional) — Barcode / UPC / EAN as printed on the sleeve.
- `format` (string, optional) — Format filter, Discogs' own spelling: Vinyl, CD, Cassette, LP, Album, Box Set, 7", 12" and so on.
- `country` (string, optional) — Country of release, Discogs' own spelling (UK, US, Japan, Europe).
- `year` (string, optional) — Year of release. A range like 1991-1993 is accepted.
- `genre` (string, optional) — Discogs genre (Rock, Electronic, Jazz, Hip Hop, Classical, Funk / Soul, Pop, Reggae, Latin, Folk, World, & Country).
- `style` (string, optional) — Discogs style, narrower than genre.
- `track` (string, optional) — Track title filter.
- `credit` (string, optional) — Credited person filter (producer, engineer, designer…).
- `page` (integer, optional, default 1) — Result page, 1-based. Discogs stops at page 100 whatever the total.
- `per_page` (integer, optional, default 50) — Rows per page. Discogs caps this at 100 and silently rewrites anything larger.
- `max_rotations` (integer, optional, default 3) — How many times to start over on a fresh connection after a failed attempt.

**Returns:** results[]{id, type, title, year, country, formats, labels, catno, barcodes, genres, styles, master_id, community{have,want}, url}, count, total, pagination{page,per_page,pages,items}

**Example request body:**
```json
{
  "query": "nirvana nevermind",
  "type": "release",
  "per_page": 10
}
```

### POST /discogs/v1/release — 1 credit
One pressing in full: tracklist with per-track credits, release credits, labels and catalogue numbers, formats, identifiers (barcode, matrix/runout), notes, images, videos, community have/want/rating, and live marketplace stats.

**Parameters:**
- `release_id` (string, required) — Numeric Discogs release id (one specific pressing). A full discogs.com release URL is accepted too.
- `include_marketplace` (boolean, optional, default true) — Also fetch live marketplace stats (lowest asking price and how many copies are for sale) and attach them as `marketplace`. One extra, very small upstream call.
- `currency` (enum, optional, default "USD") — Currency the lowest asking price is converted into. [one of: USD, GBP, EUR, CAD, AUD, JPY, CHF, MXN, BRL, NZD, SEK, ZAR, DKK, NOK, PLN]
- `max_rotations` (integer, optional, default 3) — How many times to start over on a fresh connection after a failed attempt.

**Returns:** release{release_id, master_id, title, artists, artist_name, year, released, country, genres, styles, labels, companies, formats, tracklist, credits, identifiers, notes, images, videos, community{have,want,rating_average,rating_count}, num_for_sale, estimated_weight_grams, data_quality, url}, marketplace{num_for_sale,lowest_price,lowest_price_currency,blocked_from_sale}

**Example request body:**
```json
{
  "release_id": 249504
}
```

### POST /discogs/v1/master — 1 credit
The master release — the work itself rather than one pressing — with its canonical tracklist, main release id and how many copies are for sale across all versions.

**Parameters:**
- `master_id` (string, required) — Numeric Discogs master-release id (the work, across pressings).
- `max_rotations` (integer, optional, default 3) — How many times to start over on a fresh connection after a failed attempt.

**Returns:** master{master_id, title, artists, year, main_release_id, most_recent_release_id, genres, styles, tracklist, images, num_for_sale, url}

### POST /discogs/v1/master/versions — 1 credit
Every pressing of a master release, with the format / label / country / year facets Discogs itself offers so you can see what exists before filtering.

**Parameters:**
- `master_id` (string, required) — Numeric Discogs master-release id (the work, across pressings).
- `format` (string, optional) — Keep only versions in this format. The unfiltered response lists every available value under `facets.format`.
- `label` (string, optional) — Keep only versions on this label.
- `country` (string, optional) — Keep only versions pressed in this country.
- `released` (string, optional) — Keep only versions released in this year.
- `page` (integer, optional, default 1) — Result page, 1-based. Discogs stops at page 100 whatever the total.
- `per_page` (integer, optional, default 50) — Rows per page. Discogs caps this at 100 and silently rewrites anything larger.
- `max_rotations` (integer, optional, default 3) — How many times to start over on a fresh connection after a failed attempt.

**Returns:** versions[]{release_id,title,format,label,catno,country,released,status,have,want,url}, count, total, facets{format,label,country,released}, pagination

### POST /discogs/v1/artist — 1 credit
An artist or group: profile, real name variations, aliases, band members, external links and images.

**Parameters:**
- `artist_id` (string, required) — Numeric Discogs artist id.
- `max_rotations` (integer, optional, default 3) — How many times to start over on a fresh connection after a failed attempt.

**Returns:** artist{artist_id, name, profile, name_variations, aliases, members, groups, urls, images, data_quality, url}

### POST /discogs/v1/artist/releases — 1 credit
An artist's discography — every release and master release they are credited on, sortable by year, title or format.

**Parameters:**
- `artist_id` (string, required) — Numeric Discogs artist id.
- `sort` (enum, optional) — Order the discography by year, title or format. [one of: year, title, format]
- `sort_order` (enum, optional, default "desc") — Ascending or descending. Only applies with `sort`. [one of: asc, desc]
- `page` (integer, optional, default 1) — Result page, 1-based. Discogs stops at page 100 whatever the total.
- `per_page` (integer, optional, default 50) — Rows per page. Discogs caps this at 100 and silently rewrites anything larger.
- `max_rotations` (integer, optional, default 3) — How many times to start over on a fresh connection after a failed attempt.

**Returns:** releases[]{id,type,title,artist_name,role,year,format,label,catno,main_release_id,have,want}, count, total, pagination

### POST /discogs/v1/label — 1 credit
A record label: profile, contact information the label itself publishes, sublabels, external links and images.

**Parameters:**
- `label_id` (string, required) — Numeric Discogs label id.
- `max_rotations` (integer, optional, default 3) — How many times to start over on a fresh connection after a failed attempt.

**Returns:** label{label_id, name, profile, contact_info, sublabels, urls, images, data_quality, url}

### POST /discogs/v1/label/releases — 1 credit
A label's catalogue — every release Discogs files under it, with catalogue numbers.

**Parameters:**
- `label_id` (string, required) — Numeric Discogs label id.
- `page` (integer, optional, default 1) — Result page, 1-based. Discogs stops at page 100 whatever the total.
- `per_page` (integer, optional, default 50) — Rows per page. Discogs caps this at 100 and silently rewrites anything larger.
- `max_rotations` (integer, optional, default 3) — How many times to start over on a fresh connection after a failed attempt.

**Returns:** releases[]{id,type,title,artist_name,year,format,catno,status,thumbnail_url}, count, total, pagination

### POST /discogs/v1/marketplace/stats — 1 credit
Live marketplace figures for up to 20 releases in ONE call: how many copies are for sale and the lowest asking price, converted into the currency you ask for.

**Parameters:**
- `release_ids` (array, required) — Up to 20 numeric release ids. One call replaces up to 20 single calls and costs far less per release.
- `currency` (enum, optional, default "USD") — Currency the lowest asking price is converted into. [one of: USD, GBP, EUR, CAD, AUD, JPY, CHF, MXN, BRL, NZD, SEK, ZAR, DKK, NOK, PLN]
- `max_rotations` (integer, optional, default 3) — How many times to start over on a fresh connection after a failed attempt.

**Returns:** stats[]{release_id,num_for_sale,lowest_price,lowest_price_currency,blocked_from_sale}, count, not_found[]

### POST /discogs/v1/marketplace/listings — 3 credits
Every copy of a release that is actually for sale right now: asking price in the seller's own currency, shipping, media AND sleeve condition, the seller's public handle, feedback score and the country it ships from.

**Parameters:**
- `release_id` (string, required) — Numeric Discogs release id (one specific pressing). A full discogs.com release URL is accepted too.
- `sort` (enum, optional, default "listed,desc") — Order the listings: price,asc · price,desc · condition,desc · condition,asc · seller,asc · seller,desc · listed,desc · listed,asc. [one of: listed,desc, listed,asc, condition,desc, condition,asc, seller,asc, seller,desc, price,asc, price,desc]
- `limit` (integer, optional, default 25) — Listings per page. Discogs offers exactly 25, 50, 100 or 250 and rounds anything else down to the next offered size.
- `page` (integer, optional, default 1) — Result page, 1-based. Discogs stops at page 100 whatever the total.
- `media_condition` (array, optional) — Keep only listings whose MEDIA grade is one of these. Short codes (M, NM, VG+, VG, G+, G, F, P) are accepted. [one of: Near Mint (NM or M-), Very Good Plus (VG+), Very Good (VG), Good Plus (G+), Mint (M), Good (G), Fair (F), Poor (P)]
- `ships_from` (string, optional) — Keep only listings shipping from this country, spelled as Discogs spells it (United Kingdom, Italy, Germany…).
- `price_currency` (enum, optional) — 🔴 A FILTER, not a display setting: keeps only listings the seller priced natively in this currency, which can cut the total sharply. Leave it unset to see every listing. [one of: USD, GBP, EUR, CAD, AUD, JPY, CHF, MXN, BRL, NZD, SEK, ZAR, DKK, NOK, PLN]
- `accepts_offers` (boolean, optional, default false) — Keep only listings whose seller accepts offers.
- `max_rotations` (integer, optional, default 3) — How many times to start over on a fresh connection after a failed attempt.

**Returns:** listings[]{listing_id, release_id, title, label, catno, media_condition, media_condition_code, media_condition_rank, sleeve_condition, sleeve_condition_code, price, currency, shipping, total_converted, total_converted_currency, comments, seller{username,rating_pct,ratings_count,stars,ships_from}, url}, count, total, page, rows_dropped, filters_applied

**Example request body:**
```json
{
  "release_id": 249504,
  "limit": 25
}
```

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