API Announcements

Hi everyone,

If you'd like to receive e-mail notifications of breaking changes and major feature additions to the API, please subscribe to this topic.

API changes will continue to be documented in the changelog, as well.

If you want to discuss a particular announcement, feel free to open a new topic in this forum if one doesn't already exist.

Thanks!

We are changing the terms around image requests. Please see this thread for more details: http://www.discogs.com/forum/thread/52950c194c5e2e7adca760a0

On April 1, 2014, `to` objects will be removed from the response in the List order messages and Add a new message endpoints.

If your application reads Order messages, please start using the `from` object on each message, which represents the message author.

See the changelog and the Order resource docs for more details.

Per our previous announcement the `to` object has been removed from the response in the List order message and Add a new message endpoints today. Please use the `from` object in your applications.

Check the Changelog for up-to-date change details.

The database search endpoint (/database/search) now includes a community section which has 'want' and 'have' information for releases and master releases. See the API documentation for information.

Starting August 15th, access to our search API endpoint will require OAuth authentication with a consumer key and secret (obtainable through the Developers settings page). We receive a large volume of anonymous search requests, and an overwhelming amount are failed requests (e.g., brute-force mp3 taggers), so we would like to be able to monitor these requests at the application level. This is part of an ongoing effort to improve API uptime and response times.

Authentication requires creating an application through the developer settings:
https://www.discogs.com/settings/developers

We've added a new "Location" field for seller inventories (effective immediately). For functional information please see the forum post. Also be sure to check the changelog for technical details.

On August 22, 2014, all API endpoints marked as deprecated in the documentation will be officially removed.
This includes the following endpoints:
/release/<id>,
/artist/<name>,
/label/<name>,
/master/<id>,
/image/<filename>, and
/search.

To update your app, please direct your application's requests to the following up-to-date endpoints instead:
/releases/<id>,
/artists/<id>,
/labels/<id>,
/masters/<id>,
/images/<filename>, and
/database/search, respectively.

If you are already using the up-to-date endpoints, you can disregard this message. Please refer to documentation for specific endpoint inquiries. Also note that due to the removal of the old API endpoints, XML will not be a supported output format for the Discogs API.

Hello,

Today we are adding a few data points to existing endpoints and a few new endpoints in general. The documentation has been updated to reflect these updates.

None of these changes are breaking changes—they simply add to the existing API.

* Adding user avatar URL to the /users/<username> endpoint
This updates adds the URL to the given user's avatar (currently all are on Gravatar) in the form of a public 'avatar' data point. You will notice there is a ?s=52 parameter in the URL; you can change this size to resize the avatar to another pixel value.

* Adding date_added and date_changed to the /releases/<release_id> endpoint
This update adds when the requested release was added to the database and the last time the release was changed.

* Adding new submissions and contributions endpoints
This update adds 2 new endpoints—/users/<username>/submissions and /users/<username>/contributions—to the API. If you are new to Discogs and aren't sure what the difference between the 2 is, submissions are any edits to an existing object (release, artist, label, etc.), and a contribution is a new release added to Discogs. Both of these endpoints are public, and both accept pagination headers.

If you have any specific questions about this batch update, please see the documentation first, then start a forum thread if you question is still not answered.

Thanks!

Hi everyone,

We have heard many requests to extend the date of requiring OAuth authentication for the search endpoint (/database/search), so we have decided to extend this until Tuesday, October 14th (the Monday before is a holiday). We hope this provides all of you with ample time to update your code and keep things running smoothly.

Furthermore, we will be allowing requests to be sent over HTTPS sometime next month. HTTPS will not be required for current application IDs; however, it is highly recommended that you send requests over HTTPS.

If you have any questions, please ask them in the forums.

Thanks!
Rodney | Discogs.com

Hello,

As noted before, today we will be requiring OAuth authentication on the database search endpoint. As such, we are also announcing the availability of HTTPS on the API, so your OAuth credentials can remain secure.

If you are having difficulty getting OAuth set up, please look at the Authentication section of the API docs for help and examples. If you still have trouble, please post to the forums regarding your troubles and questions.

Thanks!
Rodney

A new form of Authentication has been released. Please see our blog post for details:
http://www.discogs.com/blog/api-update-discogs-auth

Thanks,
Rodney

The /users/<user>, /artists/<id>, and /labels/<id> endpoints can all now return formatted outputs for profile text depending on media types in their Accept headers.

