openapi: 3.0.3
info:
  title: MusicBrainz Web Service v2
  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: Artists
    description: Lookup, browse, and search for artists (people, bands, orchestras).
  - name: Releases
    description: Lookup, browse, and search for releases (specific issues of an album).
  - name: Release Groups
    description: Lookup, browse, and search for release groups (logical grouping of releases).
  - name: Recordings
    description: Lookup, browse, and search for recordings (distinct audio captures of a performance).
  - name: Works
    description: Lookup, browse, and search for musical works (abstract compositions).
  - name: Labels
    description: Lookup, browse, and search for record labels.
  - name: Places
    description: Lookup, browse, and search for places (venues, studios, etc.).
  - name: Areas
    description: Lookup, browse, and search for geographic areas (countries, cities, etc.).
  - name: Events
    description: Lookup, browse, and search for music events (concerts, festivals, etc.).
  - name: Instruments
    description: Lookup and search for instruments used in recordings.
  - name: Series
    description: Lookup, browse, and search for series (ordered groups of entities).
  - name: URLs
    description: Lookup URLs linked to other MusicBrainz entities.
  - name: Genres
    description: List the curated genre taxonomy.
  - name: Identifiers
    description: Non-MBID lookups by ISRC, ISWC, and DiscID.
  - name: Collections
    description: Authenticated user collections of entities.
  - name: Submission
    description: Authenticated submission of tags, ratings, barcodes, and ISRCs.
