2996 lines
102 KiB
YAML
2996 lines
102 KiB
YAML
## ===----------------------------------------------------------------------===
|
||
##
|
||
## 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’t just copy one of those! Make it unique so we can let you know if your application starts to misbehave - the alternative is that we just silently block it, which will confuse and infuriate your users.
|
||
|
||
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
|
||
description: Access data on the service.
|
||
- name: Authentication
|
||
description: Access data on authenticating to the service.
|
||
- 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.
|
||
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/Service'
|
||
'500':
|
||
$ref: '#/components/responses/Unavailable'
|
||
/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
|
||
security:
|
||
- UserToken: []
|
||
- ConsumerKeySecret: []
|
||
- OAuth: []
|
||
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'
|
||
/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:
|
||
- UserToken: []
|
||
- ConsumerKeySecret: []
|
||
- 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'
|
||
required:
|
||
- pagination
|
||
- results
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'500':
|
||
$ref: '#/components/responses/InternalError'
|
||
/artists/{artist_id}:
|
||
get:
|
||
tags:
|
||
- Database
|
||
summary: Get information about an artist.
|
||
description: Retrieves any available information for a specific artist.
|
||
operationId: getArtist
|
||
parameters:
|
||
- $ref: '#/components/parameters/ArtistId'
|
||
responses:
|
||
'200':
|
||
description: Successfully retrieved artist details.
|
||
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/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'
|
||
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:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ArtistRelease'
|
||
required:
|
||
- pagination
|
||
- releases
|
||
'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.
|
||
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/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.
|
||
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'
|
||
releases:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/LabelRelease'
|
||
required:
|
||
- pagination
|
||
- releases
|
||
'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.
|
||
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/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'
|
||
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'
|
||
versions:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ReleaseVersion'
|
||
required:
|
||
- pagination
|
||
- versions
|
||
'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.
|
||
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/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.
|
||
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/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.
|
||
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'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
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:
|
||
- UserToken: []
|
||
- ConsumerKeySecret: []
|
||
- 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'
|
||
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:
|
||
- UserToken: []
|
||
- ConsumerKeySecret: []
|
||
- 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'
|
||
/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.
|
||
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:
|
||
oneOf:
|
||
- $ref: '#/components/schemas/ReleaseStats'
|
||
- type: object
|
||
properties:
|
||
is_offensive:
|
||
type: boolean
|
||
required:
|
||
- is_offensive
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
/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'
|
||
/users/{username}/collection/folders:
|
||
get:
|
||
tags:
|
||
- User Collection
|
||
summary: Get all the collection folders of a user.
|
||
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.
|
||
operationId: getCollectionFolders
|
||
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'
|
||
post:
|
||
tags:
|
||
- User Collection
|
||
summary: Create a new collection folder for a user.
|
||
description: |
|
||
Creates a new folder in the collection of a user.
|
||
|
||
This endpoint requires authentication for the owner.
|
||
operationId: postCollectionFolders
|
||
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'
|
||
'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.
|
||
operationId: getCollectionFolder
|
||
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'
|
||
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.
|
||
operationId: postCollectionFolder
|
||
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'
|
||
'500':
|
||
$ref: '#/components/responses/InternalError'
|
||
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.
|
||
operationId: deleteCollectionFolder
|
||
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'
|
||
/users/{username}/collection/releases/{release_id}:
|
||
get:
|
||
tags:
|
||
- User Collection
|
||
summary: Get collection items of a user that contains a given release.
|
||
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.
|
||
operationId: getCollectionItemsByRelease
|
||
parameters:
|
||
- $ref: '#/components/parameters/Username'
|
||
- $ref: '#/components/parameters/ReleaseId'
|
||
responses:
|
||
'200':
|
||
description: Successfully retrieved a list of collection items that contains a specified release.
|
||
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'
|
||
/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'
|
||
/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'
|
||
/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'
|
||
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"
|
||
required: true
|
||
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
|
||
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
|
||
parameters:
|
||
ArtistId:
|
||
description: An identifier of an artist.
|
||
name: artist_id
|
||
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
|
||
Authorization:
|
||
description: A string to authenticate a user with a service by carrying credentials.
|
||
name: Authorization
|
||
in: header
|
||
required: true
|
||
schema:
|
||
type: string
|
||
ContentType:
|
||
description: A content type for a response.
|
||
name: Content-Type
|
||
in: header
|
||
required: true
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- application/json
|
||
- application/x-www-form-urlencoded
|
||
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'
|
||
FolderId:
|
||
description: An identifier of a collection folder.
|
||
name: folder_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
example: 0
|
||
Format:
|
||
description: A filter by format.
|
||
name: format
|
||
in: query
|
||
schema:
|
||
type: string
|
||
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
|
||
InstanceId:
|
||
description: An identifier of a release instance.
|
||
name: instance_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
minimum: 0
|
||
example: 3
|
||
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
|
||
Location:
|
||
description: A geographical location of a user.
|
||
name: location
|
||
in: query
|
||
schema:
|
||
type: string
|
||
example: Planet Earth
|
||
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
|
||
Name:
|
||
description: A real name of a user.
|
||
name: name
|
||
in: query
|
||
schema:
|
||
type: string
|
||
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
|
||
Profile:
|
||
description: A biographical information about a user.
|
||
name: profile
|
||
in: query
|
||
schema:
|
||
type: string
|
||
example: Some biographical information about a user goes here...
|
||
Rating:
|
||
description: A number (between 1 and 5) for a rating of a release.
|
||
name: rating
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 5
|
||
ReleaseId:
|
||
description: An identifier of a release.
|
||
name: release_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
example: 249504
|
||
Released:
|
||
description: A filter by release year.
|
||
name: released
|
||
in: query
|
||
schema:
|
||
type: string
|
||
SortField:
|
||
description: A filter by field.
|
||
name: sort
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- label
|
||
- artist
|
||
- title
|
||
- catno
|
||
- format
|
||
- rating
|
||
- year
|
||
- added
|
||
SortOrder:
|
||
description: The order to sort the results.
|
||
name: sort_order
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- asc
|
||
- desc
|
||
UserAgent:
|
||
name: User-Agent
|
||
description: A name of a software agent responsible for interacting with the service.
|
||
in: header
|
||
required: true
|
||
schema:
|
||
type: string
|
||
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?)
|
||
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.
|
||
NotFound:
|
||
description: A requested resource cannot be found.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ServiceError'
|
||
example:
|
||
message: Resource not found.
|
||
Unauthorized:
|
||
description: A requested resource cannot be accessed due to a lack of authentication.
|
||
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
|
||
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
|
||
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
|
||
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'
|
||
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
|
||
required:
|
||
- basic_information
|
||
- id
|
||
- instance_id
|
||
- date_added
|
||
- rating
|
||
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
|
||
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
|
||
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
|
||
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
|
||
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:
|
||
ConsumerKeySecret:
|
||
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
|
||
UserToken:
|
||
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
|