Before, if you requested one of these endpoints, you would see Discogs formatting (e.g., [ u = 123] or [ url = http://www.discogs.com/]discogs[/url]) in the profile sections. Now, if you specify one of the following media types, you will receive that content transformed to plaintext or html:

Accept: application/vnd.discogs.v2.plaintext+json
Accept: application/vnd.discogs.v2.html+json
Accept: application/vnd.discogs.v2.discogs+json

The discogs media type will return the same content as if you do not include any media type. Requesting plaintext or html will return a new key/value pair with the suffix "_plaintext" or "_html" depending on what you requested. Here is what an example request and response might look like:

curl "https://api.discogs.com/artists/6270" -H "Accept: application/vnd.discogs.v2.plaintext+json"

{
"profile": "American singer and songwriter, born 31 ... got her stage name from [ a=Helmut Sommer (3)]
"profile_plaintext": "American singer and songwriter, born 31 ... got her stage name from Helmut Sommer"
...
}

If you have further questions, refer to the API docs or ask in the API forum.

Cheers,
Rodney

We've made an update to our API images; they will now be served from a dedicated images cluster. For additional detail please consult the changelog.

Note: More changes to images will be coming within the next couple months, so stay tuned!

Per the API changelog, the old/legacy API images endpoint which requires OAuth and has a 1000/day limit will be fully deprecated and shut down on March 25th, 2015.

We have just added support for user API tokens (in addition to the current OAuth support) for the official Python discogs-client. Huge thanks to tenuki for this feature, and thanks to the other users who have submitted bug fixes and updates on our Github repo.

To use this new feature, please update your discogs-client package via PyPi or through Github.

Cheers!
Rodney

In the coming weeks, we will be transitioning the Discogs API to use HTTPS/SSL exclusively, and will be deprecating HTTP access. Requests over HTTP will be redirected to their HTTPS equivalent. Please make sure that your software is capable of making an SSL connection via TLS 1.2 with a modern cipher suite, as found under "Modern compatibility" here

We will have a firm date for this transition set shortly.

The API rate-limit has been increased to 240 requests per minute (60 seconds) per IP address.

Feel free to post question to the API forum for clarification.

Thanks!
Rodney

We will be enforcing HTTPS only on the API on Monday, March 14th 2016. Please make sure your application is capable of connecting via TLS 1.2 with a modern cipher suite.

We will enforce this by redirecting all HTTP requests to their HTTPS equivalent.

The Collection Releases and Wantlist Releases endpoints now have a date_added field that displays the datetime that the Release was added to the given user's collection/wantlist.

The API is now HTTPS only. All HTTP requests will be redirected to HTTPS.

We have added an endpoint for adding, fetching, and deleting a release rating. For more details, visit:
https://www.discogs.com/developers/#page:database,header:database-release-rating

We have added an endpoint for fetching community release ratings. For more details, visit: https://www.discogs.com/developers/#page:database,header:database-community-release-rating

We have added new API endpoints for fetching User Lists: one for retrieving a high-level overview of a User's Lists, and one for a detailed view of a specific List. You can find documentation for these endpoints here: https://www.discogs.com/developers/#page:user-lists

Currently, there is only read-access to these List endpoints.

Cheers,
Rodney

We have made a few updates to the API:

* added `num_for_sale` and `lowest_price` data points to the Releases endpoint
* added a `major_formats` data point to the Master Release versions endpoint

Cheers,
Rodney

The user contributions endpoint has changed:

* the default sort is now by date added, desc
* sort parameters can be specified. See here: https://www.discogs.com/developers/#page:user-identity,header:user-identity-user-contributions

Cheers,
Rodney

For authenticated requests (Discogs Token, OAuth), we will now append rate limiting headers to API responses :

X-Discogs-Ratelimit: 240
X-Discogs-Ratelimit-Used: 1
X-Discogs-Ratelimit-Remaining: 239

In the event we update our rate limiting scheme, these headers will reflect the new limits. Upon crossing the ratelimit threshold, you will receive 429 responses from the API. Please make sure to handle these kind of errors gracefully.

Keep in mind that generic user agents that don't uniquely identify your app will be subject to more severe ratelimiting that may not be reflected in the response headers.

On April 24th, 2017, we will be enforcing the following rate limits for API requests :

For authenticated requests (Discogs Token, OAuth), clients may make 60 requests per minute per source IP.

For unauthenticated requests, clients may make 25 requests per minute per source IP.

Please make sure that your applications are able to handle 429 responses gracefully.

As a reminder, Discogs data is available for download under the CC0 No Rights Reserved license at data.discogs.com

The API rate limit change is now live. Authenticated clients may make 60 requests / minute, and unauthenticated clients may make 25 requests / minute.

On June 30th, 2018, TLS 1.0 and 1.1 will be disabled. Make sure your applications are capable of TLS 1.2 connections by this date.

On May 1st, we will make two minor changes to the API:

Authentication as the user will be required to access "curr_abbr" data from /users/<username>

Authentication as the collection owner will be required to access data from /users/<username>/collection/fields.

This is a reminder that on June 30th, 2018, TLS 1.0 and 1.1 will be disabled for api.discogs.com. Please make sure your applications are capable of TLS 1.2 connections by this date.

Today we added a small endpoint to provide the current marketplace statistics for a given release. This information is already available in the main release API endpoint, but this new endpoint should facilitate faster retrieval for those who don't need all the credits, tracks, etc.