2025-10-09 23:51:39 +00:00
## ===----------------------------------------------------------------------===
##
## This source file is part of the Discogs Service open source project
##
## Copyright (c) 2025 Röck+Cöde VoF. and the Discogs Service project authors
## Licensed under Apache license v2.0
##
## See LICENSE for license information
## See CONTRIBUTORS for the list of Discogs Service project authors
##
## SPDX-License-Identifier: Apache-2.0
##
## ===----------------------------------------------------------------------===
openapi : 3.1 .1
info :
title : Discogs API
version : v2.0
summary : The Discogs RESTFul API.
description : |
# Overview
The Discogs API v2.0 is a RESTful interface to Discogs data. You can access JSON-formatted information about Database objects such as _Artists_, _Releases_, and _Labels_. Your application can also manage _User Collections_ and _Wantlists_, create _Marketplace_ listings, and more.
Some Discogs data is made available under the [CC0 No Rights Reserved](https://creativecommons.org/public-domain/cc0/) license, and some is restricted data, as defined in our [API Terms of Use](https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use).
Our monthly data dumps are available under the the [CC0 No Rights Reserved](https://creativecommons.org/public-domain/cc0/) license.
If you utilize the Discogs API, you are subject to the [API Terms of Use](https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use). Please also ensure that any application you develop follows the Discogs [Application Name and Description Policy](https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use)
# Quickstart
If you just want to see some results right now, issue this _curl_ command:
```bash
curl https://api.discogs.com/releases/249504 --user-agent "FooBarApp/3.0"
```
# General information
General Information
**Your application must provide a User-Agent string that identifies itself** - preferably something that follows [RFC 1945](https://datatracker.ietf.org/doc/html/rfc1945#section-3.7). Some good examples include:
```
AwesomeDiscogsBrowser/0.1 +http://adb.example.com
LibraryMetadataEnhancer/0.3 +http://example.com/lime
MyDiscogsClient/1.0 +http://mydiscogsclient.org
```
Please don’
Here are some bad examples that are unclear or obscure the nature of the application:
```
curl/7.9.8 (i686-pc-linux-gnu) libcurl 7.9.8 (OpenSSL 0.9.6b)
Mozilla/5.0 (X11; Linux i686; rv:6.0.2) Gecko/20100101 Firefox/6.0.2
my app
```
# Authentication
Most endpoints require authentication. The API supports multiple methods:
1. **Discogs Auth (Key & Secret):** For read-only access to public data with a higher rate limit.
2. **Discogs Auth (Personal Access Token):** For full access to your own user account data.
3. **OAuth 1.0a:** For building third-party applications that act on behalf of other Discogs users.
# Rate Limiting
**Requests are throttled by the server by source IP to 60 per minute for authenticated requests, and 25 per minute for unauthenticated requests, with some exceptions.**
Your application should identify itself to our servers via a unique user agent string in order to achieve the maximum number of requests per minute.
Our rate limiting tracks your requests using a moving average over a 60 second window. If no requests are made in 60 seconds, your window will reset.
We attach the following headers to responses to help you track your rate limit use:
* `X-Discogs-Ratelimit`: The total number of requests that can make in a one minute window.
* `X-Discogs-Ratelimit-Used` : The number of requests made in an existing rate limit window.
* `X-Discogs-Ratelimit-Remaining`: The number of remaining requests to make in an existing rate limit window.
Your application should take our global limit into account and throttle its requests locally.
In the future, we may update these rate limits at any time in order to provide service for all users.
# Pagination
Some resources represent collections of objects and may be paginated. By default, 50 items per page are shown.
To browse different pages, or change the number of items per page (up to 100), use the page and per_page query string parameters:
```
GET https://api.discogs.com/artists/1/releases?page=2&per_page=75
```
Responses include a `Link` header:
```
Link: <https://api.discogs.com/artists/1/releases?page=3&per_page=75>; rel=next,
<https://api.discogs.com/artists/1/releases?page=1&per_page=75>; rel=first,
<https://api.discogs.com/artists/1/releases?page=30&per_page=75>; rel=last,
<https://api.discogs.com/artists/1/releases?page=1&per_page=75>; rel=prev
```
And a pagination object in the response body:
```json
{
"pagination": {
"page": 2,
"pages": 30,
"items": 2255,
"per_page": 75,
"urls":
{
"first": "https://api.discogs.com/artists/1/releases?page=1&per_page=75",
"prev": "https://api.discogs.com/artists/1/releases?page=1&per_page=75",
"next": "https://api.discogs.com/artists/1/releases?page=3&per_page=75",
last": "https://api.discogs.com/artists/1/releases?page=30&per_page=75"
}
},
"releases":
[ ... ]
}
}
```
# Versioning and Media Types
Currently, the API only supports one version: `v2`. However, you can specify a version in your requests to future-proof your application. By adding an `Accept` header with the version and media type, you can guarantee your requests will receive data from the correct version you develop your app on.
A standard `Accept` header may look like this:
```
application/vnd.discogs.v2.html+json
```
If case of requesting information from an endpoint that may have text formatting in it, it is possible to choose which kind of formatting to be returned by changing that section of the `Accept` header. We currently support 3 types:
* `application/vnd.discogs.v2.html+json`
* `application/vnd.discogs.v2.plaintext+json`
* `application/vnd.discogs.v2.discogs+json`
If no `Accept` header is supplied, or if the Accept header differs from one of the three previous options, we default to `application/vnd.discogs.v2.discogs+json`.
# Videos
In case an application integrates **YouTube** videos, then third party cookies may be used. Please refer to the [YouTube and Google's cookie policy](https://policies.google.com/technologies/cookies).
# FAQ
**1) Why am I getting an empty response from the server?**
This generally happens when no `User-Agent` header is added to the requests.
**2) How do I get updates about the API?**
Subscribe to the [API Announcements forum thread](https://www.discogs.com/forum/thread/521520689469733cfcfd2089). For larger, breaking changes, an email notice to all developers with a registered Discogs application will be sent.
**3) Where can I register a Discogs application?**
A Discogs application can be registered on the [Developer Settings](https://www.discogs.com/settings/developers).
**4) If I have a question/issue with the API, should I file a Support Request?**
It's generally best to start out with a forum post on the [API topic](https://www.discogs.com/forum/topic/1082) since other developers may have had similar issues and they can point in the right direction. If the issue requires privacy, then a support request is the best way to go.
**5) I'm getting a 404 response when trying to fetch images; what gives?**
This may seem obvious, but make sure the URL has not been changed. The URLs returned are signed URLs, so trying to change one part of the URL (e.g., _Release ID_ number) will generally not work.
**6) What are the authentication requirements for requesting images?**
Please see the [Images documentation page](https://www.discogs.com/developers/#page:images).
**7) Why am I getting a particular HTTP response?**
**200 OK**
The request was successful, and the requested data is provided in the response body.
**201 Continue**
POST request is sent to a list of resources to create a new one. The ID of the newly-created resource will be provided in the body of the response.
**204 No Content**
The request was successful, and the server has no additional information to convey, so the response body is empty.
**401 Unauthorized**
A resource that first requires [authentication](https://www.discogs.com/developers/#page:authentication) is being accessed. See Authenticating with OAuth.
**403 Forbidden**
The access to a resource is not allowed, even if authenticated. Trying to modify another user's profile, for example, will produce this error.
**404 Not Found**
The requested resource does not exist.
**405 Method Not Allowed**
A HTTP verb is not supported by the resource. Trying to `PUT` to `/artists/1`, for example, will fail because `Artists` are read-only.
**422 Unprocessable Entity**
Even though the request is well-formed, there is something semantically wrong with the body of the request. This can be due to malformed JSON, a missing parameter or the wrong type, or trying to perform an action that doesn not make any sense. Check the response body for specific information about what went wrong.
**500 Internal Server Error**
Something went wrong on the service while attempting to process the request. The message field of the response body will contain an error code that can be sent to Discogs Support (which will help on tracking down your specific issue).
termsOfService : https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use
contact :
name : Discogs API Support
url : https://www.discogs.com/forum/topic/1082
email : api@discogs.com
license :
name : API Terms of Use
url : https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use
externalDocs :
description : Discogs Developers Portal
url : https://www.discogs.com/developers
servers :
- url : https://api.discogs.com/
description : Live Server
tags :
- name : Service
2025-10-13 17:55:48 +00:00
description : Access data on the service.
- name : Authentication
description : Access data on authenticating to the service.
2025-10-09 23:51:39 +00:00
- name : Database
description : Access data on artists, labels, and releases.
- name : Marketplace
description : Interact with the marketplace, including listings, orders, and fees.
- name : User Identity
description : Manage and retrieve user profile information, submissions, and contributions.
- name : User Collection
description : Manage a user's record collection.
- name : User Wantlist
description : Manage a user's wantlist.
- name : User Lists
description : Manage user-created lists.
- name : Inventory Management
description : Bulk inventory management via CSV uploads and exports.
paths :
/ :
get :
summary : Get information about the service.
description : Retrieves any available information related to the service.
operationId : getService
tags :
- Service
responses :
'200' :
description : Service information returned successfully.
2025-10-13 13:09:10 +00:00
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
$ref : '#/components/schemas/Service'
'500' :
$ref : '#/components/responses/Unavailable'
2025-10-13 17:55:48 +00:00
/oauth/request_token :
get :
tags :
- Authentication
summary : Get details about a OAuth request token.
description : |
Retrieve a request token to initialize an *OAuth* authentication process.
This endpoint represents the [2nd step of the OAuth flow process](https://www.discogs.com/developers#header-2.-send-a-get-request-to-the-discogs-request-token-url), thus it requires to configure an *Authorization* header to have a value like this:
```
OAuth oauth_consumer_key="your_consumer_key", oauth_nonce="random_string_or_timestamp", oauth_signature="your_consumer_secret&", oauth_signature_method="PLAINTEXT", oauth_timestamp="current_timestamp", oauth_callback="your_callback"
```
For further details about this process, please refer to the [OAuth flow](https://www.discogs.com/developers#page:authentication,header:authentication-oauth-flow) section in the [Discogs API authentication](https://www.discogs.com/developers#page:authentication) documentation.
operationId : getRequestToken
parameters :
- $ref : '#/components/parameters/ContentType'
- $ref : '#/components/parameters/Authorization'
- $ref : '#/components/parameters/UserAgent'
responses :
'200' :
description : |
Successfully retrieved request token details.
With this request token, then it is possible to continue with the [next step in the OAuth flow](https://www.discogs.com/developers#header-3.-redirect-your-user-to-the-discogs-authorize-page) process.
headers :
oauth_token :
$ref : '#/components/headers/OAuthToken'
oauth_token_secret :
$ref : '#/components/headers/OAuthSecret'
oauth_callback-confirmed :
$ref : '#/components/headers/OAuthCallback'
'500' :
$ref : '#/components/responses/InternalError'
/oauth/access_token :
post :
tags :
- Authentication
summary : Provide required credentials data to obtain an access token.
description : |
Provide to the service some required credentials details to obtain an access token at the end of the *OAuth* process.
This endpoint represents the [4th step of the OAuth flow process](https://www.discogs.com/developers#header-4.-send-a-post-request-to-the-discogs-access-token-url), thus it requires to configure an *Authorization* header to have a value like this:
```
OAuth oauth_consumer_key="your_consumer_key", oauth_nonce="random_string_or_timestamp", oauth_token="oauth_token_received_from_step_2" oauth_signature="your_consumer_secret&", oauth_signature_method="PLAINTEXT", oauth_timestamp="current_timestamp", oauth_verifier="users_verifier"
```
For further details about this process, please refer to the [OAuth flow](https://www.discogs.com/developers#page:authentication,header:authentication-oauth-flow) section in the [Discogs API authentication](https://www.discogs.com/developers#page:authentication) documentation.
operationId : postAccessToken
parameters :
- $ref : '#/components/parameters/ContentType'
- $ref : '#/components/parameters/Authorization'
- $ref : '#/components/parameters/UserAgent'
responses :
'200' :
description : Successfully retrieved an access token at the end of the OAuth authentication process.
headers :
oauth_token :
$ref : '#/components/headers/OAuthToken'
oauth_token_secret :
$ref : '#/components/headers/OAuthSecret'
'500' :
$ref : '#/components/responses/InternalError'
/oauth/identity :
get :
tags :
- Authentication
summary : Get information about an authenticated user.
description : |
Retrieve basic information about the authenticated user.
This endpoint represents the (optional) [5th step of the OAuth flow process](https://www.discogs.com/developers#header-5-send-authenticated-requests-to-discogs-endpoints), as it is advised to perform a sanity check to ensure the *OAuth* process finished successfully.
For further details about this process, please refer to the [OAuth flow](https://www.discogs.com/developers#page:authentication,header:authentication-oauth-flow) section in the [Discogs API authentication](https://www.discogs.com/developers#page:authentication) documentation.
operationId : getUserIdentity
2025-10-13 18:41:24 +00:00
security :
2025-10-15 21:59:32 +00:00
- UserToken : [ ]
- ConsumerKeySecret : [ ]
2025-10-13 18:41:24 +00:00
- OAuth : [ ]
2025-10-13 17:55:48 +00:00
responses :
'200' :
description : Successfully retrieved information about an authenticated user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
$ref : '#/components/schemas/UserIdentity'
'401' :
$ref : '#/components/responses/Unauthorized'
2025-10-13 18:41:24 +00:00
/database/search :
get :
tags :
- Database
summary : Search any information from the database.
description : |
Issue a search query to the Discogs database.
This endpoint supports pagination and also, it requires authentication.
operationId : searchDatabase
parameters :
- name : query
description : A query to search for.
in : query
schema :
type : string
- name : type
description : A type of resource to search for.
in : query
schema :
type : string
enum :
- release
- master
- artist
- label
- name : title
description : |
A title to search for.
This parameter can be combined with the `name` query parameter.
in : query
schema :
type : string
- name : release_title
description : A release title to search for.
in : query
schema :
type : string
- name : credit
in : query
description : Some credits to search for.
schema :
type : string
- name : artist
description : An artist name to search for.
in : query
schema :
type : string
- name : anv
description : A ANV (Artist Name Variation) to search for.
in : query
schema :
type : string
- name : label
description : A label name to search for.
in : query
schema :
type : string
- name : genre
description : A music genre to search for.
in : query
schema :
type : string
- name : style
description : A musical style to search for.
in : query
schema :
type : string
- name : country
description : A country to search for.
in : query
schema :
type : string
- name : year
description : A release year to search for.
in : query
schema :
type : string
- name : format
description : A release format to search for.
in : query
schema :
type : string
- name : catno
description : A catalogg number to search for.
in : query
schema :
type : string
- name : barcode
description : A barcode number to search for.
in : query
schema :
type : string
- name : track
description : A track title to search for.
in : query
schema :
type : string
- name : submitter
description : A username of a submitter to search for.
in : query
schema :
type : string
- name : contributor
description : A username of a contributor to search for.
in : query
schema :
type : string
- $ref : '#/components/parameters/Page'
- $ref : '#/components/parameters/PerPage'
security :
2025-10-15 21:59:32 +00:00
- UserToken : [ ]
- ConsumerKeySecret : [ ]
2025-10-13 18:41:24 +00:00
- OAuth : [ ]
responses :
'200' :
description : Successfully retrieved search results.
headers :
Link :
$ref : '#/components/headers/Link'
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
type : object
properties :
pagination :
$ref : '#/components/schemas/Pagination'
results :
description : A list of artist, label, master and/or release search results.
type : array
items :
oneOf :
- $ref : '#/components/schemas/ReleaseResult'
- $ref : '#/components/schemas/MasterResult'
- $ref : '#/components/schemas/ArtistResult'
- $ref : '#/components/schemas/LabelResult'
2025-10-15 21:59:32 +00:00
required :
- pagination
- results
2025-10-13 18:41:24 +00:00
'401' :
$ref : '#/components/responses/Unauthorized'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-09 23:51:39 +00:00
/artists/{artist_id}:
get :
tags :
- Database
2025-10-13 17:55:48 +00:00
summary : Get information about an artist.
description : Retrieves any available information for a specific artist.
operationId : getArtist
2025-10-09 23:51:39 +00:00
parameters :
- $ref : '#/components/parameters/ArtistId'
responses :
'200' :
description : Successfully retrieved artist details.
2025-10-13 13:09:10 +00:00
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
$ref : '#/components/schemas/Artist'
'404' :
$ref : '#/components/responses/NotFound'
/artists/{artist_id}/releases:
get :
tags :
- Database
summary : Get information about releases of an artist.
description : |
Returns a list of releases and masters associated with an artist.
This endpoint supports pagination.
operationId : getArtistReleases
parameters :
- $ref : '#/components/parameters/ArtistId'
- $ref : '#/components/parameters/ArtistReleasesSort'
- $ref : '#/components/parameters/SortOrder'
- $ref : '#/components/parameters/Page'
- $ref : '#/components/parameters/PerPage'
responses :
'200' :
description : A paginated list of releases of an artist.
headers :
Link :
$ref : '#/components/headers/Link'
2025-10-13 13:09:10 +00:00
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
type : object
properties :
pagination :
$ref : '#/components/schemas/Pagination'
releases :
type : array
items :
$ref : '#/components/schemas/ArtistRelease'
2025-10-15 21:59:32 +00:00
required :
- pagination
- releases
2025-10-09 23:51:39 +00:00
'404' :
$ref : '#/components/responses/NotFound'
/labels/{label_id}:
get :
tags :
- Database
summary : Get information about a label
description : Retrieves any available information for a specific label.
operationId : getLabel
parameters :
- $ref : '#/components/parameters/LabelId'
responses :
'200' :
description : Successfully retrieved label details.
2025-10-13 13:09:10 +00:00
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
$ref : '#/components/schemas/Label'
'404' :
$ref : '#/components/responses/NotFound'
/labels/{label_id}/releases:
get :
tags :
- Database
summary : Get information about the releases of a label.
description : |
Returns a list of releases associated with a label.
This endpoint Supports pagination.
operationId : getLabelReleases
parameters :
- $ref : '#/components/parameters/LabelId'
- $ref : '#/components/parameters/Page'
- $ref : '#/components/parameters/PerPage'
responses :
'200' :
description : A paginated list of the label's releases.
2025-10-13 13:09:10 +00:00
headers :
Link :
$ref : '#/components/headers/Link'
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
type : object
properties :
pagination :
$ref : '#/components/schemas/Pagination'
releases :
type : array
items :
$ref : '#/components/schemas/LabelRelease'
2025-10-15 21:59:32 +00:00
required :
- pagination
- releases
2025-10-09 23:51:39 +00:00
'404' :
$ref : '#/components/responses/NotFound'
/masters/{master_id}:
get :
tags :
- Database
summary : Get information about a master release.
description : |
Retrieves any available information for a specific master release.
A master release represents a set of similar releases.
operationId : getMaster
parameters :
- $ref : '#/components/parameters/MasterId'
responses :
'200' :
description : Successfully retrieved master release details.
2025-10-13 13:09:10 +00:00
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
$ref : '#/components/schemas/Master'
'404' :
$ref : '#/components/responses/NotFound'
/masters/{master_id}/versions:
get :
tags :
- Database
summary : Get information about the versions of a master release.
description : |
Retrieves a list of all releases that are versions of the specified master release.
This request supports pagination.
operationId : getMasterVersions
parameters :
- $ref : '#/components/parameters/MasterId'
- $ref : '#/components/parameters/Format'
- $ref : '#/components/parameters/Label'
- $ref : '#/components/parameters/Released'
- $ref : '#/components/parameters/Country'
- $ref : '#/components/parameters/MasterVersionsSort'
- $ref : '#/components/parameters/SortOrder'
- $ref : '#/components/parameters/Page'
- $ref : '#/components/parameters/PerPage'
responses :
'200' :
description : A paginated list of releases belonging to the master.
headers :
Link :
$ref : '#/components/headers/Link'
2025-10-13 13:09:10 +00:00
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
type : object
properties :
pagination :
$ref : '#/components/schemas/Pagination'
versions :
type : array
items :
$ref : '#/components/schemas/ReleaseVersion'
2025-10-15 21:59:32 +00:00
required :
- pagination
- versions
2025-10-09 23:51:39 +00:00
'404' :
$ref : '#/components/responses/NotFound'
/releases/{release_id}:
get :
tags :
- Database
summary : Get information about a release
description : Retrieves details for a specific release.
operationId : getRelease
parameters :
- $ref : '#/components/parameters/ReleaseId'
- $ref : '#/components/parameters/Currency'
responses :
'200' :
description : Successfully retrieved release details.
2025-10-13 13:09:10 +00:00
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
$ref : '#/components/schemas/Release'
'404' :
$ref : '#/components/responses/NotFound'
/releases/{release_id}/rating:
get :
tags :
- Database
summary : Get information about a rating of release.
description : Retrieves the average rating and the total number of user ratings for a given release.
operationId : getReleaseRating
parameters :
- $ref : '#/components/parameters/ReleaseId'
responses :
'200' :
description : Successfully retrieved release rating details.
2025-10-13 13:09:10 +00:00
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
$ref : '#/components/schemas/ReleaseRating'
'404' :
$ref : '#/components/responses/NotFound'
/releases/{release_id}/rating/{username}:
get :
tags :
- Database
summary : Get information about a rating of release by a user.
description : Retrieves the rating for a given release by a specific user.
operationId : getReleaseRatingByUser
parameters :
- $ref : '#/components/parameters/ReleaseId'
- $ref : '#/components/parameters/Username'
responses :
'200' :
description : Successfully retrieved release rating details by a given user.
2025-10-13 13:09:10 +00:00
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
$ref : '#/components/schemas/ReleaseRatingByUser'
'404' :
$ref : '#/components/responses/NotFound'
2025-10-13 15:20:20 +00:00
put :
tags :
- Database
summary : Update information about a rating of release by a user.
description : |
Updates a rating of a release for a given user.
This endpoint requires authentication.
operationId : putReleaseRatingByUser
parameters :
- $ref : '#/components/parameters/ReleaseId'
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/Rating'
security :
2025-10-15 21:59:32 +00:00
- UserToken : [ ]
- ConsumerKeySecret : [ ]
2025-10-13 15:20:20 +00:00
- OAuth : [ ]
responses :
'200' :
description : Successfully updated a rating for a specific release by a given user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
$ref : '#/components/schemas/ReleaseRatingByUser'
'401' :
$ref : '#/components/responses/Unauthorized'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-13 18:41:24 +00:00
delete :
tags :
- Database
summary : Delete information about a rating of release by a user.
description : |
Updates a rating of a release for a given user.
This endpoint requires authentication.
operationId : deleteReleaseRatingByUser
parameters :
- $ref : '#/components/parameters/ReleaseId'
- $ref : '#/components/parameters/Username'
security :
2025-10-15 21:59:32 +00:00
- UserToken : [ ]
- ConsumerKeySecret : [ ]
2025-10-13 18:41:24 +00:00
- OAuth : [ ]
responses :
'200' :
description : Successfully deleted a rating for a specific release by a given user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
'401' :
$ref : '#/components/responses/Unauthorized'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-09 23:51:39 +00:00
/releases/{release_id}/stats:
get :
tags :
- Database
summary : Get information about statistics of release.
description : Retrieves the total number of “haves” (in the community's collections) and “wants” (in the community's wantlists) for a given release.
operationId : getReleaseStats
parameters :
- $ref : '#/components/parameters/ReleaseId'
responses :
'200' :
description : |
Successfully retrieved release rating details by a given user.
> warning: There is a discrepancy about this response between was is documented and what the endpoints actually responds. In the [documentation](https://www.discogs.com/developers#page:database,header:database-release-stats), it is defined that a type containing a statistical data would be returned but the actual response returns an object that contains a boolean flag instead.
2025-10-13 13:09:10 +00:00
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
oneOf :
- $ref : '#/components/schemas/ReleaseStats'
- type : object
properties :
is_offensive :
type : boolean
required :
- is_offensive
'404' :
2025-10-13 15:20:20 +00:00
$ref : '#/components/responses/NotFound'
2025-10-15 21:59:32 +00:00
/users/{username}:
get :
tags :
- User Identity
summary : Get information about a user.
description : |
Retrieves a user profile by username.
In case of being authenticated as the requested user, the `email` property will be visible, and the `num_list` count will also include a user's private lists.
In case of being authenticated as the requested user, or a user's collection or wantlist is public, the `num_collection` and the `num_wantlist` properties will also be visible.
operationId : getUserProfile
parameters :
- $ref : '#/components/parameters/Username'
responses :
'200' :
description : Successfully retrieved profile user information by a given username.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
$ref : '#/components/schemas/UserProfile'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
post :
tags :
- User Identity
summary : Update information about a user.
description : |
Edits some user profile information by username.
This endpoint requires authentication.
operationId : postUserProfile
parameters :
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/Name'
- $ref : '#/components/parameters/HomePage'
- $ref : '#/components/parameters/Location'
- $ref : '#/components/parameters/Profile'
- $ref : '#/components/parameters/Currency'
security :
- UserToken : [ ]
- ConsumerKeySecret : [ ]
- OAuth : [ ]
responses :
'200' :
description : Successfully retrieved an updated profile user information by a given username.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
$ref : '#/components/schemas/UserProfile'
'403' :
$ref : '#/components/responses/NotAccessable'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
/users/{username}/contributions:
get :
tags :
- User Identity
summary : Get contributions of a user.
description : |
Retrieves all the contributions or additions to releases, labels, and artist done by username.
This endpoints accepts pagination headers.
operationId : getUserContributions
parameters :
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/SortField'
- $ref : '#/components/parameters/SortOrder'
responses :
'200' :
description : Successfully retrieved items contributed by a user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
type : object
properties :
pagination :
$ref : '#/components/schemas/Pagination'
submissions :
description : A type that represents all items submitted by a user.
$ref : '#/components/schemas/UserItems'
required :
- pagination
- contributions
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
/users/{username}/submissions:
get :
tags :
- User Identity
summary : Get submissions of a user.
description : |
Retrieves all the submissions or edits to releases, labels, and artist done by username.
This endpoints accepts pagination headers.
operationId : getUserSubmissions
parameters :
- $ref : '#/components/parameters/Username'
responses :
'200' :
description : Successfully retrieved items submitted by a user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
type : object
properties :
pagination :
$ref : '#/components/schemas/Pagination'
submissions :
description : A type that represents all items edited by a user.
$ref : '#/components/schemas/UserItems'
required :
- pagination
- submissions
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-16 00:23:58 +02:00
/users/{username}/collection/folders:
get :
tags :
- User Collection
2025-10-16 00:57:15 +02:00
summary : Get all the collection folders of a user.
2025-10-16 00:23:58 +02:00
description : |
Retrieves a list of folders in a collection of a user.
In case the collection has been made private by its owner, authentication as the collection owner is required. Otherwise, only folder `ID 0`` (the “All” folder) will be visible only if the requested collection of a user is public.
2025-10-16 01:40:37 +02:00
operationId : getCollectionFolders
2025-10-16 00:23:58 +02:00
parameters :
- $ref : '#/components/parameters/Username'
responses :
'200' :
description : Successfully retrieved all the collection folders by a user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
type : object
properties :
pagination :
$ref : '#/components/schemas/Pagination'
folders :
description : A list of collection folders of a user.
type : array
items :
$ref : '#/components/schemas/Folder'
required :
- pagination
- folders
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-16 00:37:54 +02:00
post :
tags :
- User Collection
2025-10-16 00:57:15 +02:00
summary : Create a new collection folder for a user.
2025-10-16 00:37:54 +02:00
description : |
Creates a new folder in the collection of a user.
This endpoint requires authentication for the owner.
2025-10-16 01:40:37 +02:00
operationId : postCollectionFolders
2025-10-16 00:37:54 +02:00
parameters :
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/Name'
description : A name for a new folder.
security :
- ConsumerKeySecret : [ ]
- UserToken : [ ]
- OAuth : [ ]
responses :
'201' :
description : Successfully create a new collection folder for a user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
$ref : '#/components/schemas/Folder'
'403' :
$ref : '#/components/responses/NotAccessable'
2025-10-16 00:57:15 +02:00
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
/users/{username}/collection/folders/{folder_id}:
get :
tags :
- User Collection
summary : Get information about a collection folder of a user.
description : |
Retrieves metadata about a collection folder of a user.
In case the `folder_id` is not 0, then the endpoint requires authentication as the collection owner.
2025-10-16 01:40:37 +02:00
operationId : getCollectionFolder
2025-10-16 00:57:15 +02:00
parameters :
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/FolderId'
responses :
'200' :
description : Successfully retrieved a specific collection folder of a user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
$ref : '#/components/schemas/Folder'
'403' :
$ref : '#/components/responses/NotAccessable'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-16 01:06:15 +02:00
post :
tags :
- User Collection
summary : Update information about a collection folder of a user.
description : |
Edits the metadata for a collection folder of a user. Please bear in mind that the folders with identifier `0` and `1` cannot be renamed.
Authentication as the collection owner is required.
2025-10-16 01:40:37 +02:00
operationId : postCollectionFolder
2025-10-16 01:06:15 +02:00
parameters :
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/FolderId'
- $ref : '#/components/parameters/Name'
description : A new name for a collection folder of a user.
security :
- ConsumerKeySecret : [ ]
- UserToken : [ ]
- OAuth : [ ]
responses :
'200' :
description : Successfully retrieved an updated collection folder of a user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
$ref : '#/components/schemas/Folder'
'403' :
$ref : '#/components/responses/NotAccessable'
'404' :
$ref : '#/components/responses/NotFound'
2025-10-16 00:37:54 +02:00
'500' :
$ref : '#/components/responses/InternalError'
2025-10-16 01:12:05 +02:00
delete :
tags :
- User Collection
summary : Delete a collection folder from a collection of a user.
description : |
Deletes a collection folder from a collection of a user.
> important: A folder must be empty before it can be deleted.
This endpoints requires authentication as the collection owner.
2025-10-16 01:40:37 +02:00
operationId : deleteCollectionFolder
2025-10-16 01:12:05 +02:00
parameters :
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/FolderId'
security :
- ConsumerKeySecret : [ ]
- UserToken : [ ]
- OAuth : [ ]
responses :
'204' :
description : Successfully delete a specific collection folder of a user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
'403' :
$ref : '#/components/responses/NotAccessable'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-16 01:40:37 +02:00
/users/{username}/collection/releases/{release_id}:
get :
tags :
- User Collection
2025-10-16 02:08:22 +02:00
summary : Get collection items of a user that contains a given release.
2025-10-16 01:40:37 +02:00
description : |
Views those collection folder of a user which contain a specified release. This will also show information about each release instance.
> important: A given `release_id` must not be `0`.
This endpoint requires authentication as the collection owner only in case the collection is private.
2025-10-16 02:08:22 +02:00
operationId : getCollectionItemsByRelease
2025-10-16 01:40:37 +02:00
parameters :
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/ReleaseId'
responses :
'200' :
2025-10-16 02:08:22 +02:00
description : Successfully retrieved a list of collection items that contains a specified release.
2025-10-16 01:40:37 +02:00
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
type : object
properties :
pagination :
$ref : '#/components/schemas/Pagination'
releases :
description : A list of collection folders of a user that contains a specified release.
type : array
items :
$ref : '#/components/schemas/ReleaseInFolder'
required :
- pagination
- releases
'403' :
$ref : '#/components/responses/NotAccessable'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-16 02:08:22 +02:00
/users/{username}/collection/folders/{folder_id}/releases:
get :
tags :
- User Collection
summary : Get collection items of a user inside a specified folder.
description : |
Returns the list of item in a specified collection folder of a user.
Basic information about each release is provided, suitable for display in a list. For detailed information, make another API call to fetch the corresponding release.
This endpoint provides pagination parameters and also, requires authentication as an owner of a collection only in case the `folder_id` is not `0`, or the collection has been made private by its owner. Otherwise, only public notes fields will be visible.
operationId : getCollectionItemsByFolder
parameters :
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/FolderId'
- $ref : '#/components/parameters/SortField'
- $ref : '#/components/parameters/SortOrder'
responses :
'200' :
description : Successfully retrieved a specific collection folder of a
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
type : object
properties :
pagination :
$ref : '#/components/schemas/Pagination'
releases :
description : A list of collection folders of a user that contains a
type : array
items :
$ref : '#/components/schemas/ReleaseInFolder'
required :
- pagination
- releases
'403' :
$ref : '#/components/responses/NotAccessable'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-16 02:22:08 +02:00
/users/{username}/collection/folders/{folder_id}/releases/{release_id}:
post :
tags :
- User Collection
summary : Add a release to a collection folder of a user.
description : |
Adds a release to a collection folder of a user.
> important: A `folder_id` must not be `0`, so it is possible to use the identifier `1` for the *Uncategorized* folder.
This endpoint requires authentication as the collection owner.
operationId : postReleaseToCollectionFolder
parameters :
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/FolderId'
- $ref : '#/components/parameters/ReleaseId'
security :
- ConsumerKeySecret : [ ]
- UserToken : [ ]
- OAuth : [ ]
responses :
'201' :
description : Successfully added a specific release into a collection folder of a user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
content :
application/json :
schema :
$ref : '#/components/schemas/ReleaseInstance'
'403' :
$ref : '#/components/responses/NotAccessable'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-16 02:36:41 +02:00
/users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}:
post :
tags :
- User Collection
summary : Update a rating for a specified release instance in a specified collection folder of a user.
description : |
Changes the rating on a release and/or move the instance to another folder.
This endpoint potentially takes 2 `folder_id` parameters: 1) in the URL (which is the folder you are requesting, and is required), and 2) in the request body (representing the folder you want to move the instance to, which is optional)
This endpoints requires authentication as the collection owner.
operationId : postChangeRatingOfRelease
parameters :
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/FolderId'
- $ref : '#/components/parameters/ReleaseId'
- $ref : '#/components/parameters/InstanceId'
- $ref : '#/components/parameters/Rating'
security :
- ConsumerKeySecret : [ ]
- UserToken : [ ]
- OAuth : [ ]
responses :
'204' :
description : Successfully updated a rating for a specific release instance inside a collection folder of a user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
'403' :
$ref : '#/components/responses/NotAccessable'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-16 02:41:24 +02:00
delete :
tags :
- User Collection
summary : Delete a specified release instance in a specified collection folder of a user.
description : |
Removes an instance of a release from a collection folder of a user.
> important: To move the release to the *Uncategorized* folder instead, use the `POST` method.
This endpoint requires authentication as the collection owner.
operationId : deleteInstanceFromCollectionFolder
parameters :
- $ref : '#/components/parameters/Username'
- $ref : '#/components/parameters/FolderId'
- $ref : '#/components/parameters/ReleaseId'
- $ref : '#/components/parameters/InstanceId'
security :
- ConsumerKeySecret : [ ]
- UserToken : [ ]
- OAuth : [ ]
responses :
'204' :
description : Successfully deleted a specific release instance inside a collection folder of a user.
headers :
X-Discogs-RateLimit :
$ref : '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used :
$ref : '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining :
$ref : '#/components/headers/RateLimitRemaining'
'403' :
$ref : '#/components/responses/NotAccessable'
'404' :
$ref : '#/components/responses/NotFound'
'500' :
$ref : '#/components/responses/InternalError'
2025-10-09 23:51:39 +00:00
components :
headers :
Link :
description : |
Contains URLs for pagination, compliant with RFC 5988.
It provides `first`, `prev`, `next`, and `last` links where applicable.
schema :
type : string
example : <https://api.discogs.com/artists/1/releases?page=2&per_page=75>; rel="next", <https://api.discogs.com/artists/1/releases?page=30&per_page=75>; rel="last"
2025-10-13 13:09:10 +00:00
required : true
2025-10-13 17:55:48 +00:00
OAuthCallback :
description : An OAuth callback confirmed.
schema :
type : boolean
default : true
OAuthSecret :
description : An OAuth request token secret.
schema :
type : string
OAuthToken :
description : An OAuth request token.
schema :
type : string
2025-10-13 13:09:10 +00:00
RateLimit :
description : A total number of requests that can be made in a minute window.
schema :
type : integer
minimum : 25
maximum : 60
example : 60
required : true
RateLimitRemaining :
description : A number of remaining requests that can be made in an existing rate limit window.
schema :
type : integer
minimum : 0
maximum : 60
example : 59
required : true
RateLimitUsed :
description : A number of requests that have been made in an existing rate limit window.
schema :
type : integer
minimum : 0
maximum : 60
example : 1
required : true
2025-10-09 23:51:39 +00:00
parameters :
ArtistId :
description : An identifier of an artist.
2025-10-16 00:57:15 +02:00
name : artist_id
2025-10-09 23:51:39 +00:00
in : path
required : true
schema :
type : integer
example : 108713
ArtistReleasesSort :
description : A value to sort the releases of an artist by.
name : sort
in : query
required : false
schema :
type : string
enum :
- year
- title
- format
2025-10-13 17:55:48 +00:00
Authorization :
description : A string to authenticate a user with a service by carrying credentials.
2025-10-16 00:57:15 +02:00
name : Authorization
2025-10-13 17:55:48 +00:00
in : header
required : true
schema :
type : string
ContentType :
description : A content type for a response.
2025-10-16 00:57:15 +02:00
name : Content-Type
2025-10-13 17:55:48 +00:00
in : header
required : true
schema :
type : string
enum :
- application/json
- application/x-www-form-urlencoded
2025-10-09 23:51:39 +00:00
Country :
description : A filter by country.
name : country
in : query
schema :
type : string
Currency :
description : |
A currency code in the marketplace.
Defaults to the authenticated users currency.
name : curr_abbr
in : query
schema :
$ref : '#/components/schemas/Currency'
2025-10-16 00:57:15 +02:00
FolderId :
description : An identifier of a collection folder.
name : folder_id
in : path
required : true
schema :
type : integer
example : 0
2025-10-09 23:51:39 +00:00
Format :
description : A filter by format.
name : format
in : query
schema :
type : string
2025-10-15 21:59:32 +00:00
HomePage :
description : A URI to a website of a user.
name : home_page
in : query
schema :
type : string
format : uri
example : https://www.some-home.page
2025-10-16 02:36:41 +02:00
InstanceId :
description : An identifier of a release instance.
name : instance_id
in : path
required : true
schema :
type : integer
minimum : 0
example : 3
2025-10-09 23:51:39 +00:00
Label :
description : A filter by label.
name : label
in : query
schema :
type : string
LabelId :
description : An identifier of a label.
name : label_id
in : path
required : true
schema :
type : integer
example : 1
2025-10-15 21:59:32 +00:00
Location :
description : A geographical location of a user.
name : location
in : query
schema :
type : string
example : Planet Earth
2025-10-09 23:51:39 +00:00
MasterId :
description : An identifier of a master.
name : master_id
in : path
required : true
schema :
type : integer
example : 1000
MasterVersionsSort :
description : A value to sort the master versions by.
name : sort
in : query
schema :
type : string
enum :
- released
- title
- format
- label
- catno
- country
2025-10-15 21:59:32 +00:00
Name :
description : A real name of a user.
name : name
in : query
schema :
type : string
2025-10-09 23:51:39 +00:00
Page :
description : A number of page of results to return.
name : page
in : query
required : false
schema :
type : integer
minimum : 1
PerPage :
description : A number of items to return per page.
name : per_page
in : query
required : false
schema :
type : integer
minimum : 1
maximum : 100
2025-10-15 21:59:32 +00:00
Profile :
description : A biographical information about a user.
name : profile
in : query
schema :
type : string
example : Some biographical information about a user goes here...
2025-10-13 15:20:20 +00:00
Rating :
description : A number (between 1 and 5) for a rating of a release.
name : rating
2025-10-09 23:51:39 +00:00
in : query
schema :
2025-10-13 15:20:20 +00:00
type : integer
minimum : 1
maximum : 5
2025-10-09 23:51:39 +00:00
ReleaseId :
description : An identifier of a release.
name : release_id
in : path
required : true
schema :
type : integer
example : 249504
2025-10-13 15:20:20 +00:00
Released :
description : A filter by release year.
name : released
in : query
schema :
type : string
2025-10-15 21:59:32 +00:00
SortField :
description : A filter by field.
name : sort
in : query
schema :
type : string
enum :
- label
- artist
- title
- catno
- format
- rating
- year
- added
2025-10-09 23:51:39 +00:00
SortOrder :
description : The order to sort the results.
name : sort_order
in : query
schema :
type : string
enum :
- asc
- desc
2025-10-13 17:55:48 +00:00
UserAgent :
name : User-Agent
description : A name of a software agent responsible for interacting with the service.
in : header
required : true
schema :
type : string
2025-10-09 23:51:39 +00:00
Username :
description : A username of a user.
name : username
in : path
required : true
schema :
type : string
example : memory
responses :
InternalError :
description : An Internal Server error was encountered.
content :
application/json :
schema :
$ref : '#/components/schemas/ServiceError'
examples :
Timeout :
value :
message : Query time exceeded. Please try a simpler query.
Malformed :
value :
message : An internal server error occurred. (Malformed query?)
2025-10-15 21:59:32 +00:00
NotAccessable :
description : A requested resource cannot be accessed due to a lack of permission.
content :
application/json :
schema :
$ref : '#/components/schemas/ServiceError'
example :
message : You must have permission to access this resource.
2025-10-09 23:51:39 +00:00
NotFound :
description : A requested resource cannot be found.
content :
application/json :
schema :
$ref : '#/components/schemas/ServiceError'
example :
message : Resource not found.
Unauthorized :
2025-10-15 21:59:32 +00:00
description : A requested resource cannot be accessed due to a lack of authentication.
2025-10-09 23:51:39 +00:00
content :
application/json :
schema :
$ref : '#/components/schemas/ServiceError'
example :
message : You must authenticate to access this resource.
Unavailable :
description : The service is currently unavailable to handle requests.
content :
application/json :
schema :
$ref : '#/components/schemas/ServiceError'
example :
message : Server is currently unavailable.
schemas :
Artist :
description : A type that represents an artist or a group.
type : object
properties :
id :
description : An identifier of an artist.
type : integer
readOnly : true
name :
description : A name of an artist.
type : string
realname :
description : A real name of an artist, if any.
type : string
resource_url :
description : A URI resource of an artist.
type : string
format : uri
readOnly : true
uri :
description : A URI representation of an artist.
type : string
format : uri
readOnly : true
releases_url :
description : A URL to the releases of an artist.
type : string
format : uri
profile :
description : A detailed profile of an artist, if any.
type : string
urls :
description : A list of URLs related to an artist, if any.
type : array
items :
type : string
format : uri
namevariations :
description : A list of name variations related to an artist, if any.
type : array
items :
type : string
members :
description : A list of artists related to an artist (in case of group), if any.
type : array
items :
$ref : '#/components/schemas/ArtistId'
images :
description : A list of images related to an artist, if any.
type : array
items :
$ref : '#/components/schemas/Image'
data_quality :
description : An explanation for the data quality related to an artist.
type : string
required :
- data_quality
- id
- name
- releases_url
- resource_url
- uri
ArtistId :
description : A type that references an artist.
type : object
properties :
id :
description : An identifier of an artist.
type : integer
readOnly : true
name :
description : A name of an artist.
type : string
resource_url :
description : A URI resource of an artist.
type : string
format : uri
readOnly : true
active :
description : A flag that indicates whether the relation is currently active or not.
type : boolean
anv :
description : TBD
type : string
join :
description : TBD
type : string
role :
description : A role of an artist.
type : string
tracks :
description : TBD
type : string
required :
- id
- name
- resource_url
ArtistRelease :
description : A type that represents a release of an artist.
type : object
properties :
id :
description : An identifier of a release.
type : integer
readOnly : true
resource_url :
description : A URI resource of a release.
type : string
format : uri
readOnly : true
type :
description : A type of a release.
type : string
enum :
- release
- master
title :
description : A title of a release.
type : string
thumb :
description : A URL link to a thumbnail of a release.
type : string
format : uri
artist :
description : A name for the artist of a release.
type : string
role :
description : A role of a release.
type : string
year :
description : A number of year of a release.
type : integer
format :
description : A format of a release.
type : string
label :
description : A label of a release.
type : string
status :
description : A status of a release.
type : string
required :
- artist
- id
- resource_url
- role
- title
- thumb
- type
ArtistResult :
description : A type that represents an artist search result.
allOf :
- $ref : '#/components/schemas/SearchResult'
- type : object
properties :
type :
enum : [ artist]
Community :
description : A type that represents a community of users, in relationship to a release.
type : object
properties :
have :
description : A number of users that have a release.
type : integer
want :
description : A number of users that want a release.
type : integer
rating :
$ref : '#/components/schemas/Rating'
submitter :
description : A reference of a user that submitted the release into the database.
$ref : '#/components/schemas/UserId'
contributors :
description : A list of references of users that contributed data of a release into the database.
type : array
items :
$ref : '#/components/schemas/UserId'
data_quality :
description : An explanation for the data quality related to a community.
type : string
status :
description : An explanation for the stat status of a community.
type : string
required :
- have
- want
Currency :
description : A list of currency codes defined in the marketplace.
type : string
enum :
- USD
- GBP
- EUR
- CAD
- AUD
- JPY
- CHF
- MXN
- BRL
- NZD
- SEK
- ZAR
2025-10-16 00:23:58 +02:00
Folder :
description : A type that represents a collection folder of a user.
type : object
properties :
id :
description : An identifier of a collection folder.
type : integer
readOnly : true
name :
description : A name of a collection folder.
type : string
count :
description : A number of items a collection folder contains.
type : integer
resource_url :
description : A URI resource of a collection folder.
type : string
format : uri
readOnly : true
required :
- count
- id
- name
- resource_url
2025-10-09 23:51:39 +00:00
Identifier :
description : A type that represents an identifier.
type : object
properties :
type :
description : A type of an identifier.
type : string
value :
description : A value of an identifier, if any.
type : string
description :
description : A description of an identifier, if any.
type : string
required :
- type
Image :
description : A type that represents an image of a resource.
type : object
properties :
type :
description : A type of an image.
type : string
enum :
- primary
- secondary
uri :
description : A URI representation of an image.
type : string
format : uri
readOnly : true
resource_url :
description : A URI resource of an image.
type : string
format : uri
readOnly : true
uri150 :
description : TBD
type : string
format : uri
width :
description : A width of an image (in pixels).
type : integer
height :
description : A height of an image (in pixels).
type : integer
required :
- height
- resource_url
- type
- uri
- uri150
- width
Label :
description : A type that represents a label, company, recording studio, etc.
type : object
properties :
id :
description : An identifier of a label.
type : integer
readOnly : true
name :
description : A name of a label.
type : string
resource_url :
description : A URI resource of a label.
type : string
format : uri
readOnly : true
uri :
description : A URI representation of a label.
type : string
format : uri
readOnly : true
releases_url :
description : A URL to the releases of a label.
type : string
format : uri
readOnly : true
profile :
description : A detailed profile of a label, if any.
type : string
contact_info :
description : A contact information of a label, if any.
type : string
parent_label :
description : A reference to a parent label of a label, if any.
$ref : '#/components/schemas/LabelId'
sublabels :
description : A list of sub-labels references of a label.
type : array
items :
$ref : '#/components/schemas/LabelId'
urls :
description : A list of URLs related to a label, if any.
type : array
items :
type : string
format : uri
images :
description : A list of images related to a label, if any.
type : array
items :
$ref : '#/components/schemas/Image'
data_quality :
description : An explanation for the data quality related to a label.
type : string
required :
- data_quality
- id
- name
- releases_url
- resource_url
- uri
LabelId :
description : A type that references a label.
type : object
properties :
id :
description : An identifier of a label.
type : integer
readOnly : true
name :
description : A name of a label.
type : string
resource_url :
description : A URI resource of a label.
type : string
format : uri
catno :
description : A category number of a label, if any.
type : string
entity_type :
description : An entity name of a label, if any.
type : string
required :
- id
- name
- resource_url
LabelRelease :
description : A type that represents a release of a label.
type : object
properties :
id :
description : An identifier of a release.
type : integer
readOnly : true
resource_url :
description : A URI resource of a release.
type : string
format : uri
thumb :
description : A URL link to a thumbnail of a release.
type : string
format : uri
artist :
description : A name for the artist of a release.
type : string
title :
description : A title of a release.
type : string
format :
description : A format of a release.
type : string
catno :
description : A category number of a release.
type : string
status :
description : A status of a release.
type : string
year :
description : A number of year of a release.
type : integer
required :
- artist
- catno
- format
- id
- resource_url
- status
- title
- thumb
- year
LabelResult :
description : A type that represents a label search result.
allOf :
- $ref : '#/components/schemas/SearchResult'
- type : object
properties :
type :
enum : [ label]
Master :
description : A type that represents a set of similar releases.
type : object
allOf :
- $ref : '#/components/schemas/Release'
- type : object
properties :
main_release :
description : An identifier of the main release for this master.
type : integer
main_release_url :
description : A URL link of the main release for this master.
type : string
format : uri
versions_url :
description : A URL link to the versions of this master.
type : string
format : uri
MasterResult :
description : A type that represents a master search result.
allOf :
- $ref : '#/components/schemas/SearchResult'
- type : object
properties :
type :
enum : [ master]
main_release :
description : An identifier of a main release for a master.
type : integer
Pagination :
description : A type that provides details about a paginated result.
type : object
properties :
page :
description : A number for the current page in a result.
type : integer
pages :
description : A total number of pages in a result.
type : integer
per_page :
description : A total number of items per page in a result.
type : integer
items :
description : A total number of items in a result.
type : integer
urls :
description : A collection of URLs to navigate through the pages in a result.
type : object
properties :
first :
description : A URL link to the first page in a result, if any.
type : string
format : uri
prev :
description : A URL link to a previous page in a result, if any.
type : string
format : uri
next :
description : A URL link to a next page in a result, if any.
type : string
format : uri
last :
description : A URL link to the last page in a result, if any.
type : string
format : uri
required :
- page
- pages
- per_page
- items
- urls
Rating :
description : A type that represents a community rating of a release.
type : object
properties :
count :
description : A number of ratings given by users of a release.
type : integer
average :
description : An average of the ratings given by users of a release.
type : number
format : float
required :
- average
- count
Release :
description : A type that eepresents a particular physical or digital object released by one or more artists.
type : object
properties :
id :
description : An identifier of a release.
type : integer
readOnly : true
title :
description : A title of a release.
type : string
resource_url :
description : A URI resource of a release.
type : string
format : uri
readOnly : true
uri :
description : A URI representation of a release.
type : string
format : uri
readOnly : true
status :
description : A status of a release.
type : string
data_quality :
description : An explanation for the data quality related to a release.
type : string
thumb :
description : A URL link to a thumbnail of a release.
type : string
format : uri
country :
description : A country of a release, if any.
type : string
year :
description : A number of year of a release, if any.
type : integer
notes :
description : Notes of a release, if any.
type : string
released :
description : A release date of a release in a free-text format.
type : string
released_formatted :
description : A released date of a release in formatted text.
type : string
date_added :
description : A date and time of a release being added to the database.
type : string
format : date-time
date_changed :
description : A date and time of a release being updated in the database.
type : string
format : date-time
lowest_price :
description : A decimal number for the lowest price of a release in the marketplace, if any.
type : number
format : float
num_for_sale :
description : A number of items of a release for sale in the marketplace, if any.
type : integer
estimated_weight :
description : An estimated weight of a release, if any.
type : integer
format_quantity :
description : A total number of formats of a release.
type : integer
master_id :
description : An identifier of a master associated with a release, if any.
type : integer
master_url :
description : A URL link to a master associated with a release, if any.
type : string
format : uri
artists :
description : A list of artists associated with a release.
type : array
items :
$ref : '#/components/schemas/ArtistId'
labels :
description : A list of labels associated with a release.
type : array
items :
$ref : '#/components/schemas/LabelId'
extraartists :
description : A list of extra artists associated with a release.
type : array
items :
$ref : '#/components/schemas/ArtistId'
formats :
description : A list of formats of a release.
type : array
items :
$ref : '#/components/schemas/ReleaseFormat'
genres :
description : A list of music genres of a release.
type : array
items :
type : string
styles :
description : A list of musical styles of a release.
type : array
items :
type : string
community :
description : Some community information of a release.
$ref : '#/components/schemas/Community'
companies :
description : A list of companies related to a release.
type : array
items :
$ref : '#/components/schemas/LabelId'
tracklist :
description : A list of tracks of a release.
type : array
items :
$ref : '#/components/schemas/Track'
videos :
description : A list of videos associated with a release.
type : array
items :
$ref : '#/components/schemas/Video'
identifiers :
description : A list of identifiers associated with a release.
type : array
items :
$ref : '#/components/schemas/Identifier'
required :
- artists
- data_quality
- genres
- id
- resource_url
- status
- styles
- title
- uri
2025-10-16 01:40:37 +02:00
ReleaseInFolder :
description : A type that represents an appearance of a release in a collection folder of a user.
type : object
properties :
id :
description : An identifier of an appearance of a release in a collection folder.
type : integer
readOnly : true
folder_id :
description : An identifier of a collection folder that contains a specified release.
type : integer
readOnly : true
instance_id :
description : An identifier of a release instance.
type : integer
readOnly : true
date_added :
description : A date and time in which a release was added into the collection folder of a user.
type : string
format : date-time
rating :
description : A rating given to a release by a user that added it into a collection folder.
type : integer
minimum : 0
maximum : 5
basic_information :
description : The available information about a release that was added into a collection folder of a user.
$ref : '#/components/schemas/Release'
2025-10-16 02:08:22 +02:00
notes :
description : A list of additional notes related to a release in a collection folder of a user.
type : array
items :
description : A type that represents a note about a release in a collection folder of a user.
type : object
properties :
field_id :
description : An identifier of a custom field.
type : integer
readOnly : true
value :
description : A value assigned to a custom field.
type : string
required :
- field_id
- value
2025-10-16 01:40:37 +02:00
required :
- basic_information
- id
- instance_id
- date_added
- rating
2025-10-16 02:22:08 +02:00
ReleaseInstance :
description : A type that represents an instace of a release.
type : object
properties :
instance_id :
description : An identifier of a release instance.
type : integer
readOnly : true
resource_url :
description : A URI resource of a release instance.
type : string
format : uri
required :
- instance_id
- resource_url
2025-10-09 23:51:39 +00:00
ReleaseFormat :
description : A type that represents a format of a release.
type : object
properties :
name :
description : A name of a format.
type : string
qty :
description : A quantity of a format.
type: string # Note : API returns this as a string
text :
description : An explanation of a format, if any.
type : string
descriptions :
description : A list of descriptions of a format.
type : array
items :
type : string
required :
- name
- qty
- descriptions
ReleaseRating :
description : A type that represents a community rating of a release.
type : object
properties :
rating :
$ref : '#/components/schemas/Rating'
release_id :
description : An identifier of a release.
type : integer
readOnly : true
required :
- rating
- release_id
ReleaseRatingByUser :
description : A type that represents a rating of a release by a user.
type : object
properties :
username :
description : A username of a user.
type : string
readOnly : true
release_id :
description : An identifier of a release.
type : integer
readOnly : true
rating :
description : A number that defines a rating value of a release.
type : integer
minimum : 0
maximum : 5
required :
- rating
- release_id
- username
ReleaseResult :
description : A type that represents a release search result.
allOf :
- $ref : '#/components/schemas/SearchResult'
- type : object
properties :
type :
enum : [ release]
ReleaseStats :
description : A type that represents the statistics of a release.
type : object
properties :
num_have :
description : A total number of users that have a release in their collection.
type : integer
minimum : 0
num_want :
description : A total number of users that have a release in their wantlist.
type : integer
minimum : 0
required :
- num_have
- num_want
ReleaseVersion :
description : A type that represents a version of a release.
type : object
properties :
id :
description : An identifier of a release version.
type : integer
readOnly : true
resource_url :
description : A URI resource of a release version.
type : string
format : uri
readOnly : true
status :
description : A status of a release version.
type : string
thumb :
description : A URL link to a thumbnail of a release version.
type : string
format : uri
format :
description : A format of a release version.
type : string
country :
description : A country of a release version, if any.
type : string
title :
description : A title of a release version.
type : string
label :
description : A label of a release version.
type : string
released :
description : A release year of a release version.
type : string
major_formats :
description : A list of formats of a release version.
type : array
items :
type : string
catno :
description : A category number of a release version, if any.
type : string
stats :
description : A type contains statictics about a release version.
type : object
properties :
community :
description : A type that represents the relationship between users and a release version.
type : object
properties :
in_collection :
description : A total number of users that have a release version in their collections.
type : integer
in_wantlist :
description : A total number of users that have a release version in their wantlist.
type : integer
required :
- in_collection
- in_wantlist
required :
- format
- id
- label
- major_formats
- released
- resource_url
- stats
- status
- thumb
- title
SearchResult :
description : A type that represents a search result.
type : object
properties :
id :
description : An identifier of a result.
type : integer
readOnly : true
type :
description : A type of a result.
type : string
enum : [ '' ]
title :
description : A title of a result
type : string
thumb :
description : A URL link to a thumbnail of a result.
type : string
format : uri
cover_image :
description : A URL link to a cover image of a result.
type : string
format : uri
resource_url :
description : A URI resource of a result.
type : string
format : uri
readOnly : true
uri :
description : A URI representation of a release.
type : string
readOnly : true
country :
description : A country of a result.
type : string
year :
description : A number of year of a result.
type : string
community :
$ref : '#/components/schemas/Community'
format :
description : A list of formats associated with a result.
type : array
items :
type : string
label :
description : A list of labels associated with a result.
type : array
items :
type : string
catno :
description : A category number of a result.
type : string
genre :
description : A list of music genres associated with a result.
type : array
items :
type : string
style :
description : A list of music styles associated with a result.
type : array
items :
type : string
barcode :
description : A list of barcode numbers associated with a result.
type : array
items :
type : string
required :
- barcode
- catno
- community
- country
- cover_image
- format
- genre
- id
- label
- resource_url
- style
- thumb
- title
- type
- uri
- year
Service :
description : A type that encapsulates any available information about the service.
type : object
properties :
api_version :
description : A current API version of the service.
type : string
documentation_url :
description : A URI link to the Developers' documentation available online.
type : string
format : uri
hello :
description : A welcome message send by the service.
type : string
statistics :
description : A type that encapsulates statistical data about the service.
type : object
properties :
artists :
description : A total number of artists registered in the service.
type : integer
labels :
description : A total number of labels registered in the service.
type : integer
releases :
description : A total number of releases registered in the service.
type : integer
required :
- artists
- labels
- releases
required :
- api_version
- documentation_url
- hello
- statistics
ServiceError :
description : A type that contains any error data.
type : object
properties :
message :
description : A message of a service error.
type : string
required :
- message
Track :
description : A type that represents a track.
type : object
properties :
position :
description : A position number of a track.
type : string
type_ :
description : A type of a track.
type : string
title :
description : A title of a track.
type : string
duration :
description : A duration of a track in number of seconds.
type : string
extraartists :
description : A list of extra artists related to a track.
type : array
items :
$ref : '#/components/schemas/ArtistId'
UserId :
description : A type that references a user.
type : object
properties :
id :
description : An identifier of a user.
type : integer
username :
description : A username of a user.
type : string
resource_url :
description : A URI resource of a user.
type : string
format : uri
required :
- resource_url
- username
2025-10-13 17:55:48 +00:00
UserIdentity :
description : A type that represents a user identity.
allOf :
- $ref : '#/components/schemas/UserId'
- type : object
properties :
consumer_name :
description : A name of an application a user utilizes to interacts with the service.
type : string
2025-10-15 21:59:32 +00:00
UserItems :
description : A type that represents all items added and/or edited by a user.
type : object
properties :
artists :
description : A list of artists added and/or edited by a user.
type : array
items :
$ref : '#/components/schemas/Artist'
labels :
description : A list of labels added and/or edited by a user.
type : array
items :
$ref : '#/components/schemas/Label'
releases :
description : A list of releases added and/or edited by a user.
type : array
items :
$ref : '#/components/schemas/Release'
UserProfile :
description : A type that represents a user profile.
allOf :
- $ref : '#/components/schemas/UserId'
- type : object
properties :
name :
description : A real name of a user.
type : string
email :
description : An e-mail address of a user, if any.
type : string
format : email
profile :
description : A biographical information of a user.
type : string
location :
description : A geographical location of a user.
type : string
uri :
description : A URL to the resource of a user.
type : string
format : uri
home_page :
description : A URI to a website of a user.
type : string
format : uri
registered :
description : A date and time a user registered to the service.
type : string
format : date-time
rank :
description : A number of rank of a user.
type : integer
curr_abbr :
description : A code of a currency used by a user in the marketplace.
type : string
minLength : 3
maxLength : 3
activated :
description : A flag that indicates whether a user is active or not.
type : boolean
marketplace_suspended :
description : A flag that indicates whether a user is suspended at the marketplace or not.
type : boolean
is_staff :
description : A flag that indicates whether a user is member of the staff at the service or not.
type : boolean
num_collection :
description : A number of items a user have in its collection.
type : integer
num_lists :
description : A number of list a user created.
type : integer
num_pending :
description : A number of items a user have in its pending list.
type : integer
num_for_sale :
description : A number of item a user have for sale in the marketplace.
type : integer
num_wantlist :
description : A number of items a user have in its want list, if any.
type : integer
rating_avg :
description : An average rating to the total of releases a user rated.
type : number
format : float
minimum : 0
maximum : 5
releases_contributed :
description : A number of releases that a user contributed information.
type : integer
releases_rated :
description : A number of release that a user rated.
type : integer
buyer_rating :
description : An average rating a user have in the marketplace as a buyer.
type : number
format : float
minimum : 0
maximum : 100
buyer_rating_stars :
description : A number of star rating a user have in the marketplace as a buyer.
type : integer
minimum : 0
maximum : 5
buyer_num_ratings :
description : A total number of ratings a user have in the marketplace as a buyer.
type : integer
seller_rating :
description : An average rating a user have in the marketplace as a seller.
type : number
format : float
minimum : 0
maximum : 100
seller_rating_stars :
description : A number of star rating a user have in the marketplace as a seller.
type : integer
minimum : 0
maximum : 5
seller_num_ratings :
description : A total number of ratings a user have in the marketplace as a seller.
type : integer
avatar_url :
description : A URL to the avatar of a user.
type : string
format : uri
banner_url :
description : A URL to th banner of a user.
type : string
format : uri
collection_fields_url :
description : A URL to the collection fields of a user.
type : string
format : uri
collection_folders_url :
description : A URL to the collection forlder of a user.
type : string
format : uri
inventory_url :
description : A URL to the inventory of a user.
type : string
format : uri
wantlist_url :
description : A URI to the want list of a user.
type : string
format : uri
required :
- activated
- avatar_url
- banner_url
- buyer_num_ratings
- buyer_rating
- buyer_rating_stars
- collection_fields_url
- collection_folders_url
- curr_abbr
- home_page
- inventory_url
- is_staff
- location
- marketplace_suspended
- name
- num_collection
- num_lists
- num_for_sale
- num_pending
- profile
- rating_avg
- rank
- registered
- releases_contributed
- releases_rated
- seller_num_ratings
- seller_rating
- seller_rating_stars
- uri
- wantlist_url
2025-10-09 23:51:39 +00:00
Video :
description : A type that represents a video.
type : object
properties :
uri :
description : A URI representation of a video.
type : string
format : uri
readOnly : true
duration :
description : A duration of a video in number of seconds.
type : integer
title :
description : A title of a video.
type : string
description :
description : A description of a video.
type : string
embed :
description : A flag that indicates whether a video is embedded or not.
type : boolean
required :
- description
- duration
- embed
- title
- uri
securitySchemes :
2025-10-15 21:59:32 +00:00
ConsumerKeySecret :
2025-10-09 23:51:39 +00:00
description : |
Discogs authentication using a key/secret pair.
The `Authorization` header should be in format:
```
Discogs key={A_CONSUMER_KEY}, secret={A_CONSUMER_SECRET}
```
type : apiKey
name : Authorization
in : header
OAuth :
description : |
OAuth 1.0a flow for third-party applications.
This is a placeholder as OpenAPI 3.1 does not directly support OAuth 1.0a.
The `Authorization` header should be constructed according to OAuth 1.0a specs, for example: `OAuth oauth_consumer_key="...", oauth_nonce="...", ...`
type : http
scheme : oauth
2025-10-15 21:59:32 +00:00
UserToken :
2025-10-09 23:51:39 +00:00
description : |
Discogs authentication using a personal access token.
The `Authorization` header should be in format:
```
Discogs token={YOUR_PERSONAL_ACCESS_TOKEN}
```
type : apiKey
name : Authorization
in : header
