openapi: 3.0.3
info:
  title: MusicBrainz Web Service v2 Areas Genres API
  version: '2.0'
  description: 'The MusicBrainz Web Service v2 is the free public REST API to the MusicBrainz open music encyclopedia,

    operated by the MetaBrainz Foundation (a US 501(c)(3) non-profit).


    The API supports three primary access patterns over twelve core entity types

    (artist, release, release-group, recording, work, label, place, area, event, instrument, series, url, genre):


    - **Lookup** — fetch one entity by its MBID with configurable sub-resource includes.

    - **Browse** — list entities linked to a given parent entity, with pagination.

    - **Search** — full Lucene query syntax across the indexed catalog.


    Non-MBID lookups are available for ISRC (recordings), ISWC (works), DiscID (releases), and URL.


    Responses are returned in MMD-2 XML by default or JSON via the `fmt=json` query parameter.


    The API enforces a strict rate limit of **one request per IP per second** and requires a meaningful

    **User-Agent** header on every request (e.g. `MyApp/1.0.0 ( contact@example.com )`).

    Submission and user-specific endpoints require HTTP Basic or OAuth 2.0 authentication.

    '
  contact:
    name: MetaBrainz Foundation
    url: https://metabrainz.org/
    email: support@metabrainz.org
  license:
    name: API access is free; data licensed CC0 (core) and CC-BY-NC-SA (supplemental)
    url: https://musicbrainz.org/doc/About/Data_License
  termsOfService: https://metabrainz.org/social-contract
  x-generated-from: documentation
  x-last-validated: '2026-05-29'
servers:
- url: https://musicbrainz.org/ws/2
  description: Production MusicBrainz Web Service v2
- url: https://beta.musicbrainz.org/ws/2
  description: Beta MusicBrainz Web Service v2 (pre-release schema changes)
tags:
- name: Genres
  description: List the curated genre taxonomy.
paths:
  /genre/all:
    get:
      operationId: listAllGenres
      summary: List All Genres
      description: Return every entry from the curated MusicBrainz genre taxonomy. Also supports `fmt=txt` for a plain-text list of genre names.
      tags:
      - Genres
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - name: fmt
        in: query
        schema:
          type: string
          enum:
          - xml
          - json
          - txt
          default: xml
      responses:
        '200':
          description: Genre list
          content:
            application/json:
              schema:
                type: object
                properties:
                  genre-count:
                    type: integer
                  genre-offset:
                    type: integer
                  genres:
                    type: array
                    items:
                      $ref: '#/components/schemas/Genre'
            text/plain:
              schema:
                type: string
                description: One genre name per line.
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    MBID:
      type: string
      format: uuid
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      description: MusicBrainz Identifier (UUID v4) - the canonical primary key for every entity.
      example: 5b11f4ce-a62d-471e-81fc-a69a8278c7da
    Genre:
      type: object
      description: A music genre from the curated MusicBrainz taxonomy.
      properties:
        id:
          $ref: '#/components/schemas/MBID'
        name:
          type: string
          example: grunge
        disambiguation:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string
        help:
          type: string
  parameters:
    Offset:
      name: offset
      in: query
      required: false
      description: Zero-based offset into the result set for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of results to return (1-100, default 25).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  responses:
    TooManyRequests:
      description: Rate limit exceeded - clients must throttle to 1 request per second per IP
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    HTTPBasic:
      type: http
      scheme: basic
      description: HTTP Basic authentication using MusicBrainz editor credentials. Required for submission and user-specific endpoints.
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication via the MusicBrainz OAuth server.
      flows:
        authorizationCode:
          authorizationUrl: https://musicbrainz.org/oauth2/authorize
          tokenUrl: https://musicbrainz.org/oauth2/token
          scopes:
            profile: Access user profile
            email: Access user email
            tag: Submit tags
            rating: Submit ratings
            collection: Manage collections
            submit_barcode: Submit release barcodes
            submit_isrc: Submit recording ISRCs