{"openapi":"3.1.0","info":{"title":"Discogs (BYOK) API","version":"0.1.0","description":"Discogs (BYOK) lets an AI assistant read your own Discogs data through the Discogs API with a key you supply (personal access token). Read-only: 9 tools (search_database, get_release, get_release_stats, get_master, list_master_versions, get_artist, list_artist_releases, get_label, list_label_releases). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-discogs.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-discogs/docs"},"termsOfService":"https://connectorbay.com/byok-discogs/terms"},"servers":[{"url":"https://byok-discogs.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-discogs/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_database":{"post":{"operationId":"search_database","summary":"Search the Discogs database of releases, masters, artists and labels by free text or by fields such as artist, title, la","description":"Search the Discogs database of releases, masters, artists and labels by free text or by fields such as artist, title, label, year, genre and barcode. Returns id, type, title, year, country, formats, labels and community have/want counts. Use for \"Find the Discogs release of Kind of Blue by Miles Davis\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search, for example 'Nirvana Nevermind'.","title":"Q"},"type":{"anyOf":[{"enum":["release","master","artist","label"],"type":"string"},{"type":"null"}],"default":null,"description":"Limit to one kind of result: release, master, artist or label.","title":"Type"},"artist":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Artist name to match.","title":"Artist"},"release_title":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Release title to match.","title":"Release Title"},"title":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Combined 'artist - title' text to match.","title":"Title"},"label":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Label name to match.","title":"Label"},"genre":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Genre to match, for example 'Jazz'.","title":"Genre"},"style":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Style to match, for example 'Hard Bop'.","title":"Style"},"country":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Country of release, for example 'US'.","title":"Country"},"year":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Year of release, for example '1959'.","title":"Year"},"format":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Format to match, for example 'Vinyl' or 'CD'.","title":"Format"},"catno":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Catalogue number to match.","title":"Catno"},"barcode":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Barcode to match.","title":"Barcode"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100, Discogs default 50).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"search_databaseArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_release":{"post":{"operationId":"get_release","summary":"Get one Discogs release: title, artists, labels and catalogue numbers, formats, genres, styles, track list, community ra","description":"Get one Discogs release: title, artists, labels and catalogue numbers, formats, genres, styles, track list, community rating, copies for sale and lowest price. Use for \"Show the track list of Discogs release 249504\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"release_id":{"description":"Numeric Discogs release id (the id of a search result of type release).","minimum":1,"title":"Release Id","type":"integer"},"curr_abbr":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":null,"description":"Currency code for marketplace prices, for example USD, EUR or GBP; defaults to your account's currency.","title":"Curr Abbr"}},"required":["release_id"],"title":"get_releaseArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_release_stats":{"post":{"operationId":"get_release_stats","summary":"Get how many Discogs users have and want a release. Use for \"How many Discogs users own release 249504\".","description":"Get how many Discogs users have and want a release. Use for \"How many Discogs users own release 249504\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"release_id":{"description":"Numeric Discogs release id.","minimum":1,"title":"Release Id","type":"integer"}},"required":["release_id"],"title":"get_release_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_master":{"post":{"operationId":"get_master","summary":"Get a Discogs master release (the canonical album across all its pressings): title, year, artists, genres, styles, track","description":"Get a Discogs master release (the canonical album across all its pressings): title, year, artists, genres, styles, track list, main release id and copies for sale. Use for \"What is the main release of Discogs master 1000\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"master_id":{"description":"Numeric Discogs master id (the id of a search result of type master).","minimum":1,"title":"Master Id","type":"integer"}},"required":["master_id"],"title":"get_masterArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_master_versions":{"post":{"operationId":"list_master_versions","summary":"List the pressings and versions of a Discogs master release with label, catalogue number, format, country, release year ","description":"List the pressings and versions of a Discogs master release with label, catalogue number, format, country, release year and how many users own or want each. Use for \"Which pressings of Discogs master 1000 were released on vinyl\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"master_id":{"description":"Numeric Discogs master id.","minimum":1,"title":"Master Id","type":"integer"},"format":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only this format, for example 'Vinyl' or 'CD'.","title":"Format"},"label":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this label.","title":"Label"},"country":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only this country of release.","title":"Country"},"released":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only this release year.","title":"Released"},"sort":{"anyOf":[{"enum":["released","title","format","label","catno","country"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by: released, title, format, label, catno or country.","title":"Sort"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Sort Order"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100, Discogs default 50).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["master_id"],"title":"list_master_versionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_artist":{"post":{"operationId":"get_artist","summary":"Get a Discogs artist: profile text, name variations, links, band members and the link to their releases. Use for \"Who ar","description":"Get a Discogs artist: profile text, name variations, links, band members and the link to their releases. Use for \"Who are the members of the Discogs artist 108713\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"artist_id":{"description":"Numeric Discogs artist id (the id of a search result of type artist).","minimum":1,"title":"Artist Id","type":"integer"}},"required":["artist_id"],"title":"get_artistArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_artist_releases":{"post":{"operationId":"list_artist_releases","summary":"List an artist's releases and masters on Discogs with role, year, format and label, sortable by year, title or format. U","description":"List an artist's releases and masters on Discogs with role, year, format and label, sortable by year, title or format. Use for \"List the Discogs releases of artist 108713 by year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"artist_id":{"description":"Numeric Discogs artist id.","minimum":1,"title":"Artist Id","type":"integer"},"sort":{"anyOf":[{"enum":["year","title","format"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by: year, title or format.","title":"Sort"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Sort Order"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100, Discogs default 50).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["artist_id"],"title":"list_artist_releasesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_label":{"post":{"operationId":"get_label","summary":"Get a Discogs record label: profile text, contact info, links and sub-labels. Use for \"Tell me about the record label Pl","description":"Get a Discogs record label: profile text, contact info, links and sub-labels. Use for \"Tell me about the record label Planet E on Discogs (label 1)\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"label_id":{"description":"Numeric Discogs label id (the id of a search result of type label).","minimum":1,"title":"Label Id","type":"integer"}},"required":["label_id"],"title":"get_labelArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_label_releases":{"post":{"operationId":"list_label_releases","summary":"List the releases of a Discogs label with artist, catalogue number, format and year. Use for \"What has the Discogs label","description":"List the releases of a Discogs label with artist, catalogue number, format and year. Use for \"What has the Discogs label 1 released\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"label_id":{"description":"Numeric Discogs label id.","minimum":1,"title":"Label Id","type":"integer"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100, Discogs default 50).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["label_id"],"title":"list_label_releasesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}