API Documentation

Overview

The Brainify API provides bidirectional mapping between Spotify and MusicBrainz metadata. Convert track, album, and artist IDs between platforms or search by ISRC codes.

Base URL: https://brainify.maeisgroovy.net/api/

Authentication

All API endpoints (except /api/stats) require an API key. Include your API key in the X-API-Key header with every request.

X-API-Key: your_api_key_here

Getting an API Key: Sign up at brainify.maeisgroovy.net and generate your API key from your account dashboard.

Rate Limiting

API requests are rate limited on an hourly basis to ensure fair usage:

Free Tier: 750 requests per hour
Pro Tier: 3000 requests per hour
Enterprise Tier: 10,000 requests per hour

Rate limit information is included in response headers:

X-RateLimit-Limit: 750
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1643228400

Need higher limits? Contact us about custom enterprise plans with increased rate limits tailored to your needs.

Error Codes

Status Code	Description
`401`	Unauthorized - Missing or invalid API key
`429`	Too Many Requests - Rate limit exceeded

Endpoints

POST /api/track

Get Track Mapping

Retrieve track mappings with full album and artist information. Query by Spotify ID, MusicBrainz ID, or ISRC.

Request Body (JSON)

Parameter	Type	Required	Description
`spotify_id`	string	One of three	Spotify track ID
`mbid`	string	One of three	MusicBrainz recording ID (UUID)
`isrc`	string	One of three	International Standard Recording Code
`min_confidence`	float	No	Minimum confidence score (0.0-1.0, default: 0.0)

Example Requests

POST /api/track
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "spotify_id": "3n3Ppam7vgaVa1iaRUc9Lp"
}

POST /api/track
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "mbid": "57887697-5c9f-49e9-90d8-a0f518340b6c"
}

POST /api/track
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "isrc": "USRC17607839",
  "min_confidence": 0.8
}

Response

[
  {
    "id": 1,
    "spotify_id": "3n3Ppam7vgaVa1iaRUc9Lp",
    "mbid": "57887697-5c9f-49e9-90d8-a0f518340b6c",
    "isrc": "USRC17607839",
    "match_method": "isrc",
    "confidence": 1.0,
    "album_id": 1,
    "artist_id": 1,
    "created_at": "2026-01-25T10:27:11.531806",
    "updated_at": "2026-01-25T10:27:11.531806",
    "album": {
      "id": 1,
      "spotify_album_id": "4aawyAB9vmqN3uQ7FjRGTy",
      "mb_releasegroup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "artist_id": 1,
      "created_at": "2026-01-25T10:27:11.531806",
      "updated_at": "2026-01-25T10:27:11.531806"
    },
    "artist": {
      "id": 1,
      "spotify_artist_id": "0LcJLqbBmaGUft1e9Mm8HV",
      "mb_artist_id": "56a55378-f155-48de-80a5-d80104221267",
      "created_at": "2026-01-25T10:27:11.531806",
      "updated_at": "2026-01-25T10:27:11.531806"
    }
  }
]

POST /api/album

Get Album Mapping

Retrieve album mappings with artist information. Query by Spotify album ID or MusicBrainz release group ID.

Request Body (JSON)

Parameter	Type	Required	Description
`spotify_id`	string	One required	Spotify album ID
`mbid`	string	One required	MusicBrainz release group ID (UUID)

Example Requests

POST /api/album
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "spotify_id": "4aawyAB9vmqN3uQ7FjRGTy"
}

POST /api/album
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "mbid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response

[
  {
    "id": 1,
    "spotify_album_id": "4aawyAB9vmqN3uQ7FjRGTy",
    "mb_releasegroup_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "artist_id": 1,
    "created_at": "2026-01-25T10:27:11.531806",
    "updated_at": "2026-01-25T10:27:11.531806",
    "artist": {
      "id": 1,
      "spotify_artist_id": "0LcJLqbBmaGUft1e9Mm8HV",
      "mb_artist_id": "56a55378-f155-48de-80a5-d80104221267",
      "created_at": "2026-01-25T10:27:11.531806",
      "updated_at": "2026-01-25T10:27:11.531806"
    }
  }
]

POST /api/artist

Get Artist Mapping

Retrieve artist mappings between Spotify and MusicBrainz.

Request Body (JSON)

Parameter	Type	Required	Description
`spotify_id`	string	One required	Spotify artist ID
`mbid`	string	One required	MusicBrainz artist ID (UUID)

Example Requests

POST /api/artist
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "spotify_id": "0LcJLqbBmaGUft1e9Mm8HV"
}

POST /api/artist
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "mbid": "56a55378-f155-48de-80a5-d80104221267"
}

Response

