Agent-ready API docs that match the live public surface.

Parameters

Security notes

• Results are filtered by the authenticated workspace user_id before query execution.
• The response intentionally exposes only published catalogue fields and pagination metadata.

Success response 200

Paginated catalogue track list.

{
  "data": [
    {
      "track_id": "9af166df-2fe2-4ea4-bec6-a4ce775f3b30",
      "isrc": "USXXX1234567",
      "title": "Song Name",
      "artist": "Artist Name",
      "album": "Release Name",
      "release_date": "2024-01-01",
      "cover_url": "https://cdn.musicengine.ai/covers/song-name.jpg",
      "spotify_track_url": "https://open.spotify.com/track/abc123",
      "full_tracking": true,
      "created_at": "2026-03-08T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

Code examples

curl --request GET 'https://musicengine.ai/api/v1/tracks?limit=50&offset=0' \
  --header 'Authorization: Bearer isrc_live_...'

const response = await fetch('https://musicengine.ai/api/v1/tracks?limit=50&offset=0', {
  headers: {
    Authorization: 'Bearer isrc_live_...',
  },
});

const payload = await response.json();

import requests

response = requests.get(
    'https://musicengine.ai/api/v1/tracks',
    headers={'Authorization': 'Bearer isrc_live_...'},
    params={'limit': 50, 'offset': 0},
)

payload = response.json()

Parameters

Security notes

• The route first authenticates the API key and then queries only the matching workspace row.
• ISRC matching is case-insensitive because the handler normalizes the path parameter to uppercase.

Success response 200

Detailed track metadata.

{
  "data": {
    "track_id": "9af166df-2fe2-4ea4-bec6-a4ce775f3b30",
    "isrc": "USXXX1234567",
    "upc": "123456789012",
    "title": "Song Name",
    "artist": "Artist Name",
    "album": "Release Name",
    "release_date": "2024-01-01",
    "duration_ms": 187000,
    "cover_url": "https://cdn.musicengine.ai/covers/song-name.jpg",
    "spotify_track_url": "https://open.spotify.com/track/abc123",
    "label": "My Label",
    "copyright_c": "(C) My Label",
    "copyright_p": "(P) My Label",
    "full_tracking": true,
    "created_at": "2026-03-08T10:00:00.000Z",
    "metadata": {}
  }
}

Code examples

curl --request GET 'https://musicengine.ai/api/v1/tracks/USXXX1234567' \
  --header 'Authorization: Bearer isrc_live_...'

const response = await fetch('https://musicengine.ai/api/v1/tracks/USXXX1234567', {
  headers: {
    Authorization: 'Bearer isrc_live_...',
  },
});

const payload = await response.json();

Parameters

Security notes

• The handler verifies the ISRC belongs to the authenticated workspace before reading analytics rows.
• days is validated to a bounded 1-365 window to avoid unbounded response generation.

Success response 200

Recent daily analytics rows for the requested ISRC.

{
  "data": {
    "isrc": "USXXX1234567",
    "historical_data": [
      {
        "date": "2024-03-20",
        "spotify_streams": 15420,
        "apple_streams": 1200
      },
      {
        "date": "2024-03-19",
        "spotify_streams": 14900,
        "apple_streams": 1185
      }
    ]
  }
}

Code examples

curl --request GET 'https://musicengine.ai/api/v1/analytics/spotify/USXXX1234567?days=7' \
  --header 'Authorization: Bearer isrc_live_...'

import requests

response = requests.get(
    'https://musicengine.ai/api/v1/analytics/spotify/USXXX1234567',
    headers={'Authorization': 'Bearer isrc_live_...'},
    params={'days': 7},
)

payload = response.json()

Parameters

No path or query parameters.

Request body

Provide a human-readable profile name and at least one cookie object. Additional cookie fields are preserved, but domain, name, and value are required.

{
  "name": "DistroKid primary session",
  "cookies": [
    {
      "domain": ".spotify.com",
      "name": "sp_dc",
      "value": "...",
      "path": "/",
      "secure": true,
      "httpOnly": true
    }
  ]
}

Security notes

• This endpoint is disabled unless cookie encryption is configured on the server.
• Payload validation enforces bounded cookie counts and sizes before any encrypted storage occurs.

Success response 201

Browser profile created and cookie payload stored in encrypted form.

{
  "success": true,
  "message": "Browser profile and securely encrypted session cookies successfully imported.",
  "profile_id": 1234,
  "name": "DistroKid primary session"
}

Code examples

curl --request POST 'https://musicengine.ai/api/v1/browser-profiles/import' \
  --header 'Authorization: Bearer isrc_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "DistroKid primary session",
    "cookies": [
      {
        "domain": ".spotify.com",
        "name": "sp_dc",
        "value": "...",
        "path": "/",
        "secure": true,
        "httpOnly": true
      }
    ]
  }'

const response = await fetch('https://musicengine.ai/api/v1/browser-profiles/import', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer isrc_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'DistroKid primary session',
    cookies: [
      {
        domain: '.spotify.com',
        name: 'sp_dc',
        value: '...',
        path: '/',
        secure: true,
        httpOnly: true,
      },
    ],
  }),
});

const payload = await response.json();

Parameters

Security notes

• All aggregate queries are parameterized with the authenticated workspace user_id.
• The route exposes a compact summary payload rather than raw internal table structures.

Success response 200

Overview stats and top performers for the requested or latest day.

{
  "success": true,
  "data": {
    "stats": {
      "total_inner_catalogue_tracks": 42,
      "has_stream_data": true,
      "days_tracked": 12
    },
    "best_tracks": [
      {
        "isrc": "USXXX1234567",
        "title": "Hit Song",
        "artist": "Main Artist",
        "streams": 1500
      }
    ],
    "best_artists": [
      {
        "artist": "Main Artist",
        "streams": 4500
      }
    ]
  }
}

Code examples

curl --request GET 'https://musicengine.ai/api/v1/catalogue/overview?date=2026-03-08' \
  --header 'Authorization: Bearer isrc_live_...'

import requests

response = requests.get(
    'https://musicengine.ai/api/v1/catalogue/overview',
    headers={'Authorization': 'Bearer isrc_live_...'},
    params={'date': '2026-03-08'},
)

payload = response.json()