Developer Portal

65 tools. 7 sources. 15 dimensions.
One intelligence layer.

Give your users a world-class music experience across Spotify, Apple Music, Tidal, and Deezer. BeatBrain is a product-neutral music intelligence layer with contextual planning, playback control, and MCP auto-discovery.

Get an API Key

For Agents (Programmatic)

Your agent can self-provision a key via the public POST /api/v1/register endpoint or the MCP register_agent tool. No pre-existing auth required. Returns a sandbox-tier key (50 req/hr) immediately.

curl -X POST /api/v1/register \
  -d '{ "email": "dev@co.com",
        "agent_name": "my-agent" }'

For Developers (Dashboard)

Sign in with your email to manage keys, view usage, and upgrade tiers. Free tier: 100 req/hr. Pro: 10K/hr. Enterprise: unlimited.

Composable Primitives

Interpret

Context + sensors → musical scene

Search

Context-aware discovery

Plan Set

Energy arcs + harmonic flow

Playback

Spotify · Apple Music · Tidal · Deezer

Resolve

Cross-service track matching

Feedback

Taste genome + collaborative

Enrich

7 knowledge sources fused

MCP

66 auto-discoverable tools

Why BeatBrain

It Gets Smarter

Every like, skip, and re-request feeds the taste genome. The more your users listen, the better BeatBrain gets — creating a compounding advantage for your agent.

Context, Not Just Genre

BeatBrain understands the moment — heart rate, weather, time of day, who's in the room. 15 dimensions of scoring mean your users hear the right music, not just the right genre.

Real Music Knowledge

Your agent can answer "who's similar to Khruangbin?" with real data from Last.fm + Soundcharts — streaming stats, chart placements, audience-backed similarities. No hallucination.

Quick Start

agent.ts
import { BeatBrain } from '@beatbrain/sdk'

const bb = new BeatBrain(process.env.BEATBRAIN_KEY!)

// 1. Connect user's streaming service (one-time)
// Supports: 'spotify' | 'apple_music' | 'tidal' | 'deezer'
const { authorization_url } = await bb.connect({
  service: 'spotify', // or 'apple_music', 'tidal', 'deezer'
  end_user_id: 'user_123',
  redirect_uri: 'https://yourapp.com/callback'
})

// 2. Plan a set from context
const set = await bb.planSet({
  prompt: 'focused coding at 2am, rain outside',
  end_user_id: 'user_123',
  track_count: 8,
  sensors: { heart_rate: 68, stress_level: 0.3 },
  include_explanation: true
})

// 3. Start playback on their connected service
await bb.play({
  end_user_id: 'user_123',
  session_id: set.session_id
})

// 4. Context changes? Music adapts
await bb.updateContext(set.session_id, {
  prompt: 'wrapping up, winding down',
  sensors: { stress_level: 0.1 }
})

// 5. Report feedback — taste genome learns
await bb.feedback(set.session_id, {
  signals: [{ type: 'like', track_id: set.tracks[0].id }],
  context: { prompt: 'coding', energy: 0.35 }
})

API Reference

All v1 endpoints require Authorization: Bearer <api_key> header (except /api/v1/register which is public). Full OpenAPI spec at /api/v1/openapi.

POST/api/v1/sets/plan

The crown jewel — interprets context, searches streaming catalog, scores across 15 dimensions, and plans a complete set with energy arcs. Returns track URIs for any connected service with per-track explanations.

{
  "prompt": "focused coding at 2am, rain outside",
  "end_user_id": "user_123",
  "track_count": 8,
  "energy_curve": "sustaining",
  "sensors": {
    "heart_rate": 68,
    "stress_level": 0.3,
    "location_type": "home"
  },
  "include_explanation": true
}

Authentication

API key via Authorization: Bearer <key> header. Keys are tiered (sandbox / free / pro / enterprise) with per-key rate limits. Get a key via the dashboard or POST /api/v1/register.

Rate Limits

Sandbox: 50 req/hr. Free: 100/hr. Pro: 10K/hr. Enterprise: unlimited. Redis-backed sliding window. Every response includesX-RateLimit-Remaining andX-RateLimit-Reset headers.

Discovery

/api/v1/openapi for client generation./api/v1/mcp for LLM auto-discovery. Your agent finds BeatBrain on its own.

Error Responses

All errors return a consistent JSON structure:

{ "error": { "code": "error_code", "message": "Human-readable description" } }
401
unauthorized

Missing or empty Authorization header

403
forbidden

Invalid API key or insufficient tier

429
rate_limited

Rate limit exceeded — check X-RateLimit-Reset header for retry time

400
invalid_body

Request body is not valid JSON or missing required fields

500
internal_error

Server error — retry with exponential backoff

Model Context Protocol (MCP) — 66 Tools

BeatBrain is auto-discoverable via MCP. Point any MCP-compatible agent (OpenAI, Anthropic, Google, custom) at /api/v1/mcp and it discovers 66 tools automatically — context interpretation, set planning, explicit playback start, cross-service playback, memory/personality context retrieval, quality metrics, track enrichment, sharing, session history, library management, and more.

Agents can even self-register via MCP without a pre-existing key — callregister_agentwith your email to bootstrap.

play_musicstart_playbackplan_setsearch_trackscontrol_playbackexplore_musicqueue_trackssave_to_libraryget_share_linkget_session_historyget_user_contextget_user_memoriesget_quality_metricsupdate_contextreport_feedbackconnect_streaming_serviceregister_agentget_listening_statsget_session_details+ 41 more

Streaming Service Connections

BeatBrain supports Spotify, Apple Music, Tidal, and Deezer. Users connect once via OAuth — your agent handles the flow. Each service has different playback capabilities.

Universal connection flow

1

Call POST /api/v1/connect/{service}where service is spotify, apple-music, tidal, or deezer

2

Get back an authorization_urlsend it to the user

3

User visits the URL, logs into their service, and approves access

4

BeatBrain stores the tokens automaticallyuser never logs in again

5

Check all connections with GET /api/v1/connect/status?end_user_id=...

6

All setplan sets and start playback on their connected service

Spotify

/api/v1/connect/spotify

Auth: OAuth PKCE

Full remote playback control
Device selection & transfer
BeatBrain Web Player
Real-time playback state

Apple Music

/api/v1/connect/apple-music

Auth: MusicKit JS

BeatBrain Web Player
Playlist creation & management
Library integration
Recently played history

Tidal

/api/v1/connect/tidal

Auth: OAuth 2.1 PKCE

Deep links to Tidal player
Playlist creation & management
Real-time playlist updates
HiFi audio quality

Deezer

/api/v1/connect/deezer

Auth: OAuth

Coming soon — pending developer app approval
Connection flow wired
Playlist creation (when active)
Deep links to Deezer player

Capability matrix

Capability
Remote playback control
BeatBrain Web Player
Playlist creation
Real-time playlist updates
Device selection
Real-time playback state
Deep links

Deezer is wired but pending developer app approval. Capabilities will be enabled once approved.

Ship music intelligence today.

Get your API key, point your agent at the MCP endpoint, and watch it discover 65 music tools automatically. First set planned in under 5 minutes.