Discogs API — Database

naftiko: 1.0.0-alpha2
info:
  label: Discogs API — Database
  description: 'Discogs — Database. 12 operations. Lead operation: Get an artist. Self-contained Naftiko capability covering one Discogs business surface.'
  tags:
  - Discogs
  - Music
  - Database
  created: '2026-05-29'
  modified: '2026-05-29'
binds:
- namespace: env
  keys:
    DISCOGS_TOKEN: DISCOGS_TOKEN
capability:
  consumes:
  - type: http
    namespace: discogs-database
    baseUri: https://api.discogs.com
    description: Discogs API — Database business capability. Self-contained, no shared references.
    authentication:
      type: apikey
      key: Authorization
      value: Discogs token={{env.DISCOGS_TOKEN}}
      placement: header
    resources:
    - name: artists-artist-id
      path: /artists/{artist_id}
      operations:
      - name: getartist
        method: GET
        description: Get an artist
        inputParameters:
        - name: artist_id
          in: path
          type: integer
          required: true
          description: The ID of the artist.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: artists-artist-id-releases
      path: /artists/{artist_id}/releases
      operations:
      - name: getartistreleases
        method: GET
        description: Get artist releases
        inputParameters:
        - name: artist_id
          in: path
          type: integer
          required: true
          description: The ID of the artist.
        - name: page
          in: query
          type: integer
          required: false
          description: The page number to return.
        - name: per_page
          in: query
          type: integer
          required: false
          description: The number of items to return per page.
        - name: sort
          in: query
          type: string
          required: false
          description: The field to sort the results by.
        - name: sort_order
          in: query
          type: string
          required: false
          description: The order to sort the results.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: database-search
      path: /database/search
      operations:
      - name: searchdatabase
        method: GET
        description: Search the database
        inputParameters:
        - name: query
          in: query
          type: string
          required: false
          description: Your search query.
        - name: type
          in: query
          type: string
          required: false
          description: The type of resource to search for.
        - name: title
          in: query
          type: string
          required: false
          description: Search by combined "Artist Name - Release Title" field.
        - name: release_title
          in: query
          type: string
          required: false
          description: Search release titles.
        - name: credit
          in: query
          type: string
          required: false
          description: Search release credits.
        - name: artist
          in: query
          type: string
          required: false
          description: Search artist names.
        - name: anv
          in: query
          type: string
          required: false
          description: Search an "Artist Name Variation" (ANV).
        - name: label
          in: query
          type: string
          required: false
          description: Search label names.
        - name: genre
          in: query
          type: string
          required: false
          description: Search genres.
        - name: style
          in: query
          type: string
          required: false
          description: Search styles.
        - name: country
          in: query
          type: string
          required: false
          description: Search release country.
        - name: year
          in: query
          type: string
          required: false
          description: Search release year.
        - name: format
          in: query
          type: string
          required: false
          description: Search formats.
        - name: catno
          in: query
          type: string
          required: false
          description: Search catalog number.
        - name: barcode
          in: query
          type: string
          required: false
          description: Search barcodes.
        - name: track
          in: query
          type: string
          required: false
          description: Search track titles.
        - name: submitter
          in: query
          type: string
          required: false
          description: Search by submitter username.
        - name: contributor
          in: query
          type: string
          required: false
          description: Search by contributor username.
        - name: page
          in: query
          type: integer
          required: false
          description: The page number to return.
        - name: per_page
          in: query
          type: integer
          required: false
          description: The number of items to return per page.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: labels-label-id
      path: /labels/{label_id}
      operations:
      - name: getlabel
        method: GET
        description: Get a label
        inputParameters:
        - name: label_id
          in: path
          type: integer
          required: true
          description: The ID of the label.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: labels-label-id-releases
      path: /labels/{label_id}/releases
      operations:
      - name: getlabelreleases
        method: GET
        description: Get all label releases
        inputParameters:
        - name: label_id
          in: path
          type: integer
          required: true
          description: The ID of the label.
        - name: page
          in: query
          type: integer
          required: false
          description: The page number to return.
        - name: per_page
          in: query
          type: integer
          required: false
          description: The number of items to return per page.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: masters-master-id
      path: /masters/{master_id}
      operations:
      - name: getmasterrelease
        method: GET
        description: Get a master release
        inputParameters:
        - name: master_id
          in: path
          type: integer
          required: true
          description: The ID of the master release.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: masters-master-id-versions
      path: /masters/{master_id}/versions
      operations:
      - name: getmasterreleaseversions
        method: GET
        description: Get master release versions
        inputParameters:
        - name: master_id
          in: path
          type: integer
          required: true
          description: The ID of the master release.
        - name: page
          in: query
          type: integer
          required: false
          description: The page number to return.
        - name: per_page
          in: query
          type: integer
          required: false
          description: The number of items to return per page.
        - name: format
          in: query
          type: string
          required: false
          description: Filter by format.
        - name: label
          in: query
          type: string
          required: false
          description: Filter by label.
        - name: released
          in: query
          type: string
          required: false
          description: Filter by release year.
        - name: country
          in: query
          type: string
          required: false
          description: Filter by country.
        - name: sort
          in: query
          type: string
          required: false
          description: The field to sort the results by.
        - name: sort_order
          in: query
          type: string
          required: false
          description: The order to sort the results.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: releases-release-id
      path: /releases/{release_id}
      operations:
      - name: getrelease
        method: GET
        description: Get a release
        inputParameters:
        - name: release_id
          in: path
          type: integer
          required: true
          description: The ID of the release.
        - name: curr_abbr
          in: query
          type: string
          required: false
          description: Currency for marketplace data.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: releases-release-id-rating
      path: /releases/{release_id}/rating
      operations:
      - name: getreleasecommunityrating
        method: GET
        description: Discogs Get Release Community Rating
        inputParameters:
        - name: release_id
          in: path
          type: integer
          required: true
          description: Release ID.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: releases-release-id-rating-username
      path: /releases/{release_id}/rating/{username}
      operations:
      - name: getreleaseratingbyuser
        method: GET
        description: Discogs Get Release Rating by User
        inputParameters:
        - name: release_id
          in: path
          type: integer
          required: true
          description: Release ID.
        - name: username
          in: path
          type: string
          required: true
          description: Discogs username.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updatereleaseratingbyuser
        method: PUT
        description: Discogs Update Release Rating by User
        inputParameters:
        - name: release_id
          in: path
          type: integer
          required: true
          description: Release ID.
        - name: username
          in: path
          type: string
          required: true
          description: Discogs username.
        - name: body
          in: body
          type: object
          required: true
          description: Request body (JSON).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deletereleaseratingbyuser
        method: DELETE
        description: Discogs Delete Release Rating by User
        inputParameters:
        - name: release_id
          in: path
          type: integer
          required: true
          description: Release ID.
        - name: username
          in: path
          type: string
          required: true
          description: Discogs username.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    namespace: discogs-database-rest
    port: 8080
    description: REST adapter for Discogs API — Database. One Spectral-compliant resource per consumed operation, prefixed with /v1.
    resources:
    - path: /v1/artists/{artist-id}
      name: artists-artist-id
      description: REST surface for Get an artist.
      operations:
      - method: GET
        name: getartist
        description: Get an artist
        call: discogs-database.getartist
        outputParameters:
        - type: object
          mapping: $.
        with:
          artist_id: rest.artist_id
    - path: /v1/artists/{artist-id}/releases
      name: artists-artist-id-releases
      description: REST surface for Get artist releases.
      operations:
      - method: GET
        name: getartistreleases
        description: Get artist releases
        call: discogs-database.getartistreleases
        outputParameters:
        - type: object
          mapping: $.
        with:
          artist_id: rest.artist_id
          page: rest.page
          per_page: rest.per_page
          sort: rest.sort
          sort_order: rest.sort_order
    - path: /v1/database/search
      name: database-search
      description: REST surface for Search the database.
      operations:
      - method: GET
        name: searchdatabase
        description: Search the database
        call: discogs-database.searchdatabase
        outputParameters:
        - type: object
          mapping: $.
        with:
          query: rest.query
          type: rest.type
          title: rest.title
          release_title: rest.release_title
          credit: rest.credit
          artist: rest.artist
          anv: rest.anv
          label: rest.label
          genre: rest.genre
          style: rest.style
          country: rest.country
          year: rest.year
          format: rest.format
          catno: rest.catno
          barcode: rest.barcode
          track: rest.track
          submitter: rest.submitter
          contributor: rest.contributor
          page: rest.page
          per_page: rest.per_page
    - path: /v1/labels/{label-id}
      name: labels-label-id
      description: REST surface for Get a label.
      operations:
      - method: GET
        name: getlabel
        description: Get a label
        call: discogs-database.getlabel
        outputParameters:
        - type: object
          mapping: $.
        with:
          label_id: rest.label_id
    - path: /v1/labels/{label-id}/releases
      name: labels-label-id-releases
      description: REST surface for Get all label releases.
      operations:
      - method: GET
        name: getlabelreleases
        description: Get all label releases
        call: discogs-database.getlabelreleases
        outputParameters:
        - type: object
          mapping: $.
        with:
          label_id: rest.label_id
          page: rest.page
          per_page: rest.per_page
    - path: /v1/masters/{master-id}
      name: masters-master-id
      description: REST surface for Get a master release.
      operations:
      - method: GET
        name: getmasterrelease
        description: Get a master release
        call: discogs-database.getmasterrelease
        outputParameters:
        - type: object
          mapping: $.
        with:
          master_id: rest.master_id
    - path: /v1/masters/{master-id}/versions
      name: masters-master-id-versions
      description: REST surface for Get master release versions.
      operations:
      - method: GET
        name: getmasterreleaseversions
        description: Get master release versions
        call: discogs-database.getmasterreleaseversions
        outputParameters:
        - type: object
          mapping: $.
        with:
          master_id: rest.master_id
          page: rest.page
          per_page: rest.per_page
          format: rest.format
          label: rest.label
          released: rest.released
          country: rest.country
          sort: rest.sort
          sort_order: rest.sort_order
    - path: /v1/releases/{release-id}
      name: releases-release-id
      description: REST surface for Get a release.
      operations:
      - method: GET
        name: getrelease
        description: Get a release
        call: discogs-database.getrelease
        outputParameters:
        - type: object
          mapping: $.
        with:
          release_id: rest.release_id
          curr_abbr: rest.curr_abbr
    - path: /v1/releases/{release-id}/rating
      name: releases-release-id-rating
      description: REST surface for Discogs Get Release Community Rating.
      operations:
      - method: GET
        name: getreleasecommunityrating
        description: Discogs Get Release Community Rating
        call: discogs-database.getreleasecommunityrating
        outputParameters:
        - type: object
          mapping: $.
        with:
          release_id: rest.release_id
    - path: /v1/releases/{release-id}/rating/{username}
      name: releases-release-id-rating-username
      description: REST surface for Discogs Get Release Rating by User.
      operations:
      - method: GET
        name: getreleaseratingbyuser
        description: Discogs Get Release Rating by User
        call: discogs-database.getreleaseratingbyuser
        outputParameters:
        - type: object
          mapping: $.
        with:
          release_id: rest.release_id
          username: rest.username
    - path: /v1/releases/{release-id}/rating/{username}
      name: releases-release-id-rating-username
      description: REST surface for Discogs Update Release Rating by User.
      operations:
      - method: PUT
        name: updatereleaseratingbyuser
        description: Discogs Update Release Rating by User
        call: discogs-database.updatereleaseratingbyuser
        outputParameters:
        - type: object
          mapping: $.
        with:
          release_id: rest.release_id
          username: rest.username
          body: rest.body
    - path: /v1/releases/{release-id}/rating/{username}
      name: releases-release-id-rating-username
      description: REST surface for Discogs Delete Release Rating by User.
      operations:
      - method: DELETE
        name: deletereleaseratingbyuser
        description: Discogs Delete Release Rating by User
        call: discogs-database.deletereleaseratingbyuser
        outputParameters:
        - type: object
          mapping: $.
        with:
          release_id: rest.release_id
          username: rest.username
  - type: mcp
    namespace: discogs-database-mcp
    port: 9090
    transport: http
    description: MCP adapter for Discogs API — Database. One tool per consumed operation, routed inline through this capability's consumes block.
    tools:
    - name: get-artist
      description: Get an artist
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: discogs-database.getartist
      outputParameters:
      - type: object
        mapping: $.
      with:
        artist_id: tools.artist_id
    - name: list-artist-releases
      description: Get artist releases
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: discogs-database.getartistreleases
      outputParameters:
      - type: object
        mapping: $.
      with:
        artist_id: tools.artist_id
        page: tools.page
        per_page: tools.per_page
        sort: tools.sort
        sort_order: tools.sort_order
    - name: search-database
      description: Search the database
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: discogs-database.searchdatabase
      outputParameters:
      - type: object
        mapping: $.
      with:
        query: tools.query
        type: tools.type
        title: tools.title
        release_title: tools.release_title
        credit: tools.credit
        artist: tools.artist
        anv: tools.anv
        label: tools.label
        genre: tools.genre
        style: tools.style
        country: tools.country
        year: tools.year
        format: tools.format
        catno: tools.catno
        barcode: tools.barcode
        track: tools.track
        submitter: tools.submitter
        contributor: tools.contributor
        page: tools.page
        per_page: tools.per_page
    - name: get-label
      description: Get a label
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: discogs-database.getlabel
      outputParameters:
      - type: object
        mapping: $.
      with:
        label_id: tools.label_id
    - name: list-label-releases
      description: Get all label releases
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: discogs-database.getlabelreleases
      outputParameters:
      - type: object
        mapping: $.
      with:
        label_id: tools.label_id
        page: tools.page
        per_page: tools.per_page
    - name: getmasterrelease
      description: Get a master release
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: discogs-database.getmasterrelease
      outputParameters:
      - type: object
        mapping: $.
      with:
        master_id: tools.master_id
    - name: getmasterreleaseversions
      description: Get master release versions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: discogs-database.getmasterreleaseversions
      outputParameters:
      - type: object
        mapping: $.
      with:
        master_id: tools.master_id
        page: tools.page
        per_page: tools.per_page
        format: tools.format
        label: tools.label
        released: tools.released
        country: tools.country
        sort: tools.sort
        sort_order: tools.sort_order
    - name: get-release
      description: Get a release
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: discogs-database.getrelease
      outputParameters:
      - type: object
        mapping: $.
      with:
        release_id: tools.release_id
        curr_abbr: tools.curr_abbr
    - name: get-release-rating
      description: Discogs Get Release Community Rating
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: discogs-database.getreleasecommunityrating
      outputParameters:
      - type: object
        mapping: $.
      with:
        release_id: tools.release_id
    - name: get-user-release-rating
      description: Discogs Get Release Rating by User
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: discogs-database.getreleaseratingbyuser
      outputParameters:
      - type: object
        mapping: $.
      with:
        release_id: tools.release_id
        username: tools.username
    - name: update-user-release-rating
      description: Discogs Update Release Rating by User
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: discogs-database.updatereleaseratingbyuser
      outputParameters:
      - type: object
        mapping: $.
      with:
        release_id: tools.release_id
        username: tools.username
        body: tools.body
    - name: delete-user-release-rating
      description: Discogs Delete Release Rating by User
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: discogs-database.deletereleaseratingbyuser
      outputParameters:
      - type: object
        mapping: $.
      with:
        release_id: tools.release_id
        username: tools.username