664 lines
23 KiB
YAML
664 lines
23 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 related 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.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Service'
|
||
'500':
|
||
$ref: '#/components/responses/Unavailable'
|
||
/artists/{artist_id}:
|
||
get:
|
||
summary: Get information about an artist.
|
||
operationId: getArtist
|
||
description: Retrieves any available information for a specific artist.
|
||
tags:
|
||
- Database
|
||
parameters:
|
||
- $ref: '#/components/parameters/ArtistId'
|
||
responses:
|
||
'200':
|
||
description: Successfully retrieved artist details.
|
||
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'
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
pagination:
|
||
$ref: '#/components/schemas/Pagination'
|
||
releases:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ArtistRelease'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
components:
|
||
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.
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uri
|
||
namevariations:
|
||
description: A list of name variations related to an artist.
|
||
type: array
|
||
items:
|
||
type: string
|
||
members:
|
||
description: A list of artists related to an artist (in case of group).
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ArtistID'
|
||
images:
|
||
description: A list of images related to an artist.
|
||
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: TBD
|
||
type: string
|
||
tracks:
|
||
description: TBD
|
||
type: string
|
||
required:
|
||
- active
|
||
- 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
|
||
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
|
||
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
|
||
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
|
||
parameters:
|
||
ArtistId:
|
||
name: artist_id
|
||
description: An identifier of an artist.
|
||
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
|
||
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
|
||
SortOrder:
|
||
description: The order to sort the results.
|
||
name: sort_order
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- asc
|
||
- desc
|
||
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"
|
||
responses:
|
||
NotFound:
|
||
description: A requested resource cannot be found.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ServiceError'
|
||
example:
|
||
message: Resource not found.
|
||
Unavailable:
|
||
description: The service is currently unavailable to handle requests.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ServiceError'
|
||
example:
|
||
message: Server is currently unavailable.
|