API Documentation

Song-level audio analysis, emotional indices, and color-as-search. Every field backed by real audio science.

Overview

The MusicArk API provides programmatic access to the same song intelligence that powers musicark.dev: full audio DNA (BPM, key, spectral profile, energy curves), human-verified emotional dimensions, and color identity derived from audio. All data is tied to published songs in the Ark.

  • Base URL: https://admin.musicark.dev/api/v1
  • Authentication: API key required on every request. Send as Authorization: Bearer YOUR_KEY or ?api_key=YOUR_KEY.

Authentication

Pass your API key in one of two ways:

  • Header (recommended): Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Query parameter: ?api_key=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Missing or invalid keys receive 401. Over-limit keys receive 429.

Rate limiting

Every response includes rate-limit headers:

  • X-RateLimit-Limit — your monthly call limit
  • X-RateLimit-Remaining — calls left this month
  • X-RateLimit-Reset — ISO date when the counter resets (first of next month)

When you exceed your limit, the API returns 429 Too Many Requests with message Rate limit exceeded. Resets first of next month.

Endpoints

GET /v1/songs

Paginated list of published songs.

Param Type Description
limitnumberDefault 20, max 100
offsetnumberPagination offset
sortstringpublished_at | title | artist
tempo_feelstringFilter by MusicArk tempo feel (optional)
energy_shapestringFilter by energy shape (optional)

Tempo Feel — MusicArk's 12-word vocabulary for how music moves. Derived from BPM, energy, and cultural context.

Energy Shape — 8-word vocabulary for a song's energy over time. Computed from the energy curve. 

curl -H "Authorization: Bearer YOUR_API_KEY" "https://admin.musicark.dev/api/v1/songs?tempo_feel=groove"
curl -H "Authorization: Bearer YOUR_API_KEY" "https://admin.musicark.dev/api/v1/songs?energy_shape=build"
curl -H "Authorization: Bearer YOUR_API_KEY" "https://admin.musicark.dev/api/v1/songs?limit=5&sort=title"
{
  "data": [{ "id": "...", "title": "...", "artist": "...", "color_hex": "...", "bpm": 120, ... }],
  "meta": { "total": 42, "limit": 5, "offset": 0, "has_more": true },
  "error": null
}

GET /v1/songs/:id

Full song profile by ID (nested: song, color, temporal, harmonic, emotional, etc.).

curl -H "Authorization: Bearer YOUR_API_KEY" "https://admin.musicark.dev/api/v1/songs/SONG_UUID"
{
  "data": {
    "song": { "id": "...", "title": "...", "artist": "...", "slug": "...", "published_at": "..." },
    "color": { "hex": "...", "oklch_lightness": 0.5, ... },
    "temporal": { "bpm": 120, ... },
    "emotional": { "valence": 650, "arousal": 400, "nostalgia_index": 300, "dominant_emotion": "..." },
    ...
  },
  "meta": {},
  "error": null
}

Response shape

Excerpt — data.temporal and derived tier-2 fields returned on the full profile.

temporal
Field Type Description
tempo_marking string Italian tempo marking (e.g., "moderato", "allegro")
energy_shape string Energy shape: steady | build | rise | peak | wave | cascade | bloom | burst
Derived (Tier 2)
Field Type Description
tempo_feel string MusicArk tempo feel: stillness | drift | sway | lean | groove | bounce | stride | drive | surge | rush | blitz | fury
tempo_feel_confidence number Confidence of the assignment (0–1)

GET /v1/search/text

Full-text search by title, artist, or album.

Param Type Description
qstringRequired. Search query
max_resultsnumberDefault 20, max 100
 
curl -H "Authorization: Bearer YOUR_API_KEY" "https://admin.musicark.dev/api/v1/search/text?q=bloom"

GET /v1/search/color

Color proximity search (OKLCH).

Param Type Description
hnumberRequired. Hue 0–360
lnumberLightness 0–1, default 0.5
cnumberChroma 0–0.4, default 0.15
max_resultsnumberDefault 20
max_distancenumberDefault 50
 
curl -H "Authorization: Bearer YOUR_API_KEY" "https://admin.musicark.dev/api/v1/search/color?h=280&l=0.5&c=0.15"

GET /v1/search/emotional

Filter by emotional dimensions (1–1000). All min/max params optional.

Params: min_valence, max_valence, min_arousal, max_arousal, min_nostalgia, max_nostalgia, min_melancholy, max_melancholy, min_sensuality, max_sensuality, min_triumph, max_triumph, min_mystery, max_mystery, min_inspirational, max_inspirational, max_results (default 20). 

curl -H "Authorization: Bearer YOUR_API_KEY" "https://admin.musicark.dev/api/v1/search/emotional?min_valence=500&max_arousal=600"

API access levels

Response fields depend on your key's tier:

  • Free: Basic fields only — id, title, artist, album, release_year, slug, color_hex, bpm, key, mode, duration_seconds, dominant_emotion, published_at.
  • Pro: Everything in Free plus full color (OKLCH), temporal, harmonic, pitch, timbre, energy (including danceability), spatial, arrangement, and AI Analysis derived scalars.
  • Enterprise: Everything in Pro plus emotional (valence, arousal, nostalgia_index, melancholy_index, sensuality_index, triumph_index, mystery_index, inspirational_quality, dominant_emotion), contextual, narrative, cultural, and curves (energy_curve, brightness_curve, melody_contour, harmonic_tension_curve).

Pricing

  • Free: 100 calls/month.
  • Pro: $29/month, 5,000 calls/month.
  • Enterprise: Custom limits and SLA.

Coming soon — join the waitlist: api@musicark.dev.