## ===----------------------------------------------------------------------=== ## ## This source file is part of the Discogs Service open source project ## ## Copyright (c) 2026 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 [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 **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 you 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: ; rel=next, ; rel=first, ; rel=last, ; 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 ``` In 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 Created** 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 does 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: 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: Marketplace description: Interact with the marketplace, including listings, orders, and fees. - 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 an 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: An 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 catalog 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 the rating of a 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 the rating of a 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 the rating of a 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 the rating of a release by a user. description: | Deletes 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 the statistics of a 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 statistics. > 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 endpoint 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' contributions: description: A type that represents all items contributed 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 endpoint 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 created 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 endpoint 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 deleted 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 items 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 items in 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: type: object properties: pagination: $ref: '#/components/schemas/Pagination' releases: description: A list of items in a collection folder of a user. 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 endpoint 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' requestBody: $ref: '#/components/requestBodies/MoveInstance' 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' delete: tags: - User Collection summary: Delete a specified release instance in a specified collection folder of a user. description: | Removes an instance of a release from a collection folder of a user. > important: To move the release to the *Uncategorized* folder instead, use the `POST` method. This endpoint requires authentication as the collection owner. operationId: deleteInstanceFromCollectionFolder parameters: - $ref: '#/components/parameters/Username' - $ref: '#/components/parameters/FolderId' - $ref: '#/components/parameters/ReleaseId' - $ref: '#/components/parameters/InstanceId' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '204': description: Successfully deleted a specific release instance inside a collection folder of a user. headers: X-Discogs-RateLimit: $ref: '#/components/headers/RateLimit' X-Discogs-RateLimit-Used: $ref: '#/components/headers/RateLimitUsed' X-Discogs-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' '403': $ref: '#/components/responses/NotAccessable' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}/fields/{field_id}: post: tags: - User Collection summary: Update a value of a custom field assigned to a release instance. description: Changes the value of a notes field on a particular instance. operationId: editFieldsInstance parameters: - $ref: '#/components/parameters/Username' - $ref: '#/components/parameters/FolderId' - $ref: '#/components/parameters/ReleaseId' - $ref: '#/components/parameters/InstanceId' - $ref: '#/components/parameters/FieldId' - $ref: '#/components/parameters/FieldValue' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '204': description: Successfully updated a value of a custom notes field for a release instance in a collection folder. 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/fields: get: tags: - User Collection summary: Get a list of custom fields defined by a user. description: | Retrieves a list of collection notes fields defined by a user. These fields are available on every release in a collection. In case a collection has been made private by its owner, then the endpoint requires authentication as the collection owner. Otherwise only public custom fields will be visible. operationId: getCustomFields parameters: - $ref: '#/components/parameters/Username' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '200': description: Successfully retrieved a list of custom fields defined 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: description: A type that contains a list of retrieved custom fields of a user. type: object properties: fields: description: A list of custom fields. type: array items: $ref: '#/components/schemas/CustomField' required: - fields '403': $ref: '#/components/responses/NotAccessable' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /users/{username}/collection/value: get: tags: - User Collection summary: Get the estimated monetary value for a collection of a user. description: | Returns the estimated minimum, median, and maximum values for a collection of a user. This endpoint requires authentication as the collection owner. operationId: getCollectionValue parameters: - $ref: '#/components/parameters/Username' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '200': description: Successfully retrieved the estimated monetary value for a collection 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/CollectionValue' '403': $ref: '#/components/responses/NotAccessable' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /users/{username}/wants: get: tags: - User Wantlist summary: Get a list of releases in a wantlist of a user. description: | Returns the list of releases in a wantlist of a user. Accepts pagination parameters. 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. If the wantlist has been made private by its owner, you must be authenticated as the owner to view it. The notes field will be visible if you are authenticated as the wantlist owner. operationId: getWantlist parameters: - $ref: '#/components/parameters/Username' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: '200': description: Successfully retrieved a list of releases in a wantlist of a user. 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: description: A type that contains a list of releases in a wantlist of a user. type: object properties: pagination: $ref: '#/components/schemas/Pagination' wants: description: A list of releases in a wantlist of a user. type: array items: $ref: '#/components/schemas/ReleaseInFolder' required: - pagination - wants '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/NotAccessable' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /users/{username}/wants/{release_id}: put: tags: - User Wantlist summary: Add a release into a wantlist of a user. description: | Adds a release to a wantlist of a user. This endpoint requires authentication as the wantlist owner. operationId: addToWantlist parameters: - $ref: '#/components/parameters/Username' - $ref: '#/components/parameters/ReleaseId' - $ref: '#/components/parameters/Notes' - $ref: '#/components/parameters/Rating' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '201': description: Successfully added a release into a wantlist 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: description: A type that represents a newly added release in a wantlist of a user. $ref: '#/components/schemas/ReleaseInFolder' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/NotAccessable' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' post: tags: - User Wantlist summary: Update a release in a wantlist of a user. description: | Modifies some metadata associated with a release in a wantlist of a user. This endpoint requires authentication as the wantlist owner. operationId: updateInWantlist parameters: - $ref: '#/components/parameters/Username' - $ref: '#/components/parameters/ReleaseId' - $ref: '#/components/parameters/Notes' - $ref: '#/components/parameters/Rating' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '200': description: Successfully updated a release in a wantlist 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: description: A type that represents an updated release in a wantlist of a user. $ref: '#/components/schemas/ReleaseInFolder' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/NotAccessable' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' delete: tags: - User Wantlist summary: Delete a release from a wantlist of a user. description: | Deletes a release from a wantlist of a user. This endpoint requires authentication as the wantlist owner. operationId: deleteFromWantlist parameters: - $ref: '#/components/parameters/Username' - $ref: '#/components/parameters/ReleaseId' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '204': description: Successfully deleted a release from a wantlist 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' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/NotAccessable' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /users/{username}/lists: get: tags: - User Lists summary: Get a list of lists of a user. description: | Returns a list of lists created by a user. This endpoint accepts pagination and, to show private lists it is required to be authenticated as an owner. operationId: getLists parameters: - $ref: '#/components/parameters/Username' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: '200': description: Successfully retrieved a list of lists of a user. 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: description: A type that contains a list of lists of a user. type: object properties: pagination: $ref: '#/components/schemas/Pagination' lists: description: A list of lists of a user. type: array items: $ref: '#/components/schemas/ListId' required: - lists - pagination '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /lists/{list_id}: get: tags: - User Lists summary: Get items from a specified list. description: | Returns items from a specified list. Private lists are not shown unless a user is authenticated as an owner. operationId: getList parameters: - $ref: '#/components/parameters/ListId' responses: '200': description: Successfully retrieved the items associated with a specified list. 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/List' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /users/{username}/inventory: get: tags: - Marketplace summary: Get the listings in an inventory of a seller. description: | Returns the list of listings for an inventory of a user. Basic information about each listing and the corresponding release is provided, suitable for display in a list. For detailed information about the release, make another API call to fetch the corresponding Release. This endpoint accepts pagination and also, in case of authenticated as an inventory owner, items that not only have the `For Sale` state will be shown as well as other extra fields in those items such as `weight`, `format_quality`, `external_id`, `location`, and `quantity_keys`. Note that the `quantity` field is read-only for *NearMint* users, who will see *1* for all quantity values, regardless of their actual count. In case the user is authorized, the listing will contain a `in_cart` boolean field indicating whether or not this listing is in their cart. operationId: getInventory parameters: - $ref: '#/components/parameters/Username' - $ref: '#/components/parameters/InventoryStatus' - $ref: '#/components/parameters/SortInventory' - $ref: '#/components/parameters/SortOrder' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: '200': description: Successfully retrieved a list of listings in an inventory of a seller. 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: description: A type that contains a list of listings in an inventory of a user. type: object properties: pagination: $ref: '#/components/schemas/Pagination' listings: description: A list of listings in an inventory of a user. type: array items: $ref: '#/components/schemas/Listing' required: - listings - pagination '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' '500': $ref: '#/components/responses/InternalError' /marketplace/listings/{listing_id}: get: tags: - Marketplace summary: Get information about a listing in the marketplace. description: | Views the data associated with a listing in the marketplace. In case of authenticated as an inventory owner, items that not only have the `For Sale` state will be shown as well as other extra fields in those items such as `weight`, `format_quality`, `external_id`, `location`, and `quantity_keys`. Note that the `quantity` field is read-only for *NearMint* users, who will see *1* for all quantity values, regardless of their actual count. In case the user is authorized, the listing will contain a `in_cart` boolean field indicating whether or not this listing is in their cart. operationId: getListing parameters: - $ref: '#/components/parameters/ListingId' - $ref: '#/components/parameters/Currency' responses: '200': description: Successfully retrieved a listing in a marketplace. 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/Listing' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' '500': $ref: '#/components/responses/InternalError' post: tags: - Marketplace summary: Update a listing in a marketplace. description: | Edits the data associated with a listing in a marketplace. In case a status of a listing is not `For Sale`, `Draft`, or `Expired`, it cannot be modified - only deleted. To re-list a Sold listing, a new listing must be created. This endpoint requires authentication as a listing owner. operationId: editListing parameters: - $ref: '#/components/parameters/ListingId' requestBody: $ref: '#/components/requestBodies/Listing' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '204': description: Successfully edited a listing from a marketplace. 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' '403': $ref: '#/components/responses/NotAccessable' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' '500': $ref: '#/components/responses/InternalError' delete: tags: - Marketplace summary: Delete a listing from a marketplace. description: | Removes permanently a listing from a Marketplace. This endpoint requires authentication as a listing owner. operationId: deleteListing parameters: - $ref: '#/components/parameters/ListingId' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '204': description: Successfully deleted a listing from a marketplace. 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' '403': $ref: '#/components/responses/NotAccessable' '500': $ref: '#/components/responses/InternalError' /marketplace/listings: post: tags: - Marketplace summary: Create a new listing in a marketplace. description: | Creates a new listing in a marketplace. This endpoint requires authentication, to add a listing into an inventory of an authenticated user. operationId: createListing requestBody: $ref: '#/components/requestBodies/Listing' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '201': description: Successfully added a listing into a marketplace. 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/ListingId' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/NotAccessable' '500': $ref: '#/components/responses/InternalError' /marketplace/orders: get: tags: - Marketplace summary: Get a list of orders for a seller in a marketplace. description: | Returns a list of orders for a seller in a marketplace. This endpoint accepts pagination and authentication as a seller. operationId: getOrders parameters: - $ref: '#/components/parameters/OrderStatus' - $ref: '#/components/parameters/OrderCreatedAfter' - $ref: '#/components/parameters/OrderCreatedBefore' - $ref: '#/components/parameters/OrderArchived' - $ref: '#/components/parameters/SortOrderField' - $ref: '#/components/parameters/SortOrder' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '200': description: Successfully retrieved a list of orders for a seller in a marketplace. 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: description: A type that contains a list of orders for a seller in a marketplace. type: object properties: pagination: $ref: '#/components/schemas/Pagination' listings: description: A list of orders for a seller in a marketplace. type: array items: $ref: '#/components/schemas/Order' required: - listings - pagination '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/NotAccessable' '500': $ref: '#/components/responses/InternalError' /marketplace/orders/{order_id}: get: tags: - Marketplace summary: Get an order for a seller in a marketplace. description: | Views the data associated with an order. This endpoint requires authentication as a seller. operationId: getOrder parameters: - $ref: '#/components/parameters/OrderId' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '200': description: Successfully retrieved an order for a seller from a marketplace. 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/Order' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/NotAccessable' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /marketplace/orders/{order_id}/messages: get: tags: - Marketplace summary: Get a list of messages related to an order. description: | Returns a list of messages related to an order. This endpoint accepts pagination and requires authentication as a seller. operationId: getOrderMessages parameters: - $ref: '#/components/parameters/OrderId' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '200': description: Successfully retrieved a list of messages related to an order. 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: description: A type that contains a list of messages for a related order in a marketplace. type: object properties: pagination: $ref: '#/components/schemas/Pagination' messages: description: A list of messages for an order in a marketplace. type: array items: $ref: '#/components/schemas/OrderMessage' required: - messages - pagination '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/NotAccessable' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' post: tags: - Marketplace summary: Add a message to an order. description: | Adds a new message to the order’s message log. When posting a new message, it is also possible to update the order status. In this case, the message will automatically be prepended with: *Seller changed status from Old Status to New Status* While both `message` and `status` properties are each optional, one or both must be present. This endpoint requires authentication as a seller. operationId: addOrderMessage parameters: - $ref: '#/components/parameters/OrderId' requestBody: $ref: '#/components/requestBodies/OrderMessage' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '201': description: Successfully added a new message to a list of messages related to an order. 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: description: A message that has been added to an order. $ref: '#/components/schemas/OrderMessage' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/NotAccessable' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /marketplace/fee/{price}: get: tags: - Marketplace summary: Get an estimated fee for selling an item in a marketplace. description: | Calculates an estimated fee for selling an item in a marketplace. This endpoint requires authentication. operationId: getFee parameters: - $ref: '#/components/parameters/Price' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '200': description: Successfully retrieved an estimated fee for selling an item in a marketplace. 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: description: An estimated fee in a default currency. $ref: '#/components/schemas/Price' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' /marketplace/fee/{price}/{currency}: get: tags: - Marketplace summary: Get an estimated fee for selling an item in a marketplace, based on a given currency. description: | Calculates an estimated fee for selling an item in a marketplace, based on a given currency. This endpoint requires authentication. operationId: getFeeWithCurrency parameters: - $ref: '#/components/parameters/Price' - $ref: '#/components/parameters/CurrencyInPath' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '200': description: Successfully retrieved an estimated fee for selling an item in a marketplace, based on a given currency. 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: description: An estimated fee in a default currency. $ref: '#/components/schemas/Price' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' /marketplace/price_suggestions/{release_id}: get: tags: - Marketplace summary: Get some price suggestions for a given release. description: | Retrieves price suggestions for a provided release. If no suggestions are available, an empty object will be returned. This endpoint requires authentication and also, the user should have filled out the seller settings. Suggested prices will be denominated in the user's selling currency. operationId: getPriceSuggestions parameters: - $ref: '#/components/parameters/ReleaseId' security: - ConsumerKeySecret: [] - UserToken: [] - OAuth: [] responses: '200': description: Successfully retrieved price suggestions for a given 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: description: A group of price suggestions for a release. $ref: '#/components/schemas/ReleasePriceSuggestions' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /marketplace/stats/{release_id}: get: tags: - Marketplace summary: Get some statistics of a release. description: | Retrieves some statistics for a release in a marketplace. These statistics reflect the current state of a release in a marketplace, and include the number of items currently for sale, lowest listed price of any item for sale, and whether the item is blocked for sale in a marketplace. This endpoint mandates that authentication is optional. In case of authentication, the lowest currency expressed in their own buyer currency, configurable in buyer settings by default, in the absence of the `curr_abbr` parameter in the query. Otherwise, the price expressed in US dollars, if no currency is provided. Releases that have no items for sale in a marketplace returns no data in the `lowest_price` and `num_for_sale` keys. Releases that are blocked for sale will also have no data for these keys. operationId: getStatistics parameters: - $ref: '#/components/parameters/ReleaseId' - $ref: '#/components/parameters/Currency' responses: '200': description: Successfully retrieved statistics for a given 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: description: A group of statistics for a release. $ref: '#/components/schemas/ReleaseStatistics' '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: ; rel="next", ; rel="last" 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' CurrencyInPath: description: A currency code in a marketplace. name: currency in: path required: true schema: $ref: '#/components/schemas/Currency' FieldId: description: An identifier of a custom field. name: field_id in: path required: true schema: type: integer minimum: 1 example: 8 FieldValue: description: A value of a custom field. name: value in: query required: true schema: type: string 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 InventoryStatus: description: A status of an inventory. name: status in: query schema: type: string enum: - All - For Sale - Draft - Expired - Sold - Violation - Suspended - Deleted 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 ListId: description: An identifier of a list. name: list_id in: path required: true schema: type: integer minimum: 0 example: 123 ListingId: description: An identifier of a listing. name: listing_id in: path required: true schema: type: integer minimum: 0 example: 172723812 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 Notes: description: A custom note about a release. name: notes in: query schema: type: string OrderArchived: description: A flag that indicates whether to show orders with a specific archived status or not. name: archived in: query schema: type: boolean OrderCreatedAfter: description: An indication to show order created after a given ISO 8601 timestamp. name: created_after in: query schema: type: string format: date-time OrderCreatedBefore: description: An indication to show order created before a given ISO 8601 timestamp. name: created_before in: query schema: type: string format: date-time OrderId: description: An identifier of an order. name: order_id in: path required: true schema: type: integer minimum: 0 OrderStatus: description: An indication to show order with a given status only. name: status in: query schema: $ref: '#/components/schemas/OrderStatus' 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 Price: description: A number for a price of a release. name: price in: path required: true schema: type: number format: float minimum: 0 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 for a rating of a release. name: rating in: query schema: type: integer minimum: 0 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 SortInventory: description: A filter by an inventory field. name: sort in: query schema: type: string enum: - listed - price - item - artist - label - catno - audio - status - location SortOrder: description: The order to sort the results. name: sort_order in: query schema: type: string enum: - asc - desc SortOrderField: description: A filter by an order field. name: sort in: query schema: type: string enum: - id - buyer - created - status - last_activity 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 requestBodies: Listing: description: A container to use in case of either creating a new release into a marketplace or modifying a release already existing in a marketplace. required: true content: application/json: schema: properties: listing_id: description: An identifier of a listing, if any. type: integer minimum: 0 release_id: description: An identifier of a release. type: integer minimum: 0 condition: description: A media condition of a listing. $ref: '#/components/schemas/ConditionMedia' sleeve_condition: description: A sleeve condition of a listing. $ref: '#/components/schemas/ConditionSleeve' price: description: A price of a listing in a seller's currency. type: number format: float minimum: 0 comments: description: Any remark about a listing that would be shown to buyers. type: string allow_offers: description: A flag that indicates whether buyers are allowed to make offers for a listing or not. type: boolean status: description: A status explanation of a listing. type: string enum: - Draft - For Sale default: Draft external_id: description: | A freeform field that could be used by a seller to comment about a listing. The information stored in this field is not shown to anybody except a seller who owns a listing. type: string location: description: | A geographical location of a listing. The information stored in this field is not shown to anybody except a seller who owns a listing. type: string weight: description: A weight of a listing in grams for the purpose of calculating shipping costs. anyOf: - type: number format: float - type: string enum: - auto default: auto format_quantity: description: A number of items of a listing, for the purpose of calculating shipping costs. anyOf: - type: number format: float - type: string enum: - auto default: auto required: - condition - price - release_id - status OrderMessage: description: A container to use in case to add a message to an existing order. required: true content: application/json: schema: properties: message: description: A message to attach to an order. type: string status: description: An update to a status of an order. type: string MoveInstance: description: A container to use in case of moving a release instance from a collection folder into another. required: false content: application/json: schema: properties: folder_id: description: An identifier of a collection folder to move a release instance. type: integer minimum: 0 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. Unprocessable: description: An invalid parameter has been sent. content: application/json: schema: $ref: '#/components/schemas/ServiceError' example: message: Invalid parameter - expected one of accepted values. 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: An ANV (Artist Name Variation), if any. type: string join: description: A join relationship descriptor, if any. type: string role: description: A role of an artist. type: string tracks: description: A list of tracks associated with an artist, if any. 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 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] CollectionValue: description: A type that represents the monetary value of a collection. type: object properties: maximum: description: An estimated maximum monetary value of a collection. type: string median: description: An estimated median monetary value of a collection. type: string minimum: description: An estimated minimum monetary value of a collection. type: string required: - maximum - median - minimum 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 status of a community. type: string ConditionMedia: description: A type that represents a media condition. type: string enum: - Mint (M) - Near Mint (NM or M-) - Very Good Plus (VG+) - Very Good (VG) - Good Plus (G+) - Good (G) - Fair (F) - Poor (P) ConditionSleeve: description: A type that represents a sleeve condition. type: string enum: - Mint (M) - Near Mint (NM or M-) - Very Good Plus (VG+) - Very Good (VG) - Good Plus (G+) - Good (G) - Fair (F) - Poor (P) - Generic - Not Graded - No Cover Currency: description: A list of currency codes defined in the marketplace. type: string minLength: 3 maxLength: 3 enum: - USD - GBP - EUR - CAD - AUD - JPY - CHF - MXN - BRL - NZD - SEK - ZAR CustomField: description: A type that represents a custom field. type: object properties: id: description: An identifier of a custom field. type: integer readOnly: true name: description: A name of a custom field. type: string position: description: A position of a custom field. type: integer minimum: 1 public: description: A flag that indicates whether a custom field is public or not. type: boolean type: description: A type of a custom field. type: string enum: - dropdown - textarea lines: description: A number of lines of content to allow for a custom field of a textarea type. type: integer minimum: 1 options: description: A list of options to display, in case the field is of dropdown type. type: array items: type: string required: - id - name - position - public - type 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: A URI to a 150x150 pixel thumbnail of an image. 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 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] ListId: description: A type that references a list. type: object properties: id: description: An identifier of a list. type: integer minimum: 0 readOnly: true uri: description: A URI representation of a list. type: string format: uri resource_url: description: A URI resource of a list. type: string format: uri readOnly: true name: description: A name of a list. type: string description: description: A descriptive explanation of a list. type: string public: description: A flag that indicates whether a list is public or not. type: boolean date_added: description: A date and time in which a list was created. type: string format: date-time date_changed: description: A date and time in which a list was last changed. type: string format: date-time required: - date_added - date_changed - description - id - name - public - resource_url - uri List: description: A type that represents a list. type: object properties: list_id: description: An identifier of a list. type: integer minimum: 0 readOnly: true resource_url: description: A URI resource of a list. type: string format: uri readOnly: true url: description: A URL representation of a list. type: string format: uri name: description: A name of a list. type: string description: description: A descriptive explanation of a list. type: string public: description: A flag that indicates whether a list is public or not. type: boolean created_ts: description: A date and time in which a list was created. type: string format: date-time modified_ts: description: A date and time in which a list was last modified. type: string format: date-time items: description: A list of items contained in a list. type: array items: description: A type that represents a list item. type: object properties: id: description: An identifier of a list item. type: integer minimum: 0 readOnly: true uri: description: A URI representation of a list item. type: string format: uri readOnly: true resource_url: description: A URI resource of a list item. type: string format: uri readOnly: true type: description: A type of a list item. type: string enum: - artist - label - release display_title: description: A display title of a list item. type: string image_url: description: An image URL associated with a list item. type: string format: uri comment: description: A comment associated with a list item. type: string required: - display_title - id - image_url - resource_url - type - uri required: - created_ts - description - list_id - modified_ts - name - public - resource_url - url Listing: description: A type that represents a listing. type: object properties: id: description: An identifier of a listing. type: integer minimum: 0 readOnly: true uri: description: A URI representation of a listing. type: string format: uri readOnly: true resource_url: description: A URI resource of a listing. type: string format: uri readOnly: true status: description: A status of a listing. type: string enum: - Draft - Expired - For Sale - Sold price: description: A price assigned to a listing. $ref: '#/components/schemas/Price' original_price: description: An original price assigned to a listing. $ref: '#/components/schemas/PriceFormatted' shipping_price: description: A shipping price assigned to a listing. $ref: '#/components/schemas/Price' original_shipping_price: description: An original shipping price assigned to a listing. $ref: '#/components/schemas/PriceFormatted' allow_offers: description: A flag that indicates whether a listing allows receiving offers or not. type: boolean offer_submitted: description: A flag that indicates whether a user submitted an offer for a listing. type: boolean condition: description: A media condition of a listing. $ref: '#/components/schemas/ConditionMedia' sleeve_condition: description: A sleeve condition of a listing. $ref: '#/components/schemas/ConditionSleeve' posted: description: A date and time a listing was posted in the marketplace. type: string format: date-time ships_from: description: A country from where a listing will be shipped. type: string comments: description: A comment related to a listing. type: string seller: description: A seller of a listing. $ref: '#/components/schemas/Seller' release: description: A release of a listing. $ref: '#/components/schemas/ReleaseInListing' audio: description: A flag that indicates whether is an audio listing or not. type: boolean external_id: description: Any private comment for the seller, if any. type: string format_quantity: description: A number of units this listing counts as for shipping, if any. type: integer minimum: 1 location: description: A geographical location of a listing, if any. type: string weight: description: A weight in grams of a listing, if any. type: integer minimum: 0 in_cart: description: A flag that indicates whether a listing is in the shopping cart of a user, if any. type: boolean required: - allow_offers - audio - comments - condition - id - offer_submitted - original_price - original_shipping_price - posted - price - release - resource_url - seller - shipping_price - ships_from - sleeve_condition - status - uri ListingId: description: A type that references a listing. type: object properties: listing_id: description: An identifier of a listing. type: integer minimum: 0 readOnly: true resource_url: description: A URI resource of a listing. type: string format: uri readOnly: true required: - listing_id - resource_url 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 Order: description: A type that represents an order. allOf: - $ref: '#/components/schemas/OrderId' - type: object properties: messages_url: description: A URI resource for the messages of an order. type: string format: uri readOnly: true uri: description: A URI representation of an order. type: string format: uri readOnly: true buyer: description: A buyer of an order. $ref: '#/components/schemas/UserIdentity' seller: description: A seller of an order. $ref: '#/components/schemas/UserIdentity' created: description: A date and time in which an order was created. type: string format: date-time status: description: A status of an order. $ref: '#/components/schemas/OrderStatus' next_status: description: A list of upcoming statuses of an order. type: array items: $ref: '#/components/schemas/OrderStatus' last_activity: description: A date and time for the last update of an order. type: string format: date-time items: description: A list of items of an order. type: array items: $ref: '#/components/schemas/OrderItem' fee: description: A fee amount of an order. $ref: '#/components/schemas/Price' shipping: description: A shipping amount of an order. $ref: '#/components/schemas/Shipping' total: description: A total amount of an order. $ref: '#/components/schemas/Price' shipping_address: description: A container for all the shipping details of a buyer of an order. type: string additional_instructions: description: A container for any extra information about shipping of an order. type: string archived: description: A flag that indicates whether an order was archived or not. type: boolean required: - additional_instructions - archived - buyer - created - fee - items - last_activity - messages_url - next_status - seller - shipping - shipping_address - status - total - uri OrderId: description: A type that references an order. type: object properties: id: description: An identifier of an order. type: string readOnly: true resource_url: description: A URI resource of an order. type: string format: uri readOnly: true required: - id - resource_url OrderItem: description: A type that represents an item of an order. type: object properties: id: description: An identifier of an order item. type: integer minimum: 0 readOnly: true price: description: A price of an order item. $ref: '#/components/schemas/Price' release: description: A type that represents a release in an order. $ref: '#/components/schemas/ReleaseInListing' required: - id - price - release OrderMessage: description: A type that represents a message of an order. type: object properties: timestamp: description: A timestamp of a message for an order. type: string format: date-time type: description: A type of message for an order. type: string enum: - message - refund_received - refund_sent - shipping - status subject: description: A subject of a message for an order. type: string message: description: A body of a message for an order. type: string order: description: A reference to an order. $ref: '#/components/schemas/OrderId' status_id: description: An identifier for a status of an order, if any. type: integer minimum: 0 original: description: An original status identifier of an order, if any. type: integer minimum: 0 new: description: A new status identifier of an order, if any. type: integer minimum: 0 actor: description: An actor that sent a message for an order, if any. $ref: '#/components/schemas/OrderMessageSender' from: description: A user that sent a message for an order, if any. $ref: '#/components/schemas/OrderMessageSender' refund: description: A requested refund for an order, if any. type: object properties: amount: description: An amount for a requested refund of an order. type: integer minimum: 0 order: description: A reference to an order for which a refund has been requested. $ref: '#/components/schemas/OrderId' required: - amount - order required: - message - order - subject - timestamp - type OrderMessageSender: description: A type that represents a message sender for an order. type: object properties: id: description: An identifier of a message sender for an order, if any. type: integer minimum: 0 readOnly: true resource_url: description: A URI resource of a message sender for an order. type: string format: uri readOnly: true username: description: A username of a message sender for an order. type: string avatar_url: description: A URI avatar of a message sender for an order, if any. type: string format: uri required: - resource_url - username OrderStatus: description: A type that represents a status of an order. type: string enum: - All - New Order - Buyer Contacted - Invoice Sent - Payment Pending - Payment Received - In Progress - Shipped - Merged - Order Changed - Refund Sent - Cancelled - Cancelled (Non-Paying Buyer) - Cancelled (Item Unavailable) - Cancelled (Per Buyer's Request) - Cancelled (Refund Received) 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 Price: description: A type that represents a price. type: object properties: currency: $ref: '#/components/schemas/Currency' value: description: A decimal number of a price. type: number format: float minimum: 0 required: - currency - value PriceFormatted: description: A type that represents a formatted price. type: object properties: curr_abbr: description: An abbreviation of a currency in a marketplace. $ref: '#/components/schemas/Currency' curr_id: description: An identifier of a currency in a marketplace. type: integer minimum: 0 readOnly: true formatted: description: A price in formatted form. type: string value: description: A decimal number of a price. type: number format: float minimum: 0 required: - curr_abbr - curr_id - formatted - value 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 represents 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 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 blocked_from_sale: description: A flag that indicates whether a release is blocked for sale in a marketplace. type: boolean is_offensive: description: A flag that indicates whether a release has explicit language/content or not. type: boolean 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, if any. type: array items: $ref: '#/components/schemas/LabelId' tracklist: description: A list of tracks of a release, if any. type: array items: $ref: '#/components/schemas/Track' images: description: A list of images of a release, if any. type: array items: $ref: '#/components/schemas/Image' videos: description: A list of videos associated with a release, if any. 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 ReleaseId: description: A type that references a release. type: object properties: id: description: An identifier of a release. type: integer minimum: 0 readOnly: true resource_url: description: A URI resource of a release. type: string format: uri readOnly: true required: - id - resource_url 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, if any. type: integer readOnly: true instance_id: description: An identifier of a release instance, if any. type: integer readOnly: true resource_url: description: A URI resource to a release, if any. type: string format: uri 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 - date_added ReleaseInListing: description: A type that represents a release in a listing. allOf: - $ref: '#/components/schemas/ReleaseId' - type: object properties: catalog_number: description: A catalog number of a release. type: string title: description: A title of a release. type: string artist: description: An artist of a release. type: string label: description: A label of a release. type: string description: description: A descriptive explanation of a release. type: string year: description: A year of a release. type: integer minimum: 1800 thumbnail: description: A thumbnail image of a release. type: string format: uri images: description: A list of images associated with a release. type: array items: $ref: '#/components/schemas/Image' stats: description: A type that represents statistical information about a release. type: object properties: community: description: A type that represents statistical information about a release provided by a community. type: object properties: in_collection: description: A total number of users in a community that have a release in their collection. type: integer minimum: 0 in_wantlist: description: A total number of users in a community that have a release in their wantlist. type: integer minimum: 0 required: - in_collection - in_wantlist required: - community required: - artist - catalog_number - description - images - label - thumbnail - stats - title - year ReleaseInstance: description: A type that represents an instance 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 ReleasePriceSuggestions: description: A type that represents a list of price suggestions of a release. type: object properties: "Mint (M)": description: A suggested price for a release in mint condition, if any. $ref: '#/components/schemas/Price' "Near Mint (NM or M-)": description: A suggested price for a release in near mint condition, if any. $ref: '#/components/schemas/Price' "Very Good Plus (VG+)": description: A suggested price for a release in very good + condition, if any. $ref: '#/components/schemas/Price' "Very Good (VG)": description: A suggested price for a release in very good condition, if any. $ref: '#/components/schemas/Price' "Good Plus (G+)": description: A suggested price for a release in good + condition, if any. $ref: '#/components/schemas/Price' "Good (G)": description: A suggested price for a release in good condition, if any. $ref: '#/components/schemas/Price' "Fair (F)": description: A suggested price for a release in fair condition, if any. $ref: '#/components/schemas/Price' "Poor (P)": description: A suggested price for a release in poor condition, if any. $ref: '#/components/schemas/Price' 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 ReleaseStatistics: description: A type that represents the statistics of a release. type: object properties: blocked_from_sale: description: A flag that indicates whether a release is blocked from sale in a marketplace or not. type: boolean num_for_sale: description: A number of items for sale in a marketplace. type: integer minimum: 0 lowest_price: description: A number for a lowest price of a release in a marketplace. $ref: '#/components/schemas/Price' required: - blocked_from_sale 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 statistics 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 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 Seller: description: A type that represents a user that sells inventory in a marketplace. allOf: - $ref: '#/components/schemas/UserId' - type: object properties: uid: description: An identifier of a user associated with a seller. type: integer minimum: 0 readOnly: true url: description: A URI related to a user. type: string format: uri avatar_url: description: An avatar URL of a user. type: string format: uri html_url: description: A URL to the website of a seller. type: string format: uri min_order_total: description: A minimum order total required by a seller. type: integer minimum: 0 payment: description: A payment type preferred by a seller. type: string shipping: description: An explanation of the shipping conditions of a seller. type: string stats: description: A type that represents the statistics associated with a seller. type: object properties: rating: description: A total percentage number of the ratings given to a seller. type: string maxLength: 5 pattern: '^\d{1,3}\.\d{1}$' stars: description: An average number of stars given to a seller. type: number format: float minimum: 0 maximum: 5 total: description: A total number of rating reviews given to a seller. type: integer minimum: 0 required: - rating - stars - total required: - avatar_url - html_url - min_order_total - payment - shipping - uid - url 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 sent 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 Shipping: description: A type that represents a shipping costs. allOf: - $ref: '#/components/schemas/Price' - type: object properties: currency: description: A currency chosen by a buyer. method: description: A shipping method chosen by a buyer. type: string value: description: A shipping value to be paid by a buyer. required: - method 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, if any. 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 interact 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 has in their collection. type: integer num_lists: description: A number of lists a user has created. type: integer num_pending: description: A number of items a user has in their pending list. type: integer num_for_sale: description: A number of items a user has for sale in the marketplace. type: integer num_wantlist: description: A number of items a user has in their wantlist, if any. type: integer rating_avg: description: An average rating to the total of releases that a user has rated. type: number format: float minimum: 0 maximum: 5 releases_contributed: description: A number of releases that a user has contributed information to. type: integer releases_rated: description: A number of releases that a user has rated. type: integer buyer_rating: description: An average rating a user has in the marketplace as a buyer. type: number format: float minimum: 0 maximum: 100 buyer_rating_stars: description: A number of star ratings a user has in the marketplace as a buyer. type: integer minimum: 0 maximum: 5 buyer_num_ratings: description: A total number of ratings a user has in the marketplace as a buyer. type: integer seller_rating: description: An average rating a user has in the marketplace as a seller. type: number format: float minimum: 0 maximum: 100 seller_rating_stars: description: A number of star ratings a user has in the marketplace as a seller. type: integer minimum: 0 maximum: 5 seller_num_ratings: description: A total number of ratings a user has 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 the 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 folders 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 wantlist 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