Recoup

Get started with Recoup.

API REFERENCE

Songs by ISRC

On this page
GET/api/apple/songs

Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per requested ISRC, so a recording that Apple does not carry comes back explicitly as found: false rather than being omitted. Complements GET /api/spotify/search, which reaches ISRCs only through a fuzzy isrc: search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (upc, record_label, copyright) that Spotify does not expose.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/apple/songs?isrc=DEH742611917%2CTCAEC1931080' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request GET \
  --url 'https://api.recoupable.dev/api/apple/songs'

Parameters

Query parameters

isrcstringrequired

One or more ISRCs, comma-separated. Case-insensitive; each must match the 12-character ISRC format (two-letter country code, three-character registrant code, two-digit year, five-digit designation). Maximum 25 per request.

storefrontstring

Apple Music storefront to search, as a two-letter country code. Availability is territory-specific, so a recording present in one storefront may be absent from another.

Default: "us"

Responses

200Lookup completed. One entry per requested ISRC, in the order requested.

application/json

statusstring · enum

Status of the request

Values: "success"

storefrontstring

The storefront the lookup ran against

Example: "us"

resultsarray<AppleIsrcResult>

One entry per requested ISRC, in the order requested

Item properties for results
isrcstring

The requested ISRC, uppercased

Example: "DEH742611917"

foundboolean

Whether Apple Music carries at least one recording with this ISRC in the requested storefront

Example: true

songsarray<AppleSong>

Every recording Apple returns for this ISRC. Usually one, but the same recording can appear on several releases (compilations, anniversary editions), each with its own song id.

Item properties for songs
idstring

Apple Music catalog song id

Example: "1894880802"

isrcstring

Example: "DEH742611917"

namestring

Example: "Steady Box Fan White Noise (Extended Mix)"

artist_namestring

Display credit as Apple renders it, which may combine several artists

Example: "Sleep Sounds & Sleepy Buddy"

composer_namestringnullable

Example: "Zachary Kubilus"

album_namestring

Example: "Box Fan All Night"

release_datestringnullable

Example: "2026-05-01"

format: date

duration_msinteger

Example: 124001

track_numberintegernullable

Example: 6

disc_numberintegernullable

Example: 1

genre_namesarray<string>

Example: ["New Age","Music","Worldwide"]

Item properties for genre_names

string

has_lyricsboolean

Example: false

is_apple_digital_masterboolean

Example: false

audio_variantsarray<string>

Delivery formats available, for example lossless, lossy-stereo, dolby-atmos

Example: ["lossless","lossy-stereo"]

Item properties for audio_variants

string

urlstring

Public Apple Music page for the recording

Example: "https://music.apple.com/us/album/steady-box-fan-white-noise-extended-mix/1894880796?i=1894880802"

artwork_urlstringnullable

Artwork template URL. Substitute {w} and {h} with the pixel dimensions you want.

Example: "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/d5/d1/12/d5d112cd-19f8-6cf7-b048-b2f94c75fefd/4065328882161.png/{w}x{h}bb.jpg"

preview_urlstringnullable

30-second AAC preview

Example: "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview211/v4/56/64/02/56640222-1893-38a9-e25f-9869aa117282/mzaf_15389777242743919344.plus.aac.p.m4a"

albumobjectnullable

The release this recording appears on. Carries the rights metadata Apple exposes and Spotify does not.

Properties for album
idstring

Example: "1894880796"

namestring

Example: "Box Fan All Night"

upcstringnullable

Example: "4065328882161"

record_labelstringnullable

Example: "Sleep Sounds"

release_datestringnullable

Example: "2026-05-01"

format: date

track_countintegernullable

Example: 20

is_singleboolean

Example: false

is_compilationboolean

Example: false

is_completeboolean

Whether every track on the release is available in this storefront

Example: true

urlstring

Example: "https://music.apple.com/us/album/box-fan-all-night/1894880796"

400Bad request - isrc missing, malformed, or over the 25-ISRC limit, or an unknown storefront

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Human-readable error message

400 example
{
  "status": "error",
  "error": "isrc must be a valid ISRC: NOTANISRC"
}

401Unauthorized - missing or invalid credentials

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Human-readable error message

401 example
{
  "status": "error",
  "error": "Exactly one of x-api-key or Authorization must be provided"
}

500Internal server error, including a failure to reach the Apple Music API

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Human-readable error message

500 example
{
  "status": "error",
  "error": "Failed to reach the Apple Music API"
}

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download social.json
View operation source
json
{
  "operationId": "getAppleSongs",
  "description": "Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per **requested** ISRC, so a recording that Apple does not carry comes back explicitly as `found: false` rather than being omitted. Complements `GET /api/spotify/search`, which reaches ISRCs only through a fuzzy `isrc:` search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (`upc`, `record_label`, `copyright`) that Spotify does not expose.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "isrc",
      "in": "query",
      "description": "One or more ISRCs, comma-separated. Case-insensitive; each must match the 12-character ISRC format (two-letter country code, three-character registrant code, two-digit year, five-digit designation). Maximum 25 per request.",
      "required": true,
      "schema": {
        "type": "string",
        "example": "DEH742611917,TCAEC1931080"
      }
    },
    {
      "name": "storefront",
      "in": "query",
      "description": "Apple Music storefront to search, as a two-letter country code. Availability is territory-specific, so a recording present in one storefront may be absent from another.",
      "required": false,
      "schema": {
        "type": "string",
        "default": "us",
        "example": "gb"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Lookup completed. One entry per requested ISRC, in the order requested.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AppleSongsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - `isrc` missing, malformed, or over the 25-ISRC limit, or an unknown `storefront`",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AppleErrorResponse"
          },
          "example": {
            "status": "error",
            "error": "isrc must be a valid ISRC: NOTANISRC"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AppleErrorResponse"
          },
          "example": {
            "status": "error",
            "error": "Exactly one of x-api-key or Authorization must be provided"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error, including a failure to reach the Apple Music API",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AppleErrorResponse"
          },
          "example": {
            "status": "error",
            "error": "Failed to reach the Apple Music API"
          }
        }
      }
    }
  }
}