openapi: 3.1.1
info:
  title: Discogs API
  version: v2.0.0
  description: '# Overview

    The Discogs API v2.0 is a RESTful interface to Discogs data, allowing developers to build applications for web, desktop, and mobile devices. Access JSON-formatted information about Database objects
    like Artists, Releases, and Labels, and manage User Collections, Wantlists, and Marketplace Listings.


    For detailed documentation, please visit the [Official Discogs API Documentation](https://www.discogs.com/developers).


    ## 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.


    Your application **must** provide a unique `User-Agent` string with every request.


    ## Rate Limiting

    Requests are throttled by source IP.

    - **Authenticated Requests:** 60 requests per minute.

    - **Unauthenticated Requests:** 25 requests per minute.


    The API returns the following headers to help you track your usage:

    - `X-Discogs-Ratelimit`: Total requests allowed in the window.

    - `X-Discogs-Ratelimit-Used`: Requests you have made.

    - `X-Discogs-Ratelimit-Remaining`: Requests remaining.


    ## Data Licensing

    Some Discogs data is available under the [CC0 No Rights Reserved](http://creativecommons.org/about/cc0) license, while some is restricted. Use of the API is subject to the [API Terms of Use](https://support.discogs.com/hc/articles/360009334593-API-Terms-of-Use).

    '
  termsOfService: https://support.discogs.com/hc/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/articles/360009334593-API-Terms-of-Use
  x-logo:
    url: https://www.discogs.com/images/discogs-white.png
    backgroundColor: '#333333'
  x-providerName: discogs.com
  x-origin:
  - format: markdown
    url: https://www.discogs.com/developers
    version: v2.0
  x-generated-from: documentation
  x-last-validated: '2026-05-29'
externalDocs:
  description: Discogs Developers Portal
  url: https://www.discogs.com/developers
servers:
- url: https://api.discogs.com
  description: Production API Server
tags:
- name: Database
  description: 'Access Discogs database: artists, releases, masters, labels, and search.'
- name: Marketplace
  description: Marketplace listings, orders, fees, price suggestions, and release stats.
- name: User Identity
  description: Authenticated user identity, profile, 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: Browse and manage user-created lists of releases, artists, and labels.
- name: Inventory Management
  description: Bulk inventory export and CSV upload management.
- name: Image
  description: Image asset retrieval (proxied via OAuth).
paths:
  /artists/{artist_id}:
    get:
      tags:
      - Database
      summary: Discogs Get an Artist
      operationId: getArtist
      description: Retrieves details for a specific artist.
      parameters:
      - $ref: '#/components/parameters/ArtistId'
      responses:
        '200':
          description: Successfully retrieved artist details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artist'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artists/{artist_id}/releases:
    get:
      tags:
      - Database
      summary: Discogs Get Artist Releases
      operationId: getArtistReleases
      description: Returns a list of releases and masters associated with an artist. Supports pagination.
      parameters:
      - $ref: '#/components/parameters/ArtistId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/SortArtistReleases'
      - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: A paginated list of the artist's releases.
          headers:
            Link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  releases:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArtistRelease'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /database/search:
    get:
      tags:
      - Database
      summary: Discogs Search the Database
      operationId: searchDatabase
      description: 'Issue a search query to the Discogs database. This endpoint supports pagination and requires authentication.

        '
      parameters:
      - name: query
        in: query
        description: Your search query.
        schema:
          type: string
        example: The Cure
      - name: type
        in: query
        description: The type of resource to search for.
        schema:
          type: string
          enum:
          - release
          - master
          - artist
          - label
      - name: title
        in: query
        description: Search by combined "Artist Name - Release Title" field.
        schema:
          type: string
        example: The Cure - Disintegration
      - name: release_title
        in: query
        description: Search release titles.
        schema:
          type: string
        example: Disintegration
      - name: credit
        in: query
        description: Search release credits.
        schema:
          type: string
        example: Robert Smith
      - name: artist
        in: query
        description: Search artist names.
        schema:
          type: string
        example: The Cure
      - name: anv
        in: query
        description: Search an "Artist Name Variation" (ANV).
        schema:
          type: string
      - name: label
        in: query
        description: Search label names.
        schema:
          type: string
        example: Fiction Records
      - name: genre
        in: query
        description: Search genres.
        schema:
          type: string
        example: Rock
      - name: style
        in: query
        description: Search styles.
        schema:
          type: string
        example: Gothic Rock
      - name: country
        in: query
        description: Search release country.
        schema:
          type: string
        example: UK
      - name: year
        in: query
        description: Search release year.
        schema:
          type: string
        example: '1989'
      - name: format
        in: query
        description: Search formats.
        schema:
          type: string
        example: Vinyl
      - name: catno
        in: query
        description: Search catalog number.
        schema:
          type: string
        example: FIXH 14
      - name: barcode
        in: query
        description: Search barcodes.
        schema:
          type: string
        example: 042283923518
      - name: track
        in: query
        description: Search track titles.
        schema:
          type: string
        example: Lovesong
      - name: submitter
        in: query
        description: Search by submitter username.
        schema:
          type: string
      - name: contributor
        in: query
        description: Search by contributor username.
        schema:
          type: string
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      security:
      - DiscogsAuth: []
      responses:
        '200':
          description: Search results returned successfully.
          headers:
            Link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  results:
                    type: array
                    items:
                      oneOf:
                      - $ref: '#/components/schemas/SearchResultRelease'
                      - $ref: '#/components/schemas/SearchResultMaster'
                      - $ref: '#/components/schemas/SearchResultArtist'
                      - $ref: '#/components/schemas/SearchResultLabel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Internal Server Error. The query may be too complex or malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Timeout:
                  value:
                    message: Query time exceeded. Please try a simpler query.
                Malformed:
                  value:
                    message: An internal server error occurred. (Malformed query?)
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /images/{filename}:
    get:
      tags:
      - Image
      summary: Discogs Get Image
      operationId: getImage
      description: Return a binary image asset. Image URLs in API responses are proxied through this endpoint and require OAuth and a unique User-Agent.
      parameters:
      - name: filename
        in: path
        required: true
        description: Image filename, as returned by other endpoints.
        schema:
          type: string
        example: R-249504-1334592212.jpeg
      responses:
        '200':
          description: Image binary
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
      security:
      - OAuth1:
        - read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /inventory/export:
    get:
      tags:
      - Inventory Management
      summary: Discogs List Inventory Exports
      operationId: listInventoryExports
      description: List past inventory CSV export jobs for the authenticated user.
      parameters:
      - name: page
        in: query
        description: Page number.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        description: Items per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryExportsResponse'
      security:
      - OAuth1:
        - read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Inventory Management
      summary: Discogs Request Inventory Export
      operationId: requestInventoryExport
      description: Request an asynchronous CSV export of the authenticated user's inventory.
      responses:
        '201':
          description: Export job queued
      security:
      - OAuth1:
        - write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /inventory/export/{export_id}:
    get:
      tags:
      - Inventory Management
      summary: Discogs Get Inventory Export
      operationId: getInventoryExport
      description: Return details about a single inventory export job.
      parameters:
      - name: export_id
        in: path
        required: true
        description: Export job ID.
        schema:
          type: integer
        example: 599
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryExport'
      security:
      - OAuth1:
        - read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /inventory/export/{export_id}/download:
    get:
      tags:
      - Inventory Management
      summary: Discogs Download Inventory Export
      operationId: downloadInventoryExport
      description: Download the CSV file for a completed inventory export.
      parameters:
      - name: export_id
        in: path
        required: true
        description: Export job ID.
        schema:
          type: integer
        example: 599
      responses:
        '200':
          description: CSV file
          content:
            text/csv:
              schema:
                type: string
      security:
      - OAuth1:
        - read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /inventory/upload:
    get:
      tags:
      - Inventory Management
      summary: Discogs List Inventory Uploads
      operationId: listInventoryUploads
      description: List past CSV inventory upload jobs.
      parameters:
      - name: page
        in: query
        description: Page number.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        description: Items per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryUploadsResponse'
      security:
      - OAuth1:
        - read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /inventory/upload/add:
    post:
      tags:
      - Inventory Management
      summary: Discogs Add Inventory Upload
      operationId: addInventoryUpload
      description: Submit a CSV file to add inventory listings in bulk.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                upload:
                  type: string
                  format: binary
      responses:
        '201':
          description: Upload job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryUpload'
      security:
      - OAuth1:
        - write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /inventory/upload/change:
    post:
      tags:
      - Inventory Management
      summary: Discogs Change Inventory Upload
      operationId: changeInventoryUpload
      description: Submit a CSV file to update existing inventory listings in bulk.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                upload:
                  type: string
                  format: binary
      responses:
        '201':
          description: Upload job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryUpload'
      security:
      - OAuth1:
        - write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /inventory/upload/delete:
    post:
      tags:
      - Inventory Management
      summary: Discogs Delete Inventory Upload
      operationId: deleteInventoryUpload
      description: Submit a CSV file to delete inventory listings in bulk.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                upload:
                  type: string
                  format: binary
      responses:
        '201':
          description: Upload job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryUpload'
      security:
      - OAuth1:
        - write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /inventory/upload/{upload_id}:
    get:
      tags:
      - Inventory Management
      summary: Discogs Get Inventory Upload
      operationId: getInventoryUpload
      description: Return details about a single CSV inventory upload job.
      parameters:
      - name: upload_id
        in: path
        required: true
        description: Upload job ID.
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryUpload'
      security:
      - OAuth1:
        - read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /labels/{label_id}:
    get:
      tags:
      - Database
      summary: Discogs Get a Label
      operationId: getLabel
      description: Retrieves details for a specific label.
      parameters:
      - $ref: '#/components/parameters/LabelId'
      responses:
        '200':
          description: Successfully retrieved label details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /labels/{label_id}/releases:
    get:
      tags:
      - Database
      summary: Discogs Get All Label Releases
      operationId: getLabelReleases
      description: Returns a list of releases associated with a label. Supports pagination.
      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'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  releases:
                    type: array
                    items:
                      $ref: '#/components/schemas/LabelRelease'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /lists/{list_id}:
    get:
      tags:
      - User Lists
      summary: Discogs Get List
      operationId: getList
      description: Return a single user-created list, including all items.
      parameters:
      - name: list_id
        in: path
        required: true
        description: List ID.
        schema:
          type: integer
        example: 12345
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /marketplace/fee/{price}:
    get:
      tags:
      - Marketplace
      summary: Discogs Get Marketplace Fee
      operationId: getMarketplaceFee
      description: Return the Discogs marketplace fee for a transaction at a given price in USD.
      parameters:
      - name: price
        in: path
        required: true
        description: Transaction price in USD.
        schema:
          type: number
        example: 10.0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fee'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /marketplace/fee/{price}/{currency}:
    get:
      tags:
      - Marketplace
      summary: Discogs Get Marketplace Fee with Currency
      operationId: getMarketplaceFeeWithCurrency
      description: Return the Discogs marketplace fee for a transaction at a given price and currency.
      parameters:
      - name: price
        in: path
        required: true
        description: Transaction price.
        schema:
          type: number
        example: 10.0
      - name: currency
        in: path
        required: true
        description: ISO currency code.
        schema:
          type: string
          enum:
          - USD
          - GBP
          - EUR
          - CAD
          - AUD
          - JPY
          - CHF
          - MXN
          - BRL
          - NZD
          - SEK
          - ZAR
        example: EUR
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fee'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /marketplace/listings:
    post:
      tags:
      - Marketplace
      summary: Discogs Create a New Listing
      operationId: createListing
      description: Create a new Marketplace listing. The listing will be added to the authenticated user’s inventory.
      security:
      - DiscogsOAuth: []
        DiscogsTokenAuth: []
      requestBody:
        description: Details for the new listing.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListingNew'
      responses:
        '201':
          description: Listing successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  listing_id:
                    type: integer
                    description: The ID of the newly created listing.
                    example: 41578241
                  resource_url:
                    type: string
                    format: uri
                    description: The URL to the newly created listing resource.
                    example: https://api.discogs.com/marketplace/listings/41578241
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /marketplace/listings/{listing_id}:
    get:
      tags:
      - Marketplace
      summary: Discogs Get a Listing
      operationId: getListing
      description: View the data associated with a Marketplace listing.
      security:
      - DiscogsAuth: []
      parameters:
      - $ref: '#/components/parameters/ListingId'
      - name: curr_abbr
        in: query
        description: Currency for marketplace data.
        schema:
          $ref: '#/components/schemas/Currency'
      responses:
        '200':
          description: Successfully retrieved listing details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Listing'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Marketplace
      summary: Discogs Edit a Listing
      operationId: editListing
      description: 'Edit the data associated with a listing.

        Authentication as the listing owner is required.

        If the listing’s status is not `For Sale`, `Draft`, or `Expired`, it cannot be modified.

        '
      security:
      - DiscogsOAuth: []
        DiscogsTokenAuth: []
      parameters:
      - $ref: '#/components/parameters/ListingId'
      requestBody:
        description: Listing data to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListingUpdate'
      responses:
        '204':
          description: Listing was successfully updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - Marketplace
      summary: Discogs Delete a Listing
      operationId: deleteListing
      description: Permanently remove a listing from the Marketplace. Authentication as the listing owner is required.
      security:
      - DiscogsOAuth: []
        DiscogsTokenAuth: []
      parameters:
      - $ref: '#/components/parameters/ListingId'
      responses:
        '204':
          description: Listing was successfully deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /marketplace/orders:
    get:
      tags:
      - Marketplace
      summary: Discogs List Orders
      operationId: listOrders
      description: List marketplace orders for the authenticated seller.
      parameters:
      - name: status
        in: query
        description: Filter by order status.
        schema:
          type: string
          enum:
          - All
          - New Order
          - Buyer Contacted
          - Invoice Sent
          - Payment Pending
          - Payment Received
          - In Progress
          - Shipped
          - Refund Sent
          - Cancelled
      - name: created_after
        in: query
        description: Return orders created after this ISO 8601 datetime.
        schema:
          type: string
          format: date-time
      - name: created_before
        in: query
        description: Return orders created before this ISO 8601 datetime.
        schema:
          type: string
          format: date-time
      - name: archived
        in: query
        description: Whether to include archived orders.
        schema:
          type: boolean
      - name: sort
        in: query
        description: Sort field.
        schema:
          type: string
          enum:
          - id
          - buyer
          - created
          - status
          - last_activity
      - name: sort_order
        in: query
        description: Sort order.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: page
        in: query
        description: Page number.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        description: Items per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - OAuth1:
        - read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /marketplace/orders/{order_id}:
    get:
      tags:
      - Marketplace
      summary: Discogs Get Order
      operationId: getOrder
      description: Return a single marketplace order.
      parameters:
      - name: order_id
        in: path
        required: true
        description: Order ID (e.g. 1-1).
        schema:
          type: string
        example: 1-1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
      security:
      - OAuth1:
        - read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Marketplace
      summary: Discogs Update Order
      operationId: updateOrder
      description: Update marketplace order fields (status, shipping).
      parameters:
      - name: order_id
        in: path
        required: true
        description: Order ID.
        schema:
          type: string
        example: 1-1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  example: Shipped
                shipping:
                  type: number
                  example: 5.0
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
      security:
      - OAuth1:
        - write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /marketplace/orders/{order_id}/messages:
    get:
      tags:
      - Marketplace
      summary: Discogs List Order Messages
      operationId: listOrderMessages
      description: List messages exchanged on a marketplace order.
      parameters:
      - name: order_id
        in: path
        required: true
        description: Order ID.
        schema:
          type: string
        example: 1-1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderMessagesResponse'
      security:
      - OAuth1:
        - read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Marketplace
      summary: Discogs Add Order Message
      operationId: addOrderMessage
      description: Post a new message on a marketplace order.
      parameters:
      - name: order_id
        in: path
        required: true
        description: Order ID.
        schema:
          type: string
        example: 1-1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  example: Your order has shipped.
                status:
                  type: string
                  example: Shipped
      responses:
        '201':
          description: Message added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderMessage'
      security:
      - OAuth1:
        - write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /marketplace/price_suggestions/{release_id}:
    get:
      tags:
      - Marketplace
      summary: Discogs Get Price Suggestions
      operationId: getPriceSuggestions
      description: Return suggested marketplace prices for a release across all media conditions.
      parameters:
      - name: release_id
        in: path
        required: true
        description: Release ID.
        schema:
          type: integer
        example: 249504
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceSuggestionsResponse'
      security:
      - OAuth1:
        - read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /masters/{master_id}:
    get:
      tags:
      - Database
      summary: Discogs Get a Master Release
      operationId: getMasterRelease
      description: Retrieves details for a specific master release. A master release represents a set of similar releases.
      parameters:
      - $ref: '#/components/parameters/MasterId'
      responses:
        '200':
          description: Successfully retrieved master release details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Master'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /masters/{master_id}/versions:
    get:
      tags:
      - Database
      summary: Discogs Get Master Release Versions
      operationId: getMasterReleaseVersions
      description: Retrieves a list of all releases that are versions of the specified master release. Supports pagination.
      parameters:
      - $ref: '#/components/parameters/MasterId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/FormatFilter'
      - $ref: '#/components/parameters/LabelFilter'
      - $ref: '#/components/parameters/ReleasedFilter'
      - $ref: '#/components/parameters/CountryFilter'
      - $ref: '#/components/parameters/SortMasterVersions'
      - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: A paginated list of releases belonging to the master.
          headers:
            Link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  versions:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReleaseVersion'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /oauth/identity:
    get:
      tags:
      - User Identity
      summary: Discogs Get User Identity
      operationId: getUserIdentity
      description: 'Retrieve basic information about the authenticated user.

        This endpoint is useful for verifying that OAuth authentication is working correctly.

        '
      security:
      - DiscogsOAuth: []
        DiscogsTokenAuth: []
      responses:
        '200':
          description: Successfully retrieved identity information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identity'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /releases/{release_id}:
    get:
      tags:
      - Database
      summary: Discogs Get a Release
      operationId: getRelease
      description: Retrieves details for a specific release.
      parameters:
      - $ref: '#/components/parameters/ReleaseId'
      - name: curr_abbr
        in: query
        description: Currency for marketplace data.
        schema:
          $ref: '#/components/schemas/Currency'
      responses:
        '200':
          description: Successfully retrieved release details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Release'
              example:
                id: 249504
                status: Accepted
                year: 1987
                resource_url: https://api.discogs.com/releases/249504
                uri: https://www.discogs.com/Rick-Astley-Never-Gonna-Give-You-Up/release/249504
                artists:
                - id: 72872
                  name: Rick Astley
                  resource_url: https://api.discogs.com/artists/72872
                title: Never Gonna Give You Up
                country: UK
                released: '1987'
                notes: UK Release has a black label...
                genres:
                - Electronic
                - Pop
                styles:
                - Synth-pop
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /releases/{release_id}/rating:
    get:
      tags:
      - Database
      summary: Discogs Get Release Community Rating
      operationId: getReleaseCommunityRating
      description: Return the aggregate community rating for a release.
      parameters:
      - name: release_id
        in: path
        required: true
        description: Release ID.
        schema:
          type: integer
        example: 249504
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseRating'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /releases/{release_id}/rating/{username}:
    get:
      tags:
      - Database
      summary: Discogs Get Release Rating by User
      operationId: getReleaseRatingByUser
      description: Return a user's rating of a release.
      parameters:
      - name: release_id
        in: path
        required: true
        description: Release ID.
        schema:
          type: integer
        example: 249504
      - name: username
        in: path
        required: true
        description: Discogs username.
        schema:
          type: string
        example: memory
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserReleaseRating'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Database
      summary: Discogs Update Release Rating by User
      operationId: updateReleaseRatingByUser
      description: Set or update the authenticated user's release rating.
      parameters:
      - name: release_id
        in: path
        required: true
        description: Release ID.
        schema:
          type: integer
        example: 249504
      - name: username
        in: path
        required: true
        description: Discogs username.
        schema:
          type: string
        example: memory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rating:
                  type: integer
                  minimum: 0
                  maximum: 5
                  example: 5
      responses:
        '201':
          description: Rating saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserReleaseRating'
      security:
      - OAuth1:
        - write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - Database
      summary: Discogs Delete Release Rating by User
      operationId: deleteReleaseRatingByUser
      description: Remove a release rating for the authenticated user.
      parameters:
      - name: release_id
        in: path
        required: true
        description: Release ID.
        schema:
          type: integer
        example: 249504
      - name: username
        in: path
        required: true
        description: Discogs username.
        schema:
          type: string
        example: memory
      responses:
        '204':
          description: Rating deleted
      security:
      - OAuth1:
        - write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /releases/{release_id}/stats:
    get:
      tags:
      - Marketplace
      summary: Discogs Get Release Marketplace Stats
      operationId: getReleaseStats
      description: Return marketplace statistics (lowest price, copies for sale) for a release.
      parameters:
      - name: release_id
        in: path
        required: true
        description: Release ID.
        schema:
          type: integer
        example: 249504
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseStats'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{username}:
    get:
      tags:
      - User Identity
      summary: Discogs Get a User Profile
      operationId: getUserProfile
      description: Retrieve public profile information for a Discogs user.
      security:
      - DiscogsAuth: []
      parameters:
      - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Successfully retrieved user profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - User Identity
      summary: Discogs Update User Profile
      operationId: updateUserProfile
      description: Update the authenticated user's profile fields.
      parameters:
      - name: username
        in: path
        required: true
        description: Discogs username.
        schema:
          type: string
        example: rodneyfool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileUpdate'
      responses:
        '200':
          description: Profile updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - OAuth1:
        - write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{username}/collection/folders:
    get:
      tags:
      - User Collection
      summary: Discogs Get Collection Folders
      operationId: getCollectionFolders
      description: 'Retrieve a list of folders in a user’s collection.

        If the collection is private, authentication as the owner is required.

        If not authenticated as the owner, only the "All" folder (ID 0) is returned for public collections.

        '
      security:
      - DiscogsAuth: []
      parameters:
      - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: A list of collection folders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  folders:
                    type: array
                    items:
                      $ref: '#/components/schemas/CollectionFolder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - User Collection
      summary: Discogs Create a Collection Folder
      operationId: createCollectionFolder
      description: Create a new folder in a user’s collection. Authentication as the owner is required.
      security:
      - DiscogsOAuth: []
        DiscogsTokenAuth: []
      parameters:
      - $ref: '#/components/parameters/Username'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the new folder.
                  example: My Favorites
      responses:
        '201':
          description: Folder created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionFolder'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{username}/collection/folders/{folder_id}/releases:
    get:
      tags:
      - User Collection
      summary: Discogs Get Collection Items by Folder
      operationId: getCollectionItemsByFolder
      description: 'Returns the list of items in a folder in a user’s collection. Accepts pagination.

        If `folder_id` is not 0 or the collection is private, authentication as the collection owner is required.

        '
      security:
      - DiscogsAuth: []
      parameters:
      - $ref: '#/components/parameters/Username'
      - $ref: '#/components/parameters/FolderId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/SortCollection'
      - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: A paginated list of releases in the folder.
          headers:
            Link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  releases:
                    type: array
                    items:
                      $ref: '#/components/schemas/CollectionRelease'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{username}/collection/folders/{folder_id}/releases/{release_id}:
    post:
      tags:
      - User Collection
      summary: Discogs Add Release to Collection Folder
      operationId: addReleaseToCollectionFolder
      description: 'Add a release to a folder in a user''s collection.

        `folder_id` must be non-zero (use `1` for "Uncategorized").

        Authentication as the collection owner is required.

        '
      security:
      - DiscogsOAuth: []
        DiscogsTokenAuth: []
      parameters:
      - $ref: '#/components/parameters/Username'
      - $ref: '#/components/parameters/FolderId'
      - $ref: '#/components/parameters/ReleaseId'
      responses:
        '201':
          description: Release added to collection successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  instance_id:
                    type: integer
                    description: The new instance ID for this release in the collection.
                    example: 148842233
                  resource_url:
                    type: string
                    format: uri
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{username}/contributions:
    get:
      tags:
      - User Identity
      summary: Discogs Get User Contributions
      operationId: getUserContributions
      description: List all releases a user has contributed to.
      parameters:
      - name: username
        in: path
        required: true
        description: Discogs username.
        schema:
          type: string
        example: shooezgirl
      - name: page
        in: query
        description: Page number.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        description: Items per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: sort
        in: query
        description: Sort field.
        schema:
          type: string
          enum:
          - label
          - artist
          - title
          - catno
          - format
          - rating
          - year
          - added
      - name: sort_order
        in: query
        description: Sort order.
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contribution'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{username}/inventory:
    get:
      tags:
      - Marketplace
      summary: Discogs Get User Inventory
      operationId: getUserInventory
      description: 'Returns the list of listings in a user’s inventory. Supports pagination.

        If you are not authenticated as the inventory owner, only items that have a status of "For Sale" will be visible.

        '
      security:
      - DiscogsAuth: []
      parameters:
      - $ref: '#/components/parameters/Username'
      - name: status
        in: query
        description: Only show items with this status.
        schema:
          type: string
          enum:
          - For Sale
          - All
          - Draft
          - Expired
          - Sold
          - Violation
          - Suspended
          - Deleted
          default: For Sale
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - name: sort
        in: query
        description: Sort items by this field.
        schema:
          type: string
          enum:
          - listed
          - price
          - item
          - artist
          - label
          - catno
          - audio
          - status
          - location
          default: listed
      - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: A paginated list of inventory listings.
          headers:
            Link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  listings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Listing'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{username}/lists:
    get:
      tags:
      - User Lists
      summary: Discogs Get User Lists
      operationId: getUserLists
      description: Return a paginated list of user-created lists.
      parameters:
      - name: username
        in: path
        required: true
        description: Discogs username.
        schema:
          type: string
        example: rodneyfool
      - name: page
        in: query
        description: Page number.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        description: Items per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListsResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{username}/submissions:
    get:
      tags:
      - User Identity
      summary: Discogs Get User Submissions
      operationId: getUserSubmissions
      description: List all submissions (artist/label/release edits) by a user.
      parameters:
      - name: username
        in: path
        required: true
        description: Discogs username.
        schema:
          type: string
        example: shooezgirl
      - name: page
        in: query
        description: Page number.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        description: Items per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{username}/wants:
    get:
      tags:
      - User Wantlist
      summary: Discogs Get User Wantlist
      operationId: getUserWantlist
      description: 'Returns the list of releases in a user''s wantlist. Supports pagination.

        If the wantlist is private, authentication as the owner is required.

        '
      security:
      - DiscogsAuth: []
      parameters:
      - $ref: '#/components/parameters/Username'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of releases in the wantlist.
          headers:
            Link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  wants:
                    type: array
                    items:
                      $ref: '#/components/schemas/Want'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{username}/wants/{release_id}:
    put:
      tags:
      - User Wantlist
      summary: Discogs Add Release to Wantlist
      operationId: addReleaseToWantlist
      description: Add a release to a user's wantlist. Authentication as the owner is required.
      security:
      - DiscogsOAuth: []
        DiscogsTokenAuth: []
      parameters:
      - $ref: '#/components/parameters/Username'
      - $ref: '#/components/parameters/ReleaseId'
      requestBody:
        description: Optional notes and rating for the wantlist item.
        content:
          application/json:
            schema:
              type: object
              properties:
                notes:
                  type: string
                  description: User notes for this item.
                rating:
                  type: integer
                  description: User's rating for the release (0-5).
                  minimum: 0
                  maximum: 5
                  default: 0
      responses:
        '201':
          description: Release added to wantlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Want'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - User Wantlist
      summary: Discogs Delete Release from Wantlist
      operationId: deleteReleaseFromWantlist
      description: Delete a release from a user's wantlist. Authentication as the owner is required.
      security:
      - DiscogsOAuth: []
        DiscogsTokenAuth: []
      parameters:
      - $ref: '#/components/parameters/Username'
      - $ref: '#/components/parameters/ReleaseId'
      responses:
        '204':
          description: Release successfully deleted from wantlist.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Release:
      type: object
      description: Represents a particular physical or digital object released by one or more Artists.
      properties:
        id:
          type: integer
          readOnly: true
        title:
          type: string
        resource_url:
          type: string
          format: uri
          readOnly: true
        uri:
          type: string
          format: uri
          readOnly: true
        status:
          type: string
        data_quality:
          type: string
        thumb:
          type: string
          format: uri
        country:
          type: string
          nullable: true
        year:
          type: integer
          nullable: true
        notes:
          type: string
          nullable: true
        released:
          type: string
          description: Release date in a free-text format.
        released_formatted:
          type: string
          description: Formatted release date.
        date_added:
          type: string
          format: date-time
        date_changed:
          type: string
          format: date-time
        lowest_price:
          type: number
          format: float
          nullable: true
        num_for_sale:
          type: integer
          nullable: true
        estimated_weight:
          type: integer
          nullable: true
        format_quantity:
          type: integer
        master_id:
          type: integer
          nullable: true
        master_url:
          type: string
          format: uri
          nullable: true
        artists:
          type: array
          items:
            $ref: '#/components/schemas/ArtistSummary'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/LabelSummary'
        extraartists:
          type: array
          items:
            $ref: '#/components/schemas/ArtistSummary'
        formats:
          type: array
          items:
            $ref: '#/components/schemas/ReleaseFormat'
        genres:
          type: array
          items:
            type: string
        styles:
          type: array
          items:
            type: string
        community:
          $ref: '#/components/schemas/Community'
        companies:
          type: array
          items:
            $ref: '#/components/schemas/LabelSummary'
        tracklist:
          type: array
          items:
            $ref: '#/components/schemas/Track'
        videos:
          type: array
          items:
            $ref: '#/components/schemas/Video'
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
    Artist:
      type: object
      description: Represents a person or group in the Discogs database.
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        realname:
          type: string
          nullable: true
        resource_url:
          type: string
          format: uri
          readOnly: true
        uri:
          type: string
          format: uri
          readOnly: true
        releases_url:
          type: string
          format: uri
        profile:
          type: string
          nullable: true
        urls:
          type: array
          items:
            type: string
            format: uri
        namevariations:
          type: array
          items:
            type: string
        members:
          type: array
          items:
            $ref: '#/components/schemas/ArtistSummary'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        data_quality:
          type: string
    Label:
      type: object
      description: Represents a label, company, recording studio, etc.
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        resource_url:
          type: string
          format: uri
          readOnly: true
        uri:
          type: string
          format: uri
          readOnly: true
        releases_url:
          type: string
          format: uri
        profile:
          type: string
          nullable: true
        contact_info:
          type: string
          nullable: true
        parent_label:
          $ref: '#/components/schemas/LabelSummary'
          nullable: true
        sublabels:
          type: array
          items:
            $ref: '#/components/schemas/LabelSummary'
        urls:
          type: array
          items:
            type: string
            format: uri
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        data_quality:
          type: string
    Master:
      type: object
      description: Represents a set of similar Releases.
      allOf:
      - $ref: '#/components/schemas/Release'
      - type: object
        properties:
          main_release:
            type: integer
            description: The ID of the main release for this master.
          main_release_url:
            type: string
            format: uri
          versions_url:
            type: string
            format: uri
    ReleaseVersion:
      type: object
      properties:
        id:
          type: integer
        resource_url:
          type: string
          format: uri
        status:
          type: string
        thumb:
          type: string
          format: uri
        format:
          type: string
        country:
          type: string
          nullable: true
        title:
          type: string
        label:
          type: string
        released:
          type: string
        major_formats:
          type: array
          items:
            type: string
        catno:
          type: string
          nullable: true
        stats:
          type: object
          properties:
            community:
              type: object
              properties:
                in_collection:
                  type: integer
                in_wantlist:
                  type: integer
    ArtistRelease:
      type: object
      properties:
        id:
          type: integer
        resource_url:
          type: string
          format: uri
        type:
          type: string
          enum:
          - release
          - master
        title:
          type: string
        thumb:
          type: string
          format: uri
        artist:
          type: string
        role:
          type: string
        year:
          type: integer
          nullable: true
        format:
          type: string
          nullable: true
        label:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
    LabelRelease:
      type: object
      properties:
        id:
          type: integer
        resource_url:
          type: string
          format: uri
        thumb:
          type: string
          format: uri
        artist:
          type: string
        title:
          type: string
        format:
          type: string
        catno:
          type: string
        status:
          type: string
        year:
          type: integer
    Listing:
      type: object
      description: A Marketplace listing.
      properties:
        id:
          type: integer
          readOnly: true
        resource_url:
          type: string
          format: uri
          readOnly: true
        uri:
          type: string
          format: uri
          readOnly: true
        status:
          type: string
          enum:
          - For Sale
          - Sold
          - Draft
          - Expired
        price:
          $ref: '#/components/schemas/Price'
        allow_offers:
          type: boolean
        sleeve_condition:
          $ref: '#/components/schemas/SleeveCondition'
        condition:
          $ref: '#/components/schemas/MediaCondition'
        posted:
          type: string
          format: date-time
        ships_from:
          type: string
        comments:
          type: string
        seller:
          $ref: '#/components/schemas/UserSummary'
        release:
          $ref: '#/components/schemas/ListingRelease'
        audio:
          type: boolean
        weight:
          type: integer
          description: The weight of the item in grams.
        format_quantity:
          type: integer
          description: How many units this item counts as for shipping.
        external_id:
          type: string
          nullable: true
          description: Private comments for the seller.
        location:
          type: string
          nullable: true
          description: Physical location of the item.
    ListingNew:
      type: object
      description: Data for creating a new listing.
      required:
      - release_id
      - condition
      - price
      - status
      properties:
        release_id:
          type: integer
          description: The ID of the release.
        condition:
          $ref: '#/components/schemas/MediaCondition'
        sleeve_condition:
          $ref: '#/components/schemas/SleeveCondition'
        price:
          type: number
          format: float
          description: The price of the item in the seller's currency.
        comments:
          type: string
          description: Any remarks about the item.
        allow_offers:
          type: boolean
          default: false
        status:
          type: string
          description: The status of the listing.
          enum:
          - For Sale
          - Draft
          default: For Sale
        external_id:
          type: string
          description: Private comments for the seller.
        location:
          type: string
          description: Physical location of the item.
        weight:
          type: integer
          description: The weight in grams.
        format_quantity:
          type: integer
          description: How many units this item counts as for shipping.
    ListingUpdate:
      type: object
      description: Data for updating a listing.
      allOf:
      - $ref: '#/components/schemas/ListingNew'
    ListingRelease:
      type: object
      description: Summary of a release within a listing.
      properties:
        id:
          type: integer
        resource_url:
          type: string
          format: uri
        description:
          type: string
        thumbnail:
          type: string
          format: uri
        artist:
          type: string
        title:
          type: string
        year:
          type: integer
        format:
          type: string
        catalog_number:
          type: string
    Pagination:
      type: object
      description: Details for paginated results.
      properties:
        page:
          type: integer
        pages:
          type: integer
        per_page:
          type: integer
        items:
          type: integer
        urls:
          type: object
          properties:
            first:
              type: string
              format: uri
              nullable: true
            prev:
              type: string
              format: uri
              nullable: true
            next:
              type: string
              format: uri
              nullable: true
            last:
              type: string
              format: uri
              nullable: true
    Identity:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        resource_url:
          type: string
          format: uri
        consumer_name:
          type: string
    Profile:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        username:
          type: string
        resource_url:
          type: string
          format: uri
          readOnly: true
        uri:
          type: string
          format: uri
          readOnly: true
        name:
          type: string
          nullable: true
        home_page:
          type: string
          format: uri
          nullable: true
        location:
          type: string
          nullable: true
        profile:
          type: string
          nullable: true
        registered:
          type: string
          format: date-time
        rank:
          type: number
          format: float
        num_pending:
          type: integer
        num_for_sale:
          type: integer
        num_collection:
          type: integer
        num_wantlist:
          type: integer
        num_lists:
          type: integer
        releases_contributed:
          type: integer
        releases_rated:
          type: integer
        rating_avg:
          type: number
          format: float
        inventory_url:
          type: string
          format: uri
        collection_folders_url:
          type: string
          format: uri
        collection_fields_url:
          type: string
          format: uri
        wantlist_url:
          type: string
          format: uri
        avatar_url:
          type: string
          format: uri
        banner_url:
          type: string
          format: uri
          nullable: true
        curr_abbr:
          $ref: '#/components/schemas/Currency'
        seller_rating:
          type: number
          format: float
        seller_num_ratings:
          type: integer
        buyer_rating:
          type: number
          format: float
        buyer_num_ratings:
          type: integer
        email:
          type: string
          format: email
    CollectionFolder:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        count:
          type: integer
        resource_url:
          type: string
          format: uri
    CollectionRelease:
      type: object
      properties:
        id:
          type: integer
        instance_id:
          type: integer
        folder_id:
          type: integer
        rating:
          type: integer
        date_added:
          type: string
          format: date-time
        basic_information:
          $ref: '#/components/schemas/ReleaseSummary'
    Want:
      type: object
      properties:
        id:
          type: integer
        resource_url:
          type: string
          format: uri
        rating:
          type: integer
        notes:
          type: string
          nullable: true
        basic_information:
          $ref: '#/components/schemas/ReleaseSummary'
    ArtistSummary:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        resource_url:
          type: string
          format: uri
        anv:
          type: string
          nullable: true
        join:
          type: string
          nullable: true
        role:
          type: string
          nullable: true
        tracks:
          type: string
          nullable: true
    LabelSummary:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        resource_url:
          type: string
          format: uri
        catno:
          type: string
          nullable: true
        entity_type:
          type: string
          nullable: true
    UserSummary:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        resource_url:
          type: string
          format: uri
    ReleaseSummary:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        year:
          type: integer
        resource_url:
          type: string
          format: uri
        thumb:
          type: string
          format: uri
        cover_image:
          type: string
          format: uri
        formats:
          type: array
          items:
            $ref: '#/components/schemas/ReleaseFormat'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/LabelSummary'
        artists:
          type: array
          items:
            $ref: '#/components/schemas/ArtistSummary'
        genres:
          type: array
          items:
            type: string
        styles:
          type: array
          items:
            type: string
    ReleaseFormat:
      type: object
      properties:
        name:
          type: string
        qty:
          type: string
        text:
          type: string
          nullable: true
        descriptions:
          type: array
          items:
            type: string
    Community:
      type: object
      properties:
        have:
          type: integer
        want:
          type: integer
        rating:
          type: object
          properties:
            count:
              type: integer
            average:
              type: number
              format: float
        submitter:
          $ref: '#/components/schemas/UserSummary'
        contributors:
          type: array
          items:
            $ref: '#/components/schemas/UserSummary'
        data_quality:
          type: string
        status:
          type: string
    Image:
      type: object
      properties:
        type:
          type: string
          enum:
          - primary
          - secondary
        uri:
          type: string
          format: uri
        resource_url:
          type: string
          format: uri
        uri150:
          type: string
          format: uri
        width:
          type: integer
        height:
          type: integer
    Video:
      type: object
      properties:
        uri:
          type: string
          format: uri
        duration:
          type: integer
        title:
          type: string
        description:
          type: string
        embed:
          type: boolean
    Track:
      type: object
      properties:
        position:
          type: string
        type_:
          type: string
        title:
          type: string
        duration:
          type: string
        extraartists:
          type: array
          items:
            $ref: '#/components/schemas/ArtistSummary'
    Identifier:
      type: object
      properties:
        type:
          type: string
        value:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
    Price:
      type: object
      properties:
        currency:
          type: string
        value:
          type: number
          format: float
    Currency:
      type: string
      enum:
      - USD
      - GBP
      - EUR
      - CAD
      - AUD
      - JPY
      - CHF
      - MXN
      - BRL
      - NZD
      - SEK
      - ZAR
    MediaCondition:
      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)
    SleeveCondition:
      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
    SearchResultRelease:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
          - release
        title:
          type: string
        thumb:
          type: string
          format: uri
        cover_image:
          type: string
          format: uri
        resource_url:
          type: string
          format: uri
        uri:
          type: string
        country:
          type: string
        year:
          type: string
        format:
          type: array
          items:
            type: string
        label:
          type: array
          items:
            type: string
        catno:
          type: string
        genre:
          type: array
          items:
            type: string
        style:
          type: array
          items:
            type: string
        barcode:
          type: array
          items:
            type: string
    SearchResultMaster:
      allOf:
      - $ref: '#/components/schemas/SearchResultRelease'
      - type: object
        properties:
          type:
            enum:
            - master
          main_release:
            type: integer
    SearchResultArtist:
      allOf:
      - $ref: '#/components/schemas/SearchResultRelease'
      - type: object
        properties:
          type:
            enum:
            - artist
    SearchResultLabel:
      allOf:
      - $ref: '#/components/schemas/SearchResultRelease'
      - type: object
        properties:
          type:
            enum:
            - label
    Error:
      type: object
      properties:
        message:
          type: string
    List:
      type: object
      description: A user-created list of releases, masters, artists, or labels.
      properties:
        id:
          type: integer
          example: 12345
        name:
          type: string
          example: Best Jazz Albums of 1960s
        description:
          type: string
          example: My personal favorites.
        public:
          type: boolean
          example: true
        date_added:
          type: string
          format: date-time
          example: '2026-05-29T12:00:00Z'
        date_changed:
          type: string
          format: date-time
          example: '2026-05-29T12:00:00Z'
        uri:
          type: string
          format: uri
          example: https://www.discogs.com/lists/12345
        resource_url:
          type: string
          format: uri
        image_url:
          type: string
          format: uri
        user:
          $ref: '#/components/schemas/UserSummary'
        items:
          type: array
          items:
            $ref: '#/components/schemas/ListItem'
    ListItem:
      type: object
      description: A single item inside a user list.
      properties:
        id:
          type: integer
          example: 4567
        type:
          type: string
          enum:
          - release
          - master
          - artist
          - label
          example: release
        display_title:
          type: string
          example: Miles Davis — Kind Of Blue
        uri:
          type: string
          format: uri
        comment:
          type: string
        image_url:
          type: string
          format: uri
        resource_url:
          type: string
          format: uri
    ListsResponse:
      type: object
      description: Paginated response of a user's lists.
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        lists:
          type: array
          items:
            $ref: '#/components/schemas/List'
    Submission:
      type: object
      description: A submission (release/artist/label edit) made by a user.
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        submissions:
          type: object
          properties:
            artists:
              type: array
              items:
                $ref: '#/components/schemas/ArtistSummary'
            labels:
              type: array
              items:
                $ref: '#/components/schemas/LabelSummary'
            releases:
              type: array
              items:
                $ref: '#/components/schemas/ReleaseSummary'
    Contribution:
      type: object
      description: A user's contribution to the Discogs database.
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        contributions:
          type: array
          items:
            $ref: '#/components/schemas/ReleaseSummary'
    Order:
      type: object
      description: A marketplace order.
      properties:
        id:
          type: string
          example: 1-1
        resource_url:
          type: string
          format: uri
        status:
          type: string
          example: Payment Received
        next_status:
          type: array
          items:
            type: string
        fee:
          $ref: '#/components/schemas/Price'
        created:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: '#/components/schemas/Listing'
        shipping:
          $ref: '#/components/schemas/Price'
        shipping_address:
          type: string
        additional_instructions:
          type: string
        archived:
          type: boolean
        seller:
          $ref: '#/components/schemas/UserSummary'
        buyer:
          $ref: '#/components/schemas/UserSummary'
        total:
          $ref: '#/components/schemas/Price'
        messages_url:
          type: string
          format: uri
        uri:
          type: string
          format: uri
        last_activity:
          type: string
          format: date-time
    OrdersResponse:
      type: object
      description: Paginated marketplace orders for the authenticated seller.
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    OrderMessage:
      type: object
      description: A message attached to a marketplace order.
      properties:
        refund:
          type: object
          properties:
            amount:
              type: number
            order:
              type: object
        timestamp:
          type: string
          format: date-time
        message:
          type: string
        type:
          type: string
          enum:
          - message
          - status
          - shipping
        order:
          type: object
          properties:
            resource_url:
              type: string
            id:
              type: string
        subject:
          type: string
        from:
          $ref: '#/components/schemas/UserSummary'
    OrderMessagesResponse:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/OrderMessage'
    Fee:
      type: object
      description: Calculated Discogs marketplace fee for a transaction.
      properties:
        value:
          type: number
          example: 0.42
        currency:
          $ref: '#/components/schemas/Currency'
    PriceSuggestion:
      type: object
      description: Suggested marketplace price for a release at a given media condition.
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
        value:
          type: number
          example: 19.99
    PriceSuggestionsResponse:
      type: object
      description: Suggested prices for a release across all standard media conditions.
      additionalProperties:
        $ref: '#/components/schemas/PriceSuggestion'
    ReleaseStats:
      type: object
      description: Marketplace statistics for a release.
      properties:
        lowest_price:
          $ref: '#/components/schemas/Price'
        num_for_sale:
          type: integer
          example: 47
        blocked_from_sale:
          type: boolean
          example: false
    ReleaseRating:
      type: object
      description: Aggregate community rating for a release.
      properties:
        release_id:
          type: integer
          example: 249504
        rating:
          type: object
          properties:
            count:
              type: integer
            average:
              type: number
    UserReleaseRating:
      type: object
      description: A user's own rating for a release.
      properties:
        username:
          type: string
          example: jsmith
        release:
          type: integer
          example: 249504
        rating:
          type: integer
          minimum: 0
          maximum: 5
          example: 5
    ProfileUpdate:
      type: object
      description: Editable profile fields.
      properties:
        name:
          type: string
        home_page:
          type: string
        location:
          type: string
        profile:
          type: string
        curr_abbr:
          type: string
          enum:
          - USD
          - GBP
          - EUR
          - CAD
          - AUD
          - JPY
          - CHF
          - MXN
          - BRL
          - NZD
          - SEK
          - ZAR
    InventoryExport:
      type: object
      description: A marketplace inventory CSV export job.
      properties:
        status:
          type: string
          enum:
          - pending
          - in progress
          - success
          - failure
        created_ts:
          type: string
          format: date-time
        url:
          type: string
          format: uri
        finished_ts:
          type: string
          format: date-time
        download_url:
          type: string
          format: uri
        filename:
          type: string
          example: inventory-export.csv
        id:
          type: integer
          example: 599
        type:
          type: string
          example: export
    InventoryExportsResponse:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        items:
          type: array
          items:
            $ref: '#/components/schemas/InventoryExport'
    InventoryUpload:
      type: object
      description: A CSV inventory upload job.
      properties:
        status:
          type: string
          enum:
          - pending
          - processing
          - success
          - failure
          - partial_success
        created_ts:
          type: string
          format: date-time
        last_activity:
          type: string
          format: date-time
        type:
          type: string
          enum:
          - add
          - change
          - delete
        id:
          type: integer
        filename:
          type: string
        results_url:
          type: string
          format: uri
    InventoryUploadsResponse:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        items:
          type: array
          items:
            $ref: '#/components/schemas/InventoryUpload'
  parameters:
    Username:
      name: username
      in: path
      required: true
      description: The user's Discogs username.
      schema:
        type: string
      example: rodneyfool
    ReleaseId:
      name: release_id
      in: path
      required: true
      description: The ID of the release.
      schema:
        type: integer
      example: 249504
    MasterId:
      name: master_id
      in: path
      required: true
      description: The ID of the master release.
      schema:
        type: integer
      example: 1000
    ArtistId:
      name: artist_id
      in: path
      required: true
      description: The ID of the artist.
      schema:
        type: integer
      example: 108713
    LabelId:
      name: label_id
      in: path
      required: true
      description: The ID of the label.
      schema:
        type: integer
      example: 1
    ListingId:
      name: listing_id
      in: path
      required: true
      description: The ID of the marketplace listing.
      schema:
        type: integer
      example: 172723812
    FolderId:
      name: folder_id
      in: path
      required: true
      description: The ID of the collection folder.
      schema:
        type: integer
      example: 1
    Page:
      name: page
      in: query
      description: The page number to return.
      schema:
        type: integer
        default: 1
        minimum: 1
    PerPage:
      name: per_page
      in: query
      description: The number of items to return per page.
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 100
    SortOrder:
      name: sort_order
      in: query
      description: The order to sort the results.
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
    SortMasterVersions:
      name: sort
      in: query
      description: The field to sort the results by.
      schema:
        type: string
        enum:
        - released
        - title
        - format
        - label
        - catno
        - country
        default: released
    SortArtistReleases:
      name: sort
      in: query
      description: The field to sort the results by.
      schema:
        type: string
        enum:
        - year
        - title
        - format
        default: year
    SortCollection:
      name: sort
      in: query
      description: The field to sort the results by.
      schema:
        type: string
        enum:
        - label
        - artist
        - title
        - catno
        - format
        - rating
        - added
        - year
        default: added
    FormatFilter:
      name: format
      in: query
      description: Filter by format.
      schema:
        type: string
    LabelFilter:
      name: label
      in: query
      description: Filter by label.
      schema:
        type: string
    ReleasedFilter:
      name: released
      in: query
      description: Filter by release year.
      schema:
        type: string
    CountryFilter:
      name: country
      in: query
      description: Filter by country.
      schema:
        type: string
  headers:
    Link:
      description: 'Contains URLs for pagination, compliant with RFC 5988. It provides `first`, `prev`, `next`, and `last` links where applicable.

        '
      schema:
        type: string
        example: <https://api.discogs.com/artists/1/releases?page=2&per_page=75>; rel="next", <https://api.discogs.com/artists/1/releases?page=30&per_page=75>; rel="last"
  responses:
    Unauthorized:
      description: Unauthorized. Authentication information is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: You must authenticate to access this resource.
    Forbidden:
      description: Forbidden. You do not have permission to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: You don't have permission to access this resource.
    NotFound:
      description: Not Found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Resource not found.
  securitySchemes:
    DiscogsToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'Discogs personal access token in header: ''Discogs token={token}''.'
    DiscogsKeySecret:
      type: apiKey
      in: header
      name: Authorization
      description: 'Discogs consumer key + secret in header: ''Discogs key={key}, secret={secret}''.'
    OAuth1:
      type: oauth2
      description: OAuth 1.0a flow modeled as OAuth2 for tooling. Required for write actions on behalf of other users.
      flows:
        authorizationCode:
          authorizationUrl: https://discogs.com/oauth/authorize
          tokenUrl: https://api.discogs.com/oauth/access_token
          scopes:
            read: Read user data
            write: Write/update user resources
security:
- DiscogsToken: []