AudD Recognition API

openapi: 3.2.0
info:
  title: AudD Music Recognition API
  version: 1.4.4
  description: 'The AudD music recognition API identifies songs from short audio clips

    (`api.audd.io/`), large audio/video files (`enterprise.audd.io/`), and

    real-time audio streams (callback or longpoll based on `api.audd.io/`).


    This OpenAPI document is the canonical contract for the API. Every

    official AudD SDK validates its parser against the fixtures shipped

    alongside this spec.


    Documentation: https://docs.audd.io

    Get an api_token: https://dashboard.audd.io

    Support: api@audd.io'
  contact:
    name: AudD API Support
    email: api@audd.io
    url: https://audd.io
  license:
    name: MIT
    identifier: MIT
servers:
- url: https://api.audd.io
  description: Standard recognition, streams and custom catalog endpoints.
- url: https://enterprise.audd.io
  description: Enterprise large-file recognition endpoint.
security:
- api_token_form: []
- api_token_query: []
tags:
- name: Recognition
paths:
  /:
    post:
      operationId: recognize
      summary: Identify a song from an audio clip (the first 12 seconds are analyzed; ≤10 MB)
      description: 'Standard music recognition. Send a file directly (multipart) or pass

        a URL the AudD server downloads.


        Only the first 12 seconds of the audio are analyzed. To recognize music

        beyond the first 12 seconds of a file, use the enterprise endpoint

        (`POST https://enterprise.audd.io/`), which scans the whole file.'
      tags:
      - Recognition
      servers:
      - url: https://api.audd.io
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties: true
              required:
              - api_token
              properties:
                api_token:
                  type: string
                  description: From https://dashboard.audd.io.
                url:
                  type: string
                  format: uri
                  description: HTTPS URL of the audio file. One of `url`, `file`, or `audio` is required.
                file:
                  type: string
                  format: binary
                  description: Multipart file upload. One of `url`, `file`, or `audio` is required.
                audio:
                  type: string
                  description: Base64-encoded audio. Discouraged; limited support.
                return:
                  type: string
                  description: 'Comma-separated metadata identifiers. Valid values:

                    `apple_music`, `spotify`, `deezer`, `napster`, `musicbrainz`.

                    '
                  example: apple_music,spotify
                market:
                  type: string
                  description: ISO country code for Apple Music / iTunes / Spotify regional results. Default `us`.
                  example: us
      responses:
        '200':
          description: 'Recognition processed. The response is a `success` payload (with

            `result` either populated or null when no match was found) or an

            `error` payload.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RecognizeSuccessResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                with_metadata:
                  summary: Public-DB match with apple_music + spotify + musicbrainz return
                  externalValue: https://raw.githubusercontent.com/AudDMusic/audd-openapi/63414c0a939be98c9ec6d9c2eb5c4c7b92b60a51/fixtures/recognize_with_metadata.json
                custom_match:
                  summary: Custom-DB match (caller's fingerprint catalog)
                  externalValue: https://raw.githubusercontent.com/AudDMusic/audd-openapi/63414c0a939be98c9ec6d9c2eb5c4c7b92b60a51/fixtures/recognize_custom_match.json
                error_invalid_token:
                  summary: Error 900 — invalid api_token
                  externalValue: https://raw.githubusercontent.com/AudDMusic/audd-openapi/63414c0a939be98c9ec6d9c2eb5c4c7b92b60a51/fixtures/error_900_invalid_token.json
                error_no_file:
                  summary: Error 700 — no file or url sent
                  externalValue: https://raw.githubusercontent.com/AudDMusic/audd-openapi/63414c0a939be98c9ec6d9c2eb5c4c7b92b60a51/fixtures/error_700_no_file.json
    get:
      operationId: recognizeGet
      summary: Same as POST recognize, but with parameters in the query string
      description: GET form of `/`. Useful for quick tests in a browser; POST is preferred.
      tags:
      - Recognition
      servers:
      - url: https://api.audd.io
      parameters:
      - in: query
        name: api_token
        required: true
        schema:
          type: string
      - in: query
        name: url
        schema:
          type: string
          format: uri
      - in: query
        name: return
        schema:
          type: string
      - in: query
        name: market
        schema:
          type: string
      responses:
        '200':
          description: Same shapes as POST.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RecognizeSuccessResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                with_metadata:
                  externalValue: https://raw.githubusercontent.com/AudDMusic/audd-openapi/63414c0a939be98c9ec6d9c2eb5c4c7b92b60a51/fixtures/recognize_with_metadata.json
  /enterprise/:
    post:
      operationId: recognizeEnterprise
      summary: Recognize music in large audio/video files (hours- or days-long)
      description: 'Enterprise endpoint. Send an HTTPS URL or a multipart file (streamed,

        no in-memory buffering needed). The endpoint chunks the audio into

        12-second segments and counts each scanned chunk as 1 request.


        SDKs default to a 1-hour read timeout for this endpoint and enable TCP

        keepalive on the transport.'
      tags:
      - Recognition
      servers:
      - url: https://enterprise.audd.io
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties: true
              required:
              - api_token
              properties:
                api_token:
                  type: string
                url:
                  type: string
                  format: uri
                file:
                  type: string
                  format: binary
                return:
                  type: string
                  description: 'Comma-separated metadata identifiers. Same as the standard

                    endpoint — but **Spotify is NOT supported** on enterprise.

                    '
                accurate_offsets:
                  type: string
                  enum:
                  - 'true'
                  - 'false'
                  description: When 'true', return per-match start/end offsets within each 12-second chunk.
                skip:
                  type: integer
                  description: Number of 12-second chunks to skip after each scanned chunk.
                every:
                  type: integer
                  description: Number of consecutive chunks to scan.
                limit:
                  type: integer
                  description: 'Upper bound on the number of chunks to recognize. **Always

                    set this in dev/test environments to control cost.**

                    '
                skip_first_seconds:
                  type: integer
                use_timecode:
                  type: string
                  enum:
                  - 'true'
                  - 'false'
                  description: 'When ''true'', use the `t`/`time_continue`/`start` URL parameter

                    of the source URL as `skip_first_seconds`. Mutually exclusive

                    with `skip_first_seconds`.

                    '
                response_type:
                  type: string
                  enum:
                  - json
                  - csv
                  description: Output format. Default json.
      responses:
        '200':
          description: Recognition processed. JSON or CSV depending on `response_type`.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/EnterpriseSuccessResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success_with_isrc_upc:
                  externalValue: https://raw.githubusercontent.com/AudDMusic/audd-openapi/63414c0a939be98c9ec6d9c2eb5c4c7b92b60a51/fixtures/enterprise_with_isrc_upc.json
                error_unauthorized:
                  externalValue: https://raw.githubusercontent.com/AudDMusic/audd-openapi/63414c0a939be98c9ec6d9c2eb5c4c7b92b60a51/fixtures/error_904_enterprise_unauthorized.json
            text/csv:
              schema:
                type: string
                description: CSV when `response_type=csv`.
