kapiko API — Music Intelligence for Developers

Overview

The kapiko API lets you query curated music datasets with Spotify audio features. It's designed for music researchers, playlist builders, mood-based interfaces, and creative applications that want to work with real acoustic data.

Current data includes 100 top ambient tracks sourced from Spotify, with full audio feature analysis including energy, valence, tempo, acousticness, danceability and more.

Base URL

Base URL https://kapiko.ai/api/v1

All endpoints are relative to this base URL. The API only accepts GET requests and returns JSON.

Response Format

All responses use a consistent JSON envelope:

json

{
  "data": { ... },         // the actual payload
  "meta": {               // present on list endpoints
    "total": 100,
    "limit": 20,
    "offset": 0
  }
}

Error responses use:

json

{
  "error": "Track not found",
  "status": 404
}

Authentication

No authentication required

The API is fully open during beta. No API key, no registration. Just make requests and get data.

Rate limits

No rate limits enforced during beta. Please be reasonable — cache responses where possible.

CORS is enabled for all origins, so you can call the API directly from any browser-side JavaScript application.

Global Stats

GET /api/v1/stats Global database summary

Returns global statistics — total track and genre counts, and cross-database average audio features.

request

GET https://kapiko.ai/api/v1/stats

response

{
  "data": {
    "totals": { "tracks": 100, "genres": 1 },
    "global_averages": {
      "avg_tempo": 108.76,
      "avg_energy": 0.28,
      "avg_valence": 0.19,
      "avg_loudness": -16.72,
      "avg_acousticness": 0.703,
      "avg_danceability": 0.385,
      "avg_instrumentalness": 0.568,
      "avg_speechiness": 0.037,
      "avg_liveness": 0.121
    },
    "genres": [
      { "id": "ambient", "name": "Ambient", "track_count": 100 }
    ]
  }
}

Genres

GET /api/v1/genres List all genres

Returns all genres with their summary statistics and average audio features.

response

{
  "data": [
    {
      "id": "ambient",
      "name": "Ambient",
      "description": "Atmospheric, textural music...",
      "track_count": 100,
      "avg_tempo": 108.7634,
      "avg_energy": 0.2799,
      "avg_valence": 0.1901,
      "avg_loudness": -16.7229,
      "avg_acousticness": 0.703,
      "avg_danceability": 0.3851,
      "avg_instrumentalness": 0.5681,
      "avg_speechiness": 0.0367,
      "updated_at": "2026-03-22T00:00:00"
    }
  ],
  "meta": { "total": 1 }
}

GET /api/v1/genres/:genre Detailed genre analytics

Returns detailed analytics for a single genre including feature distributions and top artists.

Path parameters

Parameter	Description
genre	Genre ID (e.g. `ambient`)

request

GET https://kapiko.ai/api/v1/genres/ambient

response

{
  "data": {
    "genre": { "id": "ambient", "name": "Ambient", ... },
    "distributions": {
      "energy": [
        { "bucket": 0, "count": 12 },
        { "bucket": 10, "count": 8 },
        ...
      ],
      "tempo": [ ... ],
      "valence": [ ... ]
    },
    "top_artists": [
      { "artists": "Cigarettes After Sex", "track_count": 22 },
      { "artists": "Ludovico Einaudi", "track_count": 14 },
      ...
    ]
  }
}

GET /api/v1/genres/:genre/tracks Tracks in a genre

Returns paginated tracks belonging to a genre, with optional sorting.

Query parameters

Parameter	Type	Description
limit optional	integer	Tracks per page, max 100. Default: 20
offset optional	integer	Pagination offset. Default: 0
sort optional	string	Sort field: `popularity`, `energy`, `tempo`, `valence`, `name`. Default: `popularity`

request

GET https://kapiko.ai/api/v1/genres/ambient/tracks?limit=5&sort=energy

Tracks

GET /api/v1/tracks Search & browse tracks

Search and filter tracks by audio features, genre, artist and more. Results are paginated.

Query parameters

