Discogs Database API

openapi: 3.1.1
info:
  title: Discogs Database 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'
servers:
- url: https://api.discogs.com
  description: Production API Server
security:
- DiscogsToken: []
tags:
- name: Database
  description: 'Access Discogs database: artists, releases, masters, labels, and search.'
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
  /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
  /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
  /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
components:
  parameters:
    ReleaseId:
      name: release_id
      in: path
      required: true
      description: The ID of the release.
      schema:
        type: integer
      example: 249504
    SortOrder:
      name: sort_order
      in: query
      description: The order to sort the results.
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
    Page:
      name: page
      in: query
      description: The page number to return.
      schema:
        type: integer
        default: 1
        minimum: 1
    FormatFilter:
      name: format
      in: query
      description: Filter by format.
      schema:
        type: string
    PerPage:
      name: per_page
      in: query
      description: The number of items to return per page.
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 100
    SortArtistReleases:
      name: sort
      in: query
      description: The field to sort the results by.
      schema:
        type: string
        enum:
        - year
        - title
        - format
        default: year
    LabelId:
      name: label_id
      in: path
      required: true
      description: The ID of the label.
      schema:
        type: integer
      example: 1
    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
    ArtistId:
      name: artist_id
      in: path
      required: true
      description: The ID of the artist.
      schema:
        type: integer
      example: 108713
    LabelFilter:
      name: label
      in: query
      description: Filter by label.
      schema:
        type: string
    MasterId:
      name: master_id
      in: path
      required: true
      description: The ID of the master release.
      schema:
        type: integer
      example: 1000
    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
  schemas:
    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
    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
    Video:
      type: object
      properties:
        uri:
          type: string
          format: uri
        duration:
          type: integer
        title:
          type: string
        description:
          type: string
        embed:
          type: boolean
    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
    Identifier:
      type: object
      properties:
        type:
          type: string
        value:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
    SearchResultArtist:
      allOf:
      - $ref: '#/components/schemas/SearchResultRelease'
      - type: object
        properties:
          type:
            enum:
            - artist
    SearchResultMaster:
      allOf:
      - $ref: '#/components/schemas/SearchResultRelease'
      - type: object
        properties:
          type:
            enum:
            - master
          main_release:
            type: integer
    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
    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
    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
    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
    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'
    UserSummary:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        resource_url:
          type: string
          format: uri
    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
    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
    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
    SearchResultLabel:
      allOf:
      - $ref: '#/components/schemas/SearchResultRelease'
      - type: object
        properties:
          type:
            enum:
            - label
    Currency:
      type: string
      enum:
      - USD
      - GBP
      - EUR
      - CAD
      - AUD
      - JPY
      - CHF
      - MXN
      - BRL
      - NZD
      - SEK
      - ZAR
    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
    Error:
      type: object
      properties:
        message:
          type: string
    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
    Image:
      type: object
      properties:
        type:
          type: string
          enum:
          - pr

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/discogs/refs/heads/main/openapi/discogs-database-api-openapi.yml