[
  {
    "id": 1,
    "spotify_artist_id": "0LcJLqbBmaGUft1e9Mm8HV",
    "mb_artist_id": "56a55378-f155-48de-80a5-d80104221267",
    "created_at": "2026-01-25T10:27:11.531806",
    "updated_at": "2026-01-25T10:27:11.531806"
  }
]

GET /api/stats

Database Statistics

Get statistics about the mapping database. No authentication required.

Response

{
  "total_artists": 125000,
  "total_albums": 450000,
  "total_mappings": 2500000,
  "average_confidence": 0.87
}

Error Handling

Status Code	Description
`400`	Bad request - missing required parameters
`401`	Unauthorized - missing or invalid API key
`404`	No mappings found for the given ID
`429`	Too many requests - rate limit exceeded
`500`	Internal server error

Examples

Python

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://brainify.maeisgroovy.net/api"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Find MusicBrainz ID from Spotify track
response = requests.post(
    f"{BASE_URL}/track",
    json={"spotify_id": "3n3Ppam7vgaVa1iaRUc9Lp"},
    headers=headers
)
data = response.json()
print(f"MusicBrainz ID: {data[0]['mbid']}")

# Find Spotify ID from MusicBrainz recording
response = requests.post(
    f"{BASE_URL}/track",
    json={"mbid": "57887697-5c9f-49e9-90d8-a0f518340b6c"},
    headers=headers
)
data = response.json()
print(f"Spotify ID: {data[0]['spotify_id']}")

# Search by ISRC with confidence filter
response = requests.post(
    f"{BASE_URL}/track",
    json={
        "isrc": "USRC17607839",
        "min_confidence": 0.9
    },
    headers=headers
)
for track in response.json():
    print(f"Match: {track['spotify_id']} -> {track['mbid']}")
    print(f"Confidence: {track['confidence']}")

# Check rate limit headers
if 'X-RateLimit-Remaining' in response.headers:
    print(f"Requests remaining: {response.headers['X-RateLimit-Remaining']}")
    print(f"Limit resets at: {response.headers['X-RateLimit-Reset']}")

JavaScript

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://brainify.maeisgroovy.net/api';

const headers = {
  'X-API-Key': API_KEY,
  'Content-Type': 'application/json'
};

// Find Spotify album from MusicBrainz release group
const response = await fetch(`${BASE_URL}/album`, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify({
    mbid: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  })
});
const data = await response.json();
console.log('Spotify Album ID:', data[0].spotify_album_id);

// Get artist mapping
const artistRes = await fetch(`${BASE_URL}/artist`, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify({
    spotify_id: '0LcJLqbBmaGUft1e9Mm8HV'
  })
});
const artist = await artistRes.json();
console.log('MusicBrainz Artist ID:', artist[0].mb_artist_id);

// Error handling
try {
  const res = await fetch(`${BASE_URL}/track`, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({ spotify_id: 'invalid_id' })
  });
  
  if (res.status === 401) {
    console.error('Invalid API key');
  } else if (res.status === 429) {
    const resetTime = res.headers.get('X-RateLimit-Reset');
    console.error('Rate limit exceeded. Resets at:', new Date(resetTime * 1000));
  } else if (!res.ok) {
    console.error('API error:', res.status);
  }
} catch (error) {
  console.error('Request failed:', error);
}

cURL

# Track by Spotify ID
curl -X POST "https://brainify.maeisgroovy.net/api/track" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"spotify_id": "3n3Ppam7vgaVa1iaRUc9Lp"}'

# Track by MusicBrainz ID
curl -X POST "https://brainify.maeisgroovy.net/api/track" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"mbid": "57887697-5c9f-49e9-90d8-a0f518340b6c"}'

# Track by ISRC with confidence filter
curl -X POST "https://brainify.maeisgroovy.net/api/track" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"isrc": "USRC17607839", "min_confidence": 0.8}'

# Album by MusicBrainz ID
curl -X POST "https://brainify.maeisgroovy.net/api/album" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"mbid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

# Artist by Spotify ID
curl -X POST "https://brainify.maeisgroovy.net/api/artist" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"spotify_id": "0LcJLqbBmaGUft1e9Mm8HV"}'

# Stats (no auth required)
curl "https://brainify.maeisgroovy.net/api/stats"

Response Fields

Match Methods

The match_method field indicates how the mapping was determined:

isrc - Exact ISRC code match
acoustic_fingerprint - Matched via audio fingerprinting
metadata_fuzzy - Fuzzy matching on track/artist/album names
manual - Manually verified mapping

Confidence Scores

Confidence values range from 0.0 to 1.0:

1.0 - Exact match (ISRC or manual verification)
0.8-0.99 - High confidence match
0.6-0.79 - Medium confidence match
0.0-0.59 - Low confidence match