components:
  schemas:
    EnterpriseMatch:
      type: object
      additionalProperties: true
      required:
      - score
      - timecode
      description: 'A single match within a 12-second chunk of an enterprise-uploaded

        file. Multiple matches per chunk indicate competing candidates;

        higher `score` is more confident.

        '
      properties:
        score:
          type: integer
          minimum: 0
          maximum: 100
        artist:
          type: string
        title:
          type: string
        album:
          type: string
        release_date:
          type: string
        label:
          type: string
        timecode:
          type: string
          pattern: ^\d{2}:\d{2}$
          description: Position in the original song (MM:SS) where the matched fragment plays.
        isrc:
          type: string
          description: Present only on enterprise-tier accounts.
        upc:
          type: string
          description: Present only on enterprise-tier accounts.
        song_link:
          type: string
          format: uri
        start_offset:
          type: integer
          description: Position (milliseconds) within the 12-second chunk where the match begins.
        end_offset:
          type: integer
          description: Position (milliseconds) within the 12-second chunk where the match ends.
    NapsterMetadata:
      type: object
      additionalProperties: true
      description: Mirror of the upstream Napster track payload. May be absent for some tracks.
      properties:
        type:
          type: string
        id:
          type: string
        index:
          type: integer
        disc:
          type: integer
        href:
          type: string
          format: uri
        playbackSeconds:
          type: integer
        isExplicit:
          type: boolean
        isStreamable:
          type: boolean
        isAvailableInHiRes:
          type: boolean
        name:
          type: string
        isrc:
          type: string
        shortcut:
          type: string
        blurbs:
          type: array
          items:
            type: string
        artistId:
          type: string
        artistName:
          type: string
        albumId:
          type: string
        albumName:
          type: string
        formats:
          type: array
          items:
            type: object
            additionalProperties: true
        previewURL:
          type: string
          format: uri
        contributors:
          type: object
          additionalProperties: true
        links:
          type: object
          additionalProperties: true
    EnterpriseChunkResult:
      type: object
      additionalProperties: true
      required:
      - songs
      - offset
      properties:
        songs:
          type: array
          items:
            $ref: '#/components/schemas/EnterpriseMatch'
        offset:
          type: string
          pattern: ^\d{2}:\d{2}$
          description: Position (MM:SS) in the submitted file at which this 12-second chunk begins.
    AppleMusicMetadata:
      type: object
      additionalProperties: true
      description: 'Mirror of the upstream Apple Music track payload. AudD passes it

        through verbatim, so SDK consumers can rely on additional fields

        appearing here as Apple ships them.

        '
      properties:
        previews:
          type: array
          items:
            type: object
            additionalProperties: true
            properties:
              url:
                type: string
                format: uri
        artwork:
          type: object
          additionalProperties: true
          properties:
            width:
              type: integer
            height:
              type: integer
            url:
              type: string
            bgColor:
              type: string
            textColor1:
              type: string
            textColor2:
              type: string
            textColor3:
              type: string
            textColor4:
              type: string
        artistName:
          type: string
        url:
          type: string
          format: uri
        discNumber:
          type: integer
        genreNames:
          type: array
          items:
            type: string
        durationInMillis:
          type: integer
        releaseDate:
          type: string
        name:
          type: string
        isrc:
          type: string
        albumName:
          type: string
        playParams:
          type: object
          additionalProperties: true
        trackNumber:
          type: integer
        composerName:
          type: string
    EnterpriseSuccessResponse:
      type: object
      additionalProperties: true
      required:
      - status
      - result
      properties:
        status:
          type: string
          const: success
        result:
          type: array
          items:
            $ref: '#/components/schemas/EnterpriseChunkResult'
        execution_time:
          type: string
          description: Wall-clock execution time on the server.
    SpotifyMetadata:
      type: object
      additionalProperties: true
      description: Mirror of the upstream Spotify track payload.
      properties:
        album:
          type: object
          additionalProperties: true
        artists:
          type: array
          items:
            type: object
            additionalProperties: true
        available_markets:
          oneOf:
          - type: array
            items:
              type: string
          - type: 'null'
        disc_number:
          type: integer
        duration_ms:
          type: integer
        explicit:
          type: boolean
        external_ids:
          type: object
          additionalProperties: true
        external_urls:
          type: object
          additionalProperties: true
        href:
          type: string
          format: uri
        id:
          type: string
        is_local:
          type: boolean
        is_playable:
          type: boolean
        linked_from:
          oneOf:
          - type: object
            additionalProperties: true
          - type: 'null'
        name:
          type: string
        popularity:
          type: integer
        track_number:
          type: integer
        type:
          type: string
        uri:
          type: string
    ErrorResponse:
      type: object
      additionalProperties: true
      required:
      - status
      - error
      properties:
        status:
          type: string
          const: error
        error:
          type: object
          required:
          - error_code
          - error_message
          additionalProperties: true
          properties:
            error_code:
              type: integer
              description: 'AudD-specific numeric error code. The SDK maps each code to a

                typed exception class (see audd-<lang>/docs/errors.md). The

                full set: 19, 20, 31337, 40, 50, 51, 100, 300, 400, 500, 600,

                601, 602, 610, 611, 700, 701, 702, 900, 901, 902, 903, 904,

                905, 906, 907, 1000.

                '
              enum:
              - 19
              - 20
              - 31337
              - 40
              - 50
              - 51
              - 100
              - 300
              - 400
              - 500
              - 600
              - 601
              - 602
              - 610
              - 611
              - 700
              - 701
              - 702
              - 900
              - 901
              - 902
              - 903
              - 904
              - 905
              - 906
              - 907
              - 1000
            error_message:
              type: string
              description: Human-readable, server-provided. Already includes any subscription-nudge appendix.
        request_params:
          type: object
          additionalProperties: true
          description: 'Server''s redacted echo of the request parameters. The api_token

            field is masked (e.g., "d***e"). Standard endpoint uses this field

            name; the enterprise endpoint uses `requested_params` (see below).

            '
        requested_params:
          type: object
          additionalProperties: true
          description: 'Same as `request_params` but with this alternate name as returned

            by the enterprise endpoint. SDKs should normalize these into one

            field on the SDK-side error object.

            '
        request_api_method:
          type: string
          description: 'Humanized echo of the API method (e.g., "Recognition", "Adding a

            stream stream", "Getting the URL for callbacks"). Informational

            only — not a programmatic discriminator.

            '
        request_http_method:
          type: string
          enum:
          - GET
          - POST
        execution_time:
          type: string
          description: Wall-clock execution time on the server (enterprise endpoint only).
        result:
          type: object
          additionalProperties: true
          description: 'For most errors, omitted. For codes 19 and 31337, the server may

            populate a "branded" result with `artist`/`title` strings — the

            SDK surfaces these on the exception''s `branded_message` field

            and does NOT expose them as a recognition result.

            '
          properties:
            artist:
              type: string
            title:
              type: string
        see api documentation:
          type: string
          format: uri
        contact us:
          type: string
          format: email
    RecognitionResult:
      type: object
      additionalProperties: true
      required:
      - timecode
      description: "A single recognition result. Shape varies by which catalog matched:\n\n* Public-DB match — fields like `artist`, `title`, `album`,\n  `release_date`, `label`, `song_link` are populated; `audio_id` is\n  absent.\n* Custom-DB match (caller's private fingerprint catalog) — only\n  `timecode` and `audio_id` are populated; the public-DB fields are\n  absent.\n\nThe SDK exposes `is_custom_match` / `is_public_match` discriminator\nhelpers and a `thumbnail_url` helper that returns\n`{song_link}?thumb` only when the host of `song_link` is `lis.tn`.\n"
      properties:
        timecode:
          type: string
          pattern: ^\d{2}:\d{2}$
          description: Position in the recognized song (MM:SS) at which the matched fragment plays.
        audio_id:
          type: integer
          description: Custom-DB match identifier. Mutually exclusive with the public-DB fields in practice.
        artist:
          type: string
        title:
          type: string
        album:
          type: string
        release_date:
          type: string
          description: Date in YYYY-MM-DD format.
        label:
          type: string
        song_link:
          type: string
          format: uri
          description: 'Canonical AudD link to the song page. For lis.tn-hosted links,

            appending `?thumb` returns the cover-art image.

            '
        apple_music:
          $ref: '#/components/schemas/AppleMusicMetadata'
        spotify:
          $ref: '#/components/schemas/SpotifyMetadata'
        deezer:
          $ref: '#/components/schemas/DeezerMetadata'
        napster:
          $ref: '#/components/schemas/NapsterMetadata'
        musicbrainz:
          type: array
          items:
            $ref: '#/components/schemas/MusicBrainzEntry'
    RecognizeSuccessResponse:
      type: object
      additionalProperties: true
      required:
      - status
      properties:
        status:
          type: string
          const: success
        result:
          oneOf:
          - $ref: '#/components/schemas/RecognitionResult'
          - type: 'null'
    MusicBrainzEntry:
      type: object
      additionalProperties: true
      description: 'Single MusicBrainz recording match. AudD returns an array of these

        because MusicBrainz''s matching often surfaces multiple candidates.

        '
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
        score:
          oneOf:
          - type: integer
          - type: string
        title:
          type: string
        length:
          type: integer
        disambiguation:
          type: string
        video:
          oneOf:
          - type: boolean
          - type: 'null'
        artist-credit:
          type: array
          items:
            type: object
            additionalProperties: true
        releases:
          type: array
          items:
            type: object
            additionalProperties: true
        isrcs:
          oneOf:
          - type: array
            items:
              type: string
          - type: 'null'
        tags:
          oneOf:
          - type: array
            items:
              type: object
              additionalProperties: true
          - type: 'null'
    DeezerMetadata:
      type: object
      additionalProperties: true
      description: Mirror of the upstream Deezer track payload. May be absent for some tracks.
      properties:
        id:
          type: integer
        readable:
          type: boolean
        title:
          type: string
        title_short:
          type: string
        title_version:
          type: string
        link:
          type: string
          format: uri
        duration:
          type: integer
        rank:
          type: integer
        explicit_lyrics:
          type: boolean
        explicit_content_lyrics:
          type: integer
        explicit_content_cover:
          type: integer
        preview:
          type: string
          format: uri
        md5_image:
          type: string
        artist:
          type: object
          additionalProperties: true
        album:
          type: object
          additionalProperties: true
        type:
          type: string
  securitySchemes:
    api_token_form:
      type: apiKey
      in: header
      name: api_token
      description: 'AudD authentication uses the `api_token` parameter sent either as a

        multipart/form-data field (POST) or as a query parameter (GET/POST).

        OpenAPI 3.1 has no first-class scheme for "auth in request body"; this

        entry documents the parameter for code generators that recognize it.

        '
    api_token_query:
      type: apiKey
      in: query
      name: api_token
      description: api_token sent as a query parameter (works on every endpoint).