{"openapi":"3.0.3","info":{"title":"Discogs API (ReefAPI)","version":"0.1.0","description":"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. Call POST /discogs/v1/{action} with an x-api-key header; every response is the { ok, data, meta, error } envelope.","contact":{"name":"ReefAPI","url":"https://reefapi.com/discogs-api","email":"support@reefapi.com"},"license":{"name":"ReefAPI Terms","url":"https://reefapi.com/terms"},"termsOfService":"https://reefapi.com/terms"},"externalDocs":{"description":"Discogs API documentation","url":"https://reefapi.com/docs/discogs"},"servers":[{"url":"https://api.reefapi.com"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"discogs","description":"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."}],"paths":{"/discogs/v1/search":{"post":{"operationId":"discogs_search","summary":"Search Discogs for releases, master releases, artists or labels","description":"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.","tags":["discogs"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"nirvana nevermind","description":"Free-text search across artist, title, label and catalogue number. Optional when you supply at least one of the field filters."},"type":{"type":"string","enum":["release","master","artist","label"],"default":"release","example":"release","description":"What kind of record to return: a pressing (release), a master release, an artist or a label."},"artist":{"type":"string","example":"Nirvana","description":"Artist name filter."},"release_title":{"type":"string","example":"Nevermind","description":"Release title filter."},"label":{"type":"string","example":"Sub Pop","description":"Record label name filter."},"catno":{"type":"string","example":"DGC-24425","description":"Catalogue number printed on the release. Discogs matches this loosely, so it narrows rather than pins."},"barcode":{"type":"string","example":"602537351169","description":"Barcode / UPC / EAN as printed on the sleeve."},"format":{"type":"string","example":"Vinyl","description":"Format filter, Discogs' own spelling: Vinyl, CD, Cassette, LP, Album, Box Set, 7\", 12\" and so on."},"country":{"type":"string","example":"UK","description":"Country of release, Discogs' own spelling (UK, US, Japan, Europe)."},"year":{"type":"string","example":"1991","description":"Year of release. A range like 1991-1993 is accepted."},"genre":{"type":"string","example":"Rock","description":"Discogs genre (Rock, Electronic, Jazz, Hip Hop, Classical, Funk / Soul, Pop, Reggae, Latin, Folk, World, & Country)."},"style":{"type":"string","example":"Grunge","description":"Discogs style, narrower than genre."},"track":{"type":"string","example":"Smells Like Teen Spirit","description":"Track title filter."},"credit":{"type":"string","example":"Butch Vig","description":"Credited person filter (producer, engineer, designer…)."},"page":{"type":"integer","minimum":1,"maximum":100,"default":1,"example":1,"description":"Result page, 1-based. Discogs stops at page 100 whatever the total."},"per_page":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50,"description":"Rows per page. Discogs caps this at 100 and silently rewrites anything larger."},"max_rotations":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How many times to start over on a fresh connection after a failed attempt."}}},"example":{"query":"nirvana nevermind","type":"release","per_page":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/discogs/v1/release":{"post":{"operationId":"discogs_release","summary":"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,","description":"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.","tags":["discogs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"release_id":{"type":"string","example":249504,"description":"Numeric Discogs release id (one specific pressing). A full discogs.com release URL is accepted too."},"include_marketplace":{"type":"boolean","default":true,"example":true,"description":"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":{"type":"string","enum":["USD","GBP","EUR","CAD","AUD","JPY","CHF","MXN","BRL","NZD","SEK","ZAR","DKK","NOK","PLN"],"default":"USD","example":"USD","description":"Currency the lowest asking price is converted into."},"max_rotations":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How many times to start over on a fresh connection after a failed attempt."}},"required":["release_id"]},"example":{"release_id":249504}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/discogs/v1/master":{"post":{"operationId":"discogs_master","summary":"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.","description":"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.","tags":["discogs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"master_id":{"type":"string","example":13814,"description":"Numeric Discogs master-release id (the work, across pressings)."},"max_rotations":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How many times to start over on a fresh connection after a failed attempt."}},"required":["master_id"]},"example":{"master_id":13814}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/discogs/v1/master/versions":{"post":{"operationId":"discogs_master_versions","summary":"Every pressing of a master release, with the format / label / country / year facets Discogs itself offers so you can see what exists before filtering.","description":"Every pressing of a master release, with the format / label / country / year facets Discogs itself offers so you can see what exists before filtering.","tags":["discogs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"master_id":{"type":"string","example":13814,"description":"Numeric Discogs master-release id (the work, across pressings)."},"format":{"type":"string","example":"Vinyl","description":"Keep only versions in this format. The unfiltered response lists every available value under `facets.format`."},"label":{"type":"string","example":"Sub Pop","description":"Keep only versions on this label."},"country":{"type":"string","example":"US","description":"Keep only versions pressed in this country."},"released":{"type":"string","example":"1991","description":"Keep only versions released in this year."},"page":{"type":"integer","minimum":1,"maximum":100,"default":1,"example":1,"description":"Result page, 1-based. Discogs stops at page 100 whatever the total."},"per_page":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50,"description":"Rows per page. Discogs caps this at 100 and silently rewrites anything larger."},"max_rotations":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How many times to start over on a fresh connection after a failed attempt."}},"required":["master_id"]},"example":{"master_id":13814}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/discogs/v1/artist":{"post":{"operationId":"discogs_artist","summary":"An artist or group: profile, real name variations, aliases, band members, external links and images.","description":"An artist or group: profile, real name variations, aliases, band members, external links and images.","tags":["discogs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":125246,"description":"Numeric Discogs artist id."},"max_rotations":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How many times to start over on a fresh connection after a failed attempt."}},"required":["artist_id"]},"example":{"artist_id":125246}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/discogs/v1/artist/releases":{"post":{"operationId":"discogs_artist_releases","summary":"An artist's discography — every release and master release they are credited on, sortable by year, title or format.","description":"An artist's discography — every release and master release they are credited on, sortable by year, title or format.","tags":["discogs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":125246,"description":"Numeric Discogs artist id."},"sort":{"type":"string","enum":["year","title","format"],"example":"year","description":"Order the discography by year, title or format."},"sort_order":{"type":"string","enum":["asc","desc"],"default":"desc","example":"desc","description":"Ascending or descending. Only applies with `sort`."},"page":{"type":"integer","minimum":1,"maximum":100,"default":1,"example":1,"description":"Result page, 1-based. Discogs stops at page 100 whatever the total."},"per_page":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50,"description":"Rows per page. Discogs caps this at 100 and silently rewrites anything larger."},"max_rotations":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How many times to start over on a fresh connection after a failed attempt."}},"required":["artist_id"]},"example":{"artist_id":125246}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/discogs/v1/label":{"post":{"operationId":"discogs_label","summary":"A record label: profile, contact information the label itself publishes, sublabels, external links and images.","description":"A record label: profile, contact information the label itself publishes, sublabels, external links and images.","tags":["discogs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label_id":{"type":"string","example":1,"description":"Numeric Discogs label id."},"max_rotations":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How many times to start over on a fresh connection after a failed attempt."}},"required":["label_id"]},"example":{"label_id":1}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/discogs/v1/label/releases":{"post":{"operationId":"discogs_label_releases","summary":"A label's catalogue — every release Discogs files under it, with catalogue numbers.","description":"A label's catalogue — every release Discogs files under it, with catalogue numbers.","tags":["discogs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label_id":{"type":"string","example":1,"description":"Numeric Discogs label id."},"page":{"type":"integer","minimum":1,"maximum":100,"default":1,"example":1,"description":"Result page, 1-based. Discogs stops at page 100 whatever the total."},"per_page":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50,"description":"Rows per page. Discogs caps this at 100 and silently rewrites anything larger."},"max_rotations":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How many times to start over on a fresh connection after a failed attempt."}},"required":["label_id"]},"example":{"label_id":1}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/discogs/v1/marketplace/stats":{"post":{"operationId":"discogs_marketplace_stats","summary":"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.","description":"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.","tags":["discogs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"release_ids":{"type":"array","items":{"type":"string"},"example":[249504,1122001,8434],"description":"Up to 20 numeric release ids. One call replaces up to 20 single calls and costs far less per release."},"currency":{"type":"string","enum":["USD","GBP","EUR","CAD","AUD","JPY","CHF","MXN","BRL","NZD","SEK","ZAR","DKK","NOK","PLN"],"default":"USD","example":"USD","description":"Currency the lowest asking price is converted into."},"max_rotations":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How many times to start over on a fresh connection after a failed attempt."}},"required":["release_ids"]},"example":{"release_ids":[249504,1122001,8434]}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/discogs/v1/marketplace/listings":{"post":{"operationId":"discogs_marketplace_listings","summary":"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","description":"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.","tags":["discogs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"release_id":{"type":"string","example":249504,"description":"Numeric Discogs release id (one specific pressing). A full discogs.com release URL is accepted too."},"sort":{"type":"string","enum":["listed,desc","listed,asc","condition,desc","condition,asc","seller,asc","seller,desc","price,asc","price,desc"],"default":"listed,desc","example":"price,asc","description":"Order the listings: price,asc · price,desc · condition,desc · condition,asc · seller,asc · seller,desc · listed,desc · listed,asc."},"limit":{"type":"integer","minimum":25,"maximum":250,"default":25,"example":25,"description":"Listings per page. Discogs offers exactly 25, 50, 100 or 250 and rounds anything else down to the next offered size."},"page":{"type":"integer","minimum":1,"maximum":100,"default":1,"example":1,"description":"Result page, 1-based. Discogs stops at page 100 whatever the total."},"media_condition":{"type":"array","items":{"type":"string","enum":["Near Mint (NM or M-)","Very Good Plus (VG+)","Very Good (VG)","Good Plus (G+)","Mint (M)","Good (G)","Fair (F)","Poor (P)"]},"example":["VG+"],"description":"Keep only listings whose MEDIA grade is one of these. Short codes (M, NM, VG+, VG, G+, G, F, P) are accepted."},"ships_from":{"type":"string","example":"United Kingdom","description":"Keep only listings shipping from this country, spelled as Discogs spells it (United Kingdom, Italy, Germany…)."},"price_currency":{"type":"string","enum":["USD","GBP","EUR","CAD","AUD","JPY","CHF","MXN","BRL","NZD","SEK","ZAR","DKK","NOK","PLN"],"example":"USD","description":"🔴 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."},"accepts_offers":{"type":"boolean","default":false,"example":false,"description":"Keep only listings whose seller accepts offers."},"max_rotations":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How many times to start over on a fresh connection after a failed attempt."}},"required":["release_id"]},"example":{"release_id":249504,"limit":25}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":3}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Envelope":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"data":{"description":"Action result (shape varies per action)"},"meta":{"type":"object","description":"api, endpoint, mode, latency_ms, record_count, completeness_pct"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}