openapi: 3.1.0
info:
  title: TheAudioDB API
  version: "2.0"
  summary: TheAudioDB v2 JSON API
  description: |
    OpenAPI specification for the documented TheAudioDB v2 API.

    v2 uses a premium API key passed in the `X-API-KEY` request header. Public
    routes use a REST-style path and are rewritten internally to the v2 PHP
    handlers. When a request fails authentication or validation, v2 returns a
    JSON object containing a `Message` field.
  contact:
    name: TheAudioDB
    url: https://www.theaudiodb.com
servers:
  - url: https://www.theaudiodb.com/api/v2/json
    description: Production v2 JSON API
security:
  - ApiKeyAuth: []
tags:
  - name: Search
    description: Search artists, albums, and tracks by text.
  - name: Lookup
    description: Lookup artists, albums, and tracks by TheAudioDB or MusicBrainz IDs.
  - name: List
    description: List related resources for an entity.
paths:
  /search/artist/{query}:
    get:
      tags:
        - Search
      operationId: searchArtist
      summary: Search artists
      description: Search for music artists using a text string. Returns up to 10 documented results.
      parameters:
        - $ref: "#/components/parameters/SearchQuery"
      responses:
        "200":
          $ref: "#/components/responses/SearchArtistsResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
  /search/album/{query}:
    get:
      tags:
        - Search
      operationId: searchAlbum
      summary: Search albums
      description: Search for music albums using a text string. Returns up to 10 documented results.
      parameters:
        - name: query
          in: path
          required: true
          description: Album search text.
          schema:
            type: string
          example: parachutes
      responses:
        "200":
          $ref: "#/components/responses/SearchAlbumsResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
  /search/track/{query}:
    get:
      tags:
        - Search
      operationId: searchTrack
      summary: Search tracks
      description: Search for music tracks using a text string. Returns up to 10 documented results.
      parameters:
        - name: query
          in: path
          required: true
          description: Track search text.
          schema:
            type: string
          example: yellow
      responses:
        "200":
          $ref: "#/components/responses/SearchTracksResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
  /lookup/artist/{id}:
    get:
      tags:
        - Lookup
      operationId: lookupArtist
      summary: Lookup artist by ID
      description: Lookup full details for an artist using its TheAudioDB artist ID.
      parameters:
        - name: id
          in: path
          required: true
          description: TheAudioDB artist ID.
          schema:
            type: integer
          example: 111239
      responses:
        "200":
          $ref: "#/components/responses/LookupArtistsResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
  /lookup/artist_mb/{musicBrainzId}:
    get:
      tags:
        - Lookup
      operationId: lookupArtistByMusicBrainzId
      summary: Lookup artist by MusicBrainz artist ID
      parameters:
        - $ref: "#/components/parameters/MusicBrainzArtistId"
      responses:
        "200":
          $ref: "#/components/responses/LookupArtistsResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
  /lookup/album/{id}:
    get:
      tags:
        - Lookup
      operationId: lookupAlbum
      summary: Lookup album by ID
      description: Lookup full details for an album using its TheAudioDB album ID.
      parameters:
        - name: id
          in: path
          required: true
          description: TheAudioDB album ID.
          schema:
            type: integer
          example: 2109615
      responses:
        "200":
          $ref: "#/components/responses/LookupAlbumsResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
  /lookup/album_mb/{musicBrainzId}:
    get:
      tags:
        - Lookup
      operationId: lookupAlbumByMusicBrainzId
      summary: Lookup album by MusicBrainz release group ID
      parameters:
        - name: musicBrainzId
          in: path
          required: true
          description: MusicBrainz release group ID.
          schema:
            type: string
          example: 1dc4c347-a1db-32aa-b14f-bc9cc507b843
      responses:
        "200":
          $ref: "#/components/responses/LookupAlbumsResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
  /lookup/track/{id}:
    get:
      tags:
        - Lookup
      operationId: lookupTrack
      summary: Lookup track by ID
      description: Lookup full details for a track using its TheAudioDB track ID.
      parameters:
        - name: id
          in: path
          required: true
          description: TheAudioDB track ID.
          schema:
            type: integer
          example: 32724183
      responses:
        "200":
          $ref: "#/components/responses/LookupTracksResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
  /lookup/track_mb/{musicBrainzId}:
    get:
      tags:
        - Lookup
      operationId: lookupTrackByMusicBrainzId
      summary: Lookup track by MusicBrainz recording ID
      parameters:
        - name: musicBrainzId
          in: path
          required: true
          description: MusicBrainz recording ID.
          schema:
            type: string
          example: 50369905-68ca-48d2-912d-b37330ff7dc3
      responses:
        "200":
          $ref: "#/components/responses/LookupTracksResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
  /list/discography/{artistId}:
    get:
      tags:
        - List
      operationId: listArtistDiscography
      summary: List artist discography
      description: Lookup the full list of albums for an artist using its TheAudioDB artist ID. Returns up to 500 documented results.
      parameters:
        - name: artistId
          in: path
          required: true
          description: TheAudioDB artist ID.
          schema:
            type: integer
          example: 111239
      responses:
        "200":
          $ref: "#/components/responses/ListAlbumsResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Premium v2 API key.
  parameters:
    SearchQuery:
      name: query
      in: path
      required: true
      description: Artist search text.
      schema:
        type: string
      example: coldplay
    MusicBrainzArtistId:
      name: musicBrainzId
      in: path
      required: true
      description: MusicBrainz artist ID.
      schema:
        type: string
      example: cc197bad-dc9c-440d-a5b5-d52ba2e14234
  responses:
    SearchArtistsResponse:
      description: Artist search results.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SearchArtistsResponse"
          examples:
            search:
              value:
                search:
                  - idArtist: "111239"
                    strArtist: Coldplay
                    intFormedYear: "1997"
                    strGenre: Alternative Rock
                    strCountry: United Kingdom
                    strMusicBrainzID: cc197bad-dc9c-440d-a5b5-d52ba2e14234
    SearchAlbumsResponse:
      description: Album search results.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SearchAlbumsResponse"
          examples:
            search:
              value:
                search:
                  - idAlbum: "2109615"
                    strAlbum: Parachutes
                    idArtist: "111239"
                    strArtist: Coldplay
                    intYearReleased: "2000"
    SearchTracksResponse:
      description: Track search results.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SearchTracksResponse"
          examples:
            search:
              value:
                search:
                  - idTrack: "32724183"
                    strTrack: Yellow
                    idAlbum: "2109615"
                    strAlbum: Parachutes
                    idArtist: "111239"
                    strArtist: Coldplay
    LookupArtistsResponse:
      description: Artist lookup results.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/LookupArtistsResponse"
    LookupAlbumsResponse:
      description: Album lookup results.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/LookupAlbumsResponse"
    LookupTracksResponse:
      description: Track lookup results.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/LookupTracksResponse"
    ListAlbumsResponse:
      description: List results containing album rows.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListAlbumsResponse"
          examples:
            list:
              value:
                list:
                  - idAlbum: "2109615"
                    strAlbum: Parachutes
                    idArtist: "111239"
                    strArtist: Coldplay
                    intYearReleased: "2000"
    ErrorResponse:
      description: Error response for missing or invalid API keys, invalid IDs, or no data found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missingApiKey:
              value:
                Message: Missing API key in header, sign up at https://www.theaudiodb.com/pricing
            invalidApiKey:
              value:
                Message: "Invalid Premium API key: Signup here: https://www.theaudiodb.com/pricing"
            noData:
              value:
                Message: No data found
  schemas:
    Artist:
      type: object
      description: Artist row returned by the v2 API. Lookup responses may include more fields than search responses.
      additionalProperties: true
      properties:
        idArtist:
          type:
            - string
            - integer
        strArtist:
          type:
            - string
            - "null"
        intBornYear:
          type:
            - string
            - integer
            - "null"
        intFormedYear:
          type:
            - string
            - integer
            - "null"
        strBiography:
          type:
            - string
            - "null"
        strGenre:
          type:
            - string
            - "null"
        strStyle:
          type:
            - string
            - "null"
        strCountry:
          type:
            - string
            - "null"
        strArtistThumb:
          type:
            - string
            - "null"
        strMusicBrainzID:
          type:
            - string
            - "null"
    Album:
      type: object
      description: Album row returned by the v2 API. Lookup responses may include more fields than search responses.
      additionalProperties: true
      properties:
        idAlbum:
          type:
            - string
            - integer
        strAlbum:
          type:
            - string
            - "null"
        idArtist:
          type:
            - string
            - integer
            - "null"
        strArtist:
          type:
            - string
            - "null"
        intYearReleased:
          type:
            - string
            - integer
            - "null"
        strGenre:
          type:
            - string
            - "null"
        strAlbumThumb:
          type:
            - string
            - "null"
        strDescription:
          type:
            - string
            - "null"
        strMusicBrainzID:
          type:
            - string
            - "null"
        strMusicBrainzArtistID:
          type:
            - string
            - "null"
    Track:
      type: object
      description: Track row returned by the v2 API. Lookup responses may include more fields than search responses.
      additionalProperties: true
      properties:
        idTrack:
          type:
            - string
            - integer
        strTrack:
          type:
            - string
            - "null"
        idAlbum:
          type:
            - string
            - integer
            - "null"
        strAlbum:
          type:
            - string
            - "null"
        idArtist:
          type:
            - string
            - integer
            - "null"
        strArtist:
          type:
            - string
            - "null"
        intDuration:
          type:
            - string
            - integer
            - "null"
        strGenre:
          type:
            - string
            - "null"
        strDescription:
          type:
            - string
            - "null"
        strTrackThumb:
          type:
            - string
            - "null"
        intTrackNumber:
          type:
            - string
            - integer
            - "null"
        strMusicBrainzID:
          type:
            - string
            - "null"
        strMusicBrainzAlbumID:
          type:
            - string
            - "null"
        strMusicBrainzArtistID:
          type:
            - string
            - "null"
    SearchArtistsResponse:
      type: object
      additionalProperties: false
      properties:
        search:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/Artist"
    SearchAlbumsResponse:
      type: object
      additionalProperties: false
      properties:
        search:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/Album"
    SearchTracksResponse:
      type: object
      additionalProperties: false
      properties:
        search:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/Track"
    LookupArtistsResponse:
      type: object
      additionalProperties: false
      properties:
        lookup:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/Artist"
    LookupAlbumsResponse:
      type: object
      additionalProperties: false
      properties:
        lookup:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/Album"
    LookupTracksResponse:
      type: object
      additionalProperties: false
      properties:
        lookup:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/Track"
    ListAlbumsResponse:
      type: object
      additionalProperties: false
      properties:
        list:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/Album"
    ErrorResponse:
      type: object
      additionalProperties: true
      properties:
        Message:
          type: string