Parameter	Type	Description
genre optional	string	Filter by genre ID (e.g. `ambient`)
artist optional	string	Filter by artist name (partial match)
min_energy optional	float	Minimum energy (0.0–1.0)
max_energy optional	float	Maximum energy (0.0–1.0)
min_tempo optional	float	Minimum BPM
max_tempo optional	float	Maximum BPM
key optional	integer	Musical key (0=C, 1=C#, … 11=B)
mode optional	integer	0 = minor, 1 = major
sort optional	string	`popularity`, `energy`, `energy_asc`, `tempo`, `tempo_asc`, `valence`, `name`
limit optional	integer	Max 100. Default: 20
offset optional	integer	Default: 0

request — low energy ambient

GET https://kapiko.ai/api/v1/tracks?genre=ambient&max_energy=0.1&sort=energy_asc&limit=5

GET /api/v1/tracks/:id Single track

Returns a single track with all audio features and genre name.

Path parameters

Parameter	Description
id	Spotify track ID (e.g. `0yc6Gst2xkRu0eMLeRMGCX`)

request

GET https://kapiko.ai/api/v1/tracks/0yc6Gst2xkRu0eMLeRMGCX

response

{
  "data": {
    "id": "0yc6Gst2xkRu0eMLeRMGCX",
    "name": "Apocalypse",
    "artists": "Cigarettes After Sex",
    "album": "Cigarettes After Sex",
    "genre_id": "ambient",
    "genre_name": "Ambient",
    "popularity": 84,
    "duration_ms": 290616,
    "tempo": 94.485,
    "energy": 0.467,
    "valence": 0.182,
    "loudness": -9.013,
    "acousticness": 0.0205,
    "danceability": 0.37,
    "instrumentalness": 0.572,
    "speechiness": 0.0273,
    "liveness": 0.109,
    "key": 5,
    "mode": 1,
    "time_signature": 4,
    "source": "spotify"
  }
}

Compare

GET /api/v1/compare Track vs genre benchmark

Compares a track's audio features against a genre's average, showing the delta and a human-readable label for each feature.

Query parameters

Parameter	Type	Description
track_id	string	Spotify track ID
genre	string	Genre ID to compare against

request

GET https://kapiko.ai/api/v1/compare?track_id=0yc6Gst2xkRu0eMLeRMGCX&genre=ambient

response

{
  "data": {
    "track": { "id": "0yc6Gst2xkRu0eMLeRMGCX", "name": "Apocalypse", ... },
    "genre": { "id": "ambient", "name": "Ambient", ... },
    "comparison": {
      "energy": {
        "track_value": 0.467,
        "genre_avg": 0.2799,
        "delta": 0.1871,
        "percentile_label": "above average"
      },
      "valence": {
        "track_value": 0.182,
        "genre_avg": 0.1901,
        "delta": -0.0081,
        "percentile_label": "near average"
      },
      "tempo": { ... },
      "loudness": { ... },
      "acousticness": { ... },
      "danceability": { ... },
      "instrumentalness": { ... },
      "speechiness": { ... }
    }
  }
}

Audio Features Reference

All audio features are sourced from Spotify's audio analysis API (collected before deprecation). Values are floats unless otherwise noted.

energy

0.0–1.0. Perceptual intensity and activity. High energy = loud, fast, noisy.

valence

0.0–1.0. Musical positiveness. High = happy/euphoric; low = sad/tense.

tempo

Beats per minute (BPM). Estimated overall tempo of the track.

loudness

Overall loudness in dB. Typically –60 to 0 dB. More negative = quieter.

acousticness

0.0–1.0. Confidence that the track is acoustic. 1.0 = fully acoustic.

danceability

0.0–1.0. How suitable for dancing based on tempo, rhythm stability, beat.

instrumentalness

0.0–1.0. Predicts whether a track contains no vocals. >0.5 = likely instrumental.

speechiness

0.0–1.0. Presence of spoken words. >0.66 = likely entirely speech.

liveness

0.0–1.0. Probability of a live audience. >0.8 = likely live recording.

key

Integer 0–11. Pitch class notation: 0=C, 1=C#, 2=D, … 11=B.

mode

0 = minor, 1 = major.

time_signature

Estimated beats per bar (3, 4, 5, etc.).

Available Genres

ID	Name	Tracks	Description
ambient	Ambient	100	Atmospheric, textural music with low energy and high acousticness

More genres are coming soon — lo-fi hip hop, classical piano, post-rock, and more.

Errors

Status	Meaning
400	Bad request — missing or invalid query parameters
404	Not found — genre or track ID does not exist
500	Internal server error

kapiko Music Intelligence API

Overview

Base URL

Response Format

Authentication

No authentication required

Rate limits

Global Stats

Genres

Path parameters

Query parameters

Tracks

Query parameters

Path parameters

Compare

Query parameters

Audio Features Reference

Available Genres

Errors