components:
  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
  parameters:
    MBID:
      name: mbid
      in: path
      required: true
      description: MusicBrainz Identifier (UUID v4) of the entity.
      schema:
        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}$'
        example: 5b11f4ce-a62d-471e-81fc-a69a8278c7da
    Format:
      name: fmt
      in: query
      required: false
      description: Response serialization format. Defaults to XML; set to `json` for JSON.
      schema:
        type: string
        enum: [xml, json]
        default: xml
    Inc:
      name: inc
      in: query
      required: false
      description: Plus-separated list of sub-resources and relationships to include in the response.
      schema:
        type: string
        example: aliases+tags+ratings+artist-rels
    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
    Offset:
      name: offset
      in: query
      required: false
      description: Zero-based offset into the result set for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    Query:
      name: query
      in: query
      required: true
      description: Lucene-syntax search query string.
      schema:
        type: string
        example: 'artist:nirvana AND country:US'
    Dismax:
      name: dismax
      in: query
      required: false
      description: When true, use the simpler dismax query parser instead of full Lucene.
      schema:
        type: boolean
        default: false
    Client:
      name: client
      in: query
      required: true
      description: Application identifier in the form `name-version` for submission requests.
      schema:
        type: string
        example: my-tagger-1.0.0
  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
    LifeSpan:
      type: object
      description: Begin/end dates and whether the entity has ended.
      properties:
        begin:
          type: string
          description: Begin date (year, year-month, or full ISO date).
          example: '1988-01'
        end:
          type: string
          nullable: true
          description: End date (year, year-month, or full ISO date), null if ongoing.
          example: '1994-04-05'
        ended:
          type: boolean
          description: Whether the entity has ended.
    Alias:
      type: object
      description: Alternative name for an entity.
      properties:
        name: {type: string, example: Nirvana}
        sort-name: {type: string, example: Nirvana}
        locale: {type: string, nullable: true, example: en}
        type: {type: string, nullable: true, example: Artist name}
        primary: {type: boolean, nullable: true}
        begin: {type: string, nullable: true}
        end: {type: string, nullable: true}
    Tag:
      type: object
      properties:
        name: {type: string, example: grunge}
        count: {type: integer, example: 42}
    Rating:
      type: object
      properties:
        value: {type: number, format: float, minimum: 0, maximum: 5, example: 4.5}
        votes-count: {type: integer, example: 123}
    Relation:
      type: object
      description: Typed relationship between two MusicBrainz entities.
      properties:
        type: {type: string, example: composer}
        type-id: {$ref: '#/components/schemas/MBID'}
        direction: {type: string, enum: [forward, backward]}
        target-type: {type: string, example: artist}
        target-credit: {type: string, nullable: true}
        attributes: {type: array, items: {type: string}}
        artist: {$ref: '#/components/schemas/Artist'}
        url: {$ref: '#/components/schemas/Url'}
        work: {$ref: '#/components/schemas/Work'}
        recording: {$ref: '#/components/schemas/Recording'}
        begin: {type: string, nullable: true}
        end: {type: string, nullable: true}
        ended: {type: boolean}
    Artist:
      type: object
      description: A person, group, orchestra, choir, character, or other artistic entity.
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        name: {type: string, example: Nirvana}
        sort-name: {type: string, example: Nirvana}
        type: {type: string, nullable: true, enum: [Person, Group, Orchestra, Choir, Character, Other], example: Group}
        type-id: {$ref: '#/components/schemas/MBID'}
        gender: {type: string, nullable: true, enum: [Male, Female, Other, Not applicable]}
        gender-id: {type: string, nullable: true}
        country: {type: string, nullable: true, description: ISO 3166-1 alpha-2 country code, example: US}
        area: {$ref: '#/components/schemas/Area'}
        begin-area: {$ref: '#/components/schemas/Area'}
        end-area: {$ref: '#/components/schemas/Area'}
        disambiguation: {type: string, example: '90s US grunge band'}
        isnis: {type: array, items: {type: string}, description: International Standard Name Identifiers}
        ipis: {type: array, items: {type: string}, description: Interested Parties Information codes}
        life-span: {$ref: '#/components/schemas/LifeSpan'}
        aliases: {type: array, items: {$ref: '#/components/schemas/Alias'}}
        tags: {type: array, items: {$ref: '#/components/schemas/Tag'}}
        rating: {$ref: '#/components/schemas/Rating'}
        relations: {type: array, items: {$ref: '#/components/schemas/Relation'}}
    Area:
      type: object
      description: A geographic area (country, subdivision, city, etc.).
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        name: {type: string, example: United States}
        sort-name: {type: string}
        type: {type: string, nullable: true, enum: [Country, Subdivision, County, Municipality, City, District, Island]}
        type-id: {$ref: '#/components/schemas/MBID'}
        iso-3166-1-codes: {type: array, items: {type: string}, example: [US]}
        iso-3166-2-codes: {type: array, items: {type: string}}
        iso-3166-3-codes: {type: array, items: {type: string}}
        disambiguation: {type: string}
        life-span: {$ref: '#/components/schemas/LifeSpan'}
    Release:
      type: object
      description: A specific issue of a release-group, with packaging, label, country, and barcode.
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        title: {type: string, example: Nevermind}
        status: {type: string, nullable: true, enum: [Official, Promotion, Bootleg, Pseudo-Release, Withdrawn, Cancelled]}
        status-id: {type: string, nullable: true}
        quality: {type: string, enum: [low, normal, high]}
        packaging: {type: string, nullable: true, example: Jewel Case}
        packaging-id: {type: string, nullable: true}
        language: {type: string, nullable: true, description: ISO 639-3 code, example: eng}
        script: {type: string, nullable: true, description: ISO 15924 code, example: Latn}
        date: {type: string, nullable: true, example: '1991-09-24'}
        country: {type: string, nullable: true, example: US}
        barcode: {type: string, nullable: true, example: '720642442524'}
        asin: {type: string, nullable: true, description: Amazon Standard Identification Number}
        disambiguation: {type: string}
        artist-credit:
          type: array
          items:
            type: object
            properties:
              name: {type: string}
              joinphrase: {type: string}
              artist: {$ref: '#/components/schemas/Artist'}
        release-group: {$ref: '#/components/schemas/ReleaseGroup'}
        label-info:
          type: array
          items:
            type: object
            properties:
              catalog-number: {type: string, nullable: true}
              label: {$ref: '#/components/schemas/Label'}
        media:
          type: array
          items:
            type: object
            properties:
              position: {type: integer}
              format: {type: string, example: CD}
              format-id: {type: string}
              title: {type: string}
              track-count: {type: integer}
              tracks: {type: array, items: {$ref: '#/components/schemas/Track'}}
              discs:
                type: array
                items:
                  type: object
                  properties:
                    id: {type: string, description: Disc ID}
                    sectors: {type: integer}
                    offsets: {type: array, items: {type: integer}}
        cover-art-archive:
          type: object
          properties:
            artwork: {type: boolean}
            count: {type: integer}
            front: {type: boolean}
            back: {type: boolean}
            darkened: {type: boolean}
        text-representation:
          type: object
          properties:
            language: {type: string}
            script: {type: string}
        tags: {type: array, items: {$ref: '#/components/schemas/Tag'}}
        rating: {$ref: '#/components/schemas/Rating'}
        relations: {type: array, items: {$ref: '#/components/schemas/Relation'}}
    ReleaseGroup:
      type: object
      description: A logical grouping of releases (e.g. an album and its reissues).
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        title: {type: string, example: Nevermind}
        primary-type: {type: string, nullable: true, enum: [Album, Single, EP, Broadcast, Other]}
        primary-type-id: {type: string, nullable: true}
        secondary-types: {type: array, items: {type: string}}
        secondary-type-ids: {type: array, items: {type: string}}
        first-release-date: {type: string, example: '1991-09-24'}
        disambiguation: {type: string}
        artist-credit: {type: array, items: {type: object}}
        releases: {type: array, items: {$ref: '#/components/schemas/Release'}}
        tags: {type: array, items: {$ref: '#/components/schemas/Tag'}}
        rating: {$ref: '#/components/schemas/Rating'}
    Track:
      type: object
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        position: {type: integer, example: 1}
        number: {type: string, example: '1'}
        title: {type: string, example: Smells Like Teen Spirit}
        length: {type: integer, description: Length in milliseconds, example: 301920}
        artist-credit: {type: array, items: {type: object}}
        recording: {$ref: '#/components/schemas/Recording'}
    Recording:
      type: object
      description: A distinct audio capture of a performance.
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        title: {type: string, example: Smells Like Teen Spirit}
        length: {type: integer, description: Length in milliseconds, example: 301920}
        video: {type: boolean}
        disambiguation: {type: string}
        first-release-date: {type: string}
        isrcs: {type: array, items: {type: string}, example: [USGF19102751]}
        artist-credit: {type: array, items: {type: object}}
        releases: {type: array, items: {$ref: '#/components/schemas/Release'}}
        tags: {type: array, items: {$ref: '#/components/schemas/Tag'}}
        rating: {$ref: '#/components/schemas/Rating'}
        relations: {type: array, items: {$ref: '#/components/schemas/Relation'}}
    Work:
      type: object
      description: A distinct intellectual or artistic creation (song, composition, etc.).
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        title: {type: string, example: Smells Like Teen Spirit}
        type: {type: string, nullable: true, example: Song}
        type-id: {type: string, nullable: true}
        language: {type: string, nullable: true, example: eng}
        languages: {type: array, items: {type: string}}
        iswcs: {type: array, items: {type: string}, example: [T-101.690.320-9]}
        attributes:
          type: array
          items:
            type: object
            properties:
              type: {type: string}
              type-id: {type: string}
              value: {type: string}
              value-id: {type: string, nullable: true}
        disambiguation: {type: string}
        tags: {type: array, items: {$ref: '#/components/schemas/Tag'}}
        rating: {$ref: '#/components/schemas/Rating'}
        relations: {type: array, items: {$ref: '#/components/schemas/Relation'}}
    Label:
      type: object
      description: A record label or imprint.
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        name: {type: string, example: DGC}
        sort-name: {type: string}
        type: {type: string, nullable: true, enum: [Imprint, Production, Original Production, Bootleg Production, Reissue Production, Distributor, Holding, Rights Society, Publisher]}
        type-id: {type: string, nullable: true}
        label-code: {type: integer, nullable: true, description: Numeric label code without LC prefix}
        country: {type: string, nullable: true}
        area: {$ref: '#/components/schemas/Area'}
        ipis: {type: array, items: {type: string}}
        isnis: {type: array, items: {type: string}}
        disambiguation: {type: string}
        life-span: {$ref: '#/components/schemas/LifeSpan'}
        tags: {type: array, items: {$ref: '#/components/schemas/Tag'}}
        rating: {$ref: '#/components/schemas/Rating'}
    Place:
      type: object
      description: A physical location (venue, studio, etc.).
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        name: {type: string, example: Sound City Studios}
        type: {type: string, nullable: true, enum: [Studio, Venue, Stadium, Indoor arena, Religious building, Educational institution, Pressing plant, Other]}
        type-id: {type: string, nullable: true}
        address: {type: string, nullable: true}
        area: {$ref: '#/components/schemas/Area'}
        coordinates:
          type: object
          nullable: true
          properties:
            latitude: {type: number, format: float}
            longitude: {type: number, format: float}
        disambiguation: {type: string}
        life-span: {$ref: '#/components/schemas/LifeSpan'}
    Event:
      type: object
      description: An organized happening at which artists perform (concert, festival, ceremony).
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        name: {type: string, example: Reading Festival 1992}
        type: {type: string, nullable: true, enum: [Concert, Festival, Launch event, Convention/Expo, Masterclass/Clinic, Stage performance, Award ceremony, Other]}
        type-id: {type: string, nullable: true}
        cancelled: {type: boolean}
        time: {type: string, nullable: true}
        setlist: {type: string, nullable: true}
        disambiguation: {type: string}
        life-span: {$ref: '#/components/schemas/LifeSpan'}
    Instrument:
      type: object
      description: A musical instrument or family of instruments.
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        name: {type: string, example: electric guitar}
        type: {type: string, nullable: true, enum: [Wind instrument, String instrument, Percussion instrument, Electronic instrument, Family, Ensemble, Other instrument]}
        type-id: {type: string, nullable: true}
        description: {type: string}
        disambiguation: {type: string}
    Series:
      type: object
      description: An ordered grouping of related entities (tour, festival series, award ceremony series, etc.).
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        name: {type: string, example: Reading Festival}
        type: {type: string, nullable: true}
        type-id: {type: string, nullable: true}
        ordering-attribute: {type: string, nullable: true}
        disambiguation: {type: string}
    Url:
      type: object
      description: A URL linked to other MusicBrainz entities.
      properties:
        id: {$ref: '#/components/schemas/MBID'}
        resource: {type: string, format: uri, example: 'https://www.nin.com/'}
        relations: {type: array, items: {$ref: '#/components/schemas/Relation'}}
    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}
    BrowseArtistsResponse:
      type: object
      properties:
        artist-count: {type: integer}
        artist-offset: {type: integer}
        artists: {type: array, items: {$ref: '#/components/schemas/Artist'}}
    BrowseReleasesResponse:
      type: object
      properties:
        release-count: {type: integer}
        release-offset: {type: integer}
        releases: {type: array, items: {$ref: '#/components/schemas/Release'}}
    BrowseRecordingsResponse:
      type: object
      properties:
        recording-count: {type: integer}
        recording-offset: {type: integer}
        recordings: {type: array, items: {$ref: '#/components/schemas/Recording'}}
    BrowseWorksResponse:
      type: object
      properties:
        work-count: {type: integer}
        work-offset: {type: integer}
        works: {type: array, items: {$ref: '#/components/schemas/Work'}}
    SearchScored:
      type: object
      description: A scored search result wraps an entity with a relevance score.
      properties:
        score: {type: integer, minimum: 0, maximum: 100}
    SearchArtistsResponse:
      type: object
      properties:
        created: {type: string, format: date-time}
        count: {type: integer}
        offset: {type: integer}
        artists:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Artist'
              - $ref: '#/components/schemas/SearchScored'
    SearchReleasesResponse:
      type: object
      properties:
        created: {type: string, format: date-time}
        count: {type: integer}
        offset: {type: integer}
        releases:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Release'
              - $ref: '#/components/schemas/SearchScored'
    SearchRecordingsResponse:
      type: object
      properties:
        created: {type: string, format: date-time}
        count: {type: integer}
        offset: {type: integer}
        recordings:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Recording'
              - $ref: '#/components/schemas/SearchScored'
    Error:
      type: object
      properties:
        error: {type: string}
        help: {type: string}
  responses:
    NotFound:
      description: Entity not found
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    BadRequest:
      description: Malformed request or invalid parameters
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    Unauthorized:
      description: Authentication required or invalid credentials
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    Forbidden:
      description: Authenticated but not authorized
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    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'}
    ServiceUnavailable:
      description: Service temporarily unavailable
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
paths:
  /artist/{mbid}:
    get:
      operationId: lookupArtist
      summary: Lookup Artist
      description: Look up an artist by MBID, optionally including sub-resources and relationships via `inc`.
      tags: [Artists]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Artist found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Artist'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
        '503': {$ref: '#/components/responses/ServiceUnavailable'}
  /artist:
    get:
      operationId: browseOrSearchArtists
      summary: Browse Or Search Artists
      description: Browse artists linked to a parent entity (`area`, `collection`, `recording`, `release`, `release-group`, `work`)
        or search the indexed catalog with a Lucene `query`.
      tags: [Artists]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: query
          in: query
          required: false
          schema: {type: string}
          description: Lucene query string (mutually exclusive with browse parameters).
        - name: area
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: collection
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: recording
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: release
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: release-group
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: work
          in: query
          required: false
          schema: {type: string, format: uuid}
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
        - $ref: '#/components/parameters/Dismax'
      responses:
        '200':
          description: List of artists (browse) or scored search results
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BrowseArtistsResponse'
                  - $ref: '#/components/schemas/SearchArtistsResponse'
        '400': {$ref: '#/components/responses/BadRequest'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
        '503': {$ref: '#/components/responses/ServiceUnavailable'}
  /release/{mbid}:
    get:
      operationId: lookupRelease
      summary: Lookup Release
      description: Look up a release by MBID. Common includes are `artist-credits`, `labels`, `discids`, `recordings`,
        `release-groups`, `media`, `isrcs`.
      tags: [Releases]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Release found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Release'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /release:
    get:
      operationId: browseOrSearchReleases
      summary: Browse Or Search Releases
      description: Browse releases linked to a parent entity or search by Lucene query. Browse may be filtered by
        `type`, `status`, and `release-group-status`.
      tags: [Releases]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: query
          in: query
          required: false
          schema: {type: string}
        - name: area
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: artist
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: collection
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: label
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: recording
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: release-group
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: track
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: track_artist
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: type
          in: query
          required: false
          schema: {type: string}
        - name: status
          in: query
          required: false
          schema: {type: string, enum: [official, promotion, bootleg, pseudo-release, withdrawn, cancelled]}
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Browse or search results
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BrowseReleasesResponse'
                  - $ref: '#/components/schemas/SearchReleasesResponse'
        '400': {$ref: '#/components/responses/BadRequest'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
    post:
      operationId: submitBarcodes
      summary: Submit Release Barcodes
      description: Submit GTIN/EAN/UPC barcodes for one or more releases (XML body, requires authentication).
      tags: [Submission]
      security: [{HTTPBasic: []}, {OAuth2: [submit_barcode]}]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/Client'
      requestBody:
        required: true
        content:
          application/xml:
            schema: {type: string, description: MMD-2 XML metadata document with release barcode entries.}
      responses:
        '200': {description: Submission accepted}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /release-group/{mbid}:
    get:
      operationId: lookupReleaseGroup
      summary: Lookup Release Group
      description: Look up a release group by MBID.
      tags: [Release Groups]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Release group found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ReleaseGroup'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /release-group:
    get:
      operationId: browseOrSearchReleaseGroups
      summary: Browse Or Search Release Groups
      description: Browse release groups linked to an artist, collection, or release; or search with a Lucene query.
      tags: [Release Groups]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: query
          in: query
          schema: {type: string}
        - name: artist
          in: query
          schema: {type: string, format: uuid}
        - name: collection
          in: query
          schema: {type: string, format: uuid}
        - name: release
          in: query
          schema: {type: string, format: uuid}
        - name: type
          in: query
          schema: {type: string}
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200': {description: Browse or search results}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /recording/{mbid}:
    get:
      operationId: lookupRecording
      summary: Lookup Recording
      description: Look up a recording by MBID. Common includes are `artist-credits`, `releases`, `isrcs`, `url-rels`,
        `work-rels`.
      tags: [Recordings]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Recording found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Recording'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /recording:
    get:
      operationId: browseOrSearchRecordings
      summary: Browse Or Search Recordings
      description: Browse recordings linked to an artist, collection, release, or work; or search with a Lucene query.
      tags: [Recordings]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: query
          in: query
          schema: {type: string}
        - name: artist
          in: query
          schema: {type: string, format: uuid}
        - name: collection
          in: query
          schema: {type: string, format: uuid}
        - name: release
          in: query
          schema: {type: string, format: uuid}
        - name: work
          in: query
          schema: {type: string, format: uuid}
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Browse or search results
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BrowseRecordingsResponse'
                  - $ref: '#/components/schemas/SearchRecordingsResponse'
        '429': {$ref: '#/components/responses/TooManyRequests'}
    post:
      operationId: submitISRCs
      summary: Submit Recording ISRCs
      description: Submit ISRCs for one or more recordings (XML body, requires authentication).
      tags: [Submission]
      security: [{HTTPBasic: []}, {OAuth2: [submit_isrc]}]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/Client'
      requestBody:
        required: true
        content:
          application/xml:
            schema: {type: string, description: MMD-2 XML document with `<recording>` entries and `<isrc-list>`.}
      responses:
        '200': {description: Submission accepted}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /work/{mbid}:
    get:
      operationId: lookupWork
      summary: Lookup Work
      description: Look up a work by MBID. Common includes are `artist-rels`, `recording-rels`, `aliases`.
      tags: [Works]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Work found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Work'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /work:
    get:
      operationId: browseOrSearchWorks
      summary: Browse Or Search Works
      description: Browse works linked to an artist or collection, or search with a Lucene query.
      tags: [Works]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: query
          in: query
          schema: {type: string}
        - name: artist
          in: query
          schema: {type: string, format: uuid}
        - name: collection
          in: query
          schema: {type: string, format: uuid}
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Browse or search results
          content:
            application/json:
              schema: {$ref: '#/components/schemas/BrowseWorksResponse'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /label/{mbid}:
    get:
      operationId: lookupLabel
      summary: Lookup Label
      description: Look up a label by MBID.
      tags: [Labels]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Label found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Label'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /label:
    get:
      operationId: browseOrSearchLabels
      summary: Browse Or Search Labels
      description: Browse labels linked to an area, collection, or release, or search with a Lucene query.
      tags: [Labels]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: query
          in: query
          schema: {type: string}
        - name: area
          in: query
          schema: {type: string, format: uuid}
        - name: collection
          in: query
          schema: {type: string, format: uuid}
        - name: release
          in: query
          schema: {type: string, format: uuid}
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200': {description: Browse or search results}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /place/{mbid}:
    get:
      operationId: lookupPlace
      summary: Lookup Place
      description: Look up a place by MBID.
      tags: [Places]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Place found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Place'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /place:
    get:
      operationId: browseOrSearchPlaces
      summary: Browse Or Search Places
      description: Browse places linked to an area or collection, or search with a Lucene query.
      tags: [Places]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: query
          in: query
          schema: {type: string}
        - name: area
          in: query
          schema: {type: string, format: uuid}
        - name: collection
          in: query
          schema: {type: string, format: uuid}
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200': {description: Browse or search results}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /area/{mbid}:
    get:
      operationId: lookupArea
      summary: Lookup Area
      description: Look up a geographic area by MBID.
      tags: [Areas]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Area found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Area'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /area:
    get:
      operationId: searchAreas
      summary: Search Areas
      description: Search areas with a Lucene query.
      tags: [Areas]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Format'
      responses:
        '200': {description: Search results}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /event/{mbid}:
    get:
      operationId: lookupEvent
      summary: Lookup Event
      description: Look up an event by MBID.
      tags: [Events]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Event found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Event'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /event:
    get:
      operationId: browseOrSearchEvents
      summary: Browse Or Search Events
      description: Browse events linked to an area, artist, collection, place, or other event, or search with a
        Lucene query.
      tags: [Events]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: query
          in: query
          schema: {type: string}
        - name: area
          in: query
          schema: {type: string, format: uuid}
        - name: artist
          in: query
          schema: {type: string, format: uuid}
        - name: collection
          in: query
          schema: {type: string, format: uuid}
        - name: place
          in: query
          schema: {type: string, format: uuid}
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200': {description: Browse or search results}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /instrument/{mbid}:
    get:
      operationId: lookupInstrument
      summary: Lookup Instrument
      description: Look up an instrument by MBID.
      tags: [Instruments]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Instrument found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Instrument'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /instrument:
    get:
      operationId: searchInstruments
      summary: Search Instruments
      description: Search instruments with a Lucene query.
      tags: [Instruments]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Format'
      responses:
        '200': {description: Search results}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /series/{mbid}:
    get:
      operationId: lookupSeries
      summary: Lookup Series
      description: Look up a series by MBID.
      tags: [Series]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Series found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Series'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /series:
    get:
      operationId: searchSeries
      summary: Search Series
      description: Search series with a Lucene query, or browse by collection.
      tags: [Series]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: query
          in: query
          schema: {type: string}
        - name: collection
          in: query
          schema: {type: string, format: uuid}
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200': {description: Browse or search results}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /url/{mbid}:
    get:
      operationId: lookupUrl
      summary: Lookup Url
      description: Look up a URL by MBID.
      tags: [URLs]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/MBID'
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: URL found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Url'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /url:
    get:
      operationId: lookupUrlsByResource
      summary: Lookup Urls By Resource
      description: Look up one or more URLs by the resource string (up to 100 `resource` parameters per request).
      tags: [URLs, Identifiers]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: resource
          in: query
          required: true
          description: A URL to look up. May be repeated up to 100 times in one request.
          schema: {type: string, format: uri}
          example: https://www.nin.com/
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: URL or url-list found
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Url'
                  - type: object
                    properties:
                      url-count: {type: integer}
                      urls: {type: array, items: {$ref: '#/components/schemas/Url'}}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /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'}
  /isrc/{isrc}:
    get:
      operationId: lookupRecordingsByISRC
      summary: Lookup Recordings By ISRC
      description: Look up all recordings that share an International Standard Recording Code.
      tags: [Identifiers, Recordings]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: isrc
          in: path
          required: true
          description: International Standard Recording Code (12 characters).
          schema:
            type: string
            pattern: '^[A-Z]{2}[A-Z0-9]{3}[0-9]{7}$'
            example: USGF19102751
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Recordings sharing this ISRC
          content:
            application/json:
              schema:
                type: object
                properties:
                  isrc: {type: string}
                  recordings: {type: array, items: {$ref: '#/components/schemas/Recording'}}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /iswc/{iswc}:
    get:
      operationId: lookupWorksByISWC
      summary: Lookup Works By ISWC
      description: Look up all works that share an International Standard Musical Work Code.
      tags: [Identifiers, Works]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: iswc
          in: path
          required: true
          description: International Standard Musical Work Code (e.g. T-101.690.320-9).
          schema:
            type: string
            example: T-101.690.320-9
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Works sharing this ISWC
          content:
            application/json:
              schema:
                type: object
                properties:
                  iswc: {type: string}
                  works: {type: array, items: {$ref: '#/components/schemas/Work'}}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /discid/{discid}:
    get:
      operationId: lookupReleasesByDiscID
      summary: Lookup Releases By Disc ID
      description: Look up releases that match a CD's MusicBrainz Disc ID. Supports fuzzy TOC matching and optional
        CD-stub fallback.
      tags: [Identifiers, Releases]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: discid
          in: path
          required: true
          description: 28-character MusicBrainz Disc ID computed by libdiscid from a CD's TOC.
          schema:
            type: string
            example: 49HHV7Eb8UKF3aQiNmu1GR8vKjY-
        - name: toc
          in: query
          required: false
          description: Table-of-contents string used for fuzzy matching when the Disc ID is not found.
          schema: {type: string}
        - name: cdstubs
          in: query
          required: false
          description: Whether to include CD-stub matches when no release matches.
          schema: {type: string, enum: [yes, no], default: 'yes'}
        - name: media-format
          in: query
          required: false
          description: Restrict matched releases to a specific media format (e.g. `CD`, `all`).
          schema: {type: string}
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Releases or CD stubs matching the Disc ID
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /collection:
    get:
      operationId: listUserCollections
      summary: List User Collections
      description: List the collections owned by a MusicBrainz editor. Use `inc=user-collections` while authenticated
        to also include private collections.
      tags: [Collections]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: editor
          in: query
          required: true
          schema: {type: string}
          description: MusicBrainz editor (username) whose collections to list.
        - $ref: '#/components/parameters/Inc'
        - $ref: '#/components/parameters/Format'
      responses:
        '200': {description: Collection list}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /collection/{collection_mbid}:
    get:
      operationId: lookupCollection
      summary: Lookup Collection
      description: Look up a collection by MBID.
      tags: [Collections]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: collection_mbid
          in: path
          required: true
          schema: {type: string, format: uuid}
        - $ref: '#/components/parameters/Format'
      responses:
        '200': {description: Collection metadata}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /collection/{collection_mbid}/{entity_type}:
    put:
      operationId: addEntitiesToCollection
      summary: Add Entities To Collection
      description: Add up to ~400 entities (semicolon-separated MBIDs) to an existing collection.
      tags: [Collections]
      security: [{HTTPBasic: []}, {OAuth2: [collection]}]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: collection_mbid
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: entity_type
          in: path
          required: true
          schema:
            type: string
            enum: [areas, artists, events, labels, places, recordings, release-groups, releases, works]
        - $ref: '#/components/parameters/Client'
      responses:
        '200': {description: Entities added}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
    delete:
      operationId: removeEntitiesFromCollection
      summary: Remove Entities From Collection
      description: Remove entities (semicolon-separated MBIDs) from a collection.
      tags: [Collections]
      security: [{HTTPBasic: []}, {OAuth2: [collection]}]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - name: collection_mbid
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: entity_type
          in: path
          required: true
          schema:
            type: string
            enum: [areas, artists, events, labels, places, recordings, release-groups, releases, works]
        - $ref: '#/components/parameters/Client'
      responses:
        '200': {description: Entities removed}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /tag:
    post:
      operationId: submitTags
      summary: Submit User Tags
      description: Submit one or more user tags (upvote/downvote/withdraw) on entities (XML body, requires authentication).
      tags: [Submission]
      security: [{HTTPBasic: []}, {OAuth2: [tag]}]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/Client'
      requestBody:
        required: true
        content:
          application/xml:
            schema: {type: string, description: MMD-2 XML with `<user-tag>` elements (vote attribute optional).}
      responses:
        '200': {description: Tag submission accepted}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /rating:
    post:
      operationId: submitRatings
      summary: Submit User Ratings
      description: Submit one or more user ratings (integer 0-5, with 0 meaning withdraw) on entities (XML body,
        requires authentication).
      tags: [Submission]
      security: [{HTTPBasic: []}, {OAuth2: [rating]}]
      x-microcks-operation: {delay: 0, dispatcher: FALLBACK}
      parameters:
        - $ref: '#/components/parameters/Client'
      requestBody:
        required: true
        content:
          application/xml:
            schema: {type: string, description: MMD-2 XML with `<user-rating>` elements.}
      responses:
        '200': {description: Rating submission accepted}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/TooManyRequests'}