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
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.
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" } }unauthorizedMissing or empty Authorization header
forbiddenInvalid API key or insufficient tier
rate_limitedRate limit exceeded — check X-RateLimit-Reset header for retry time
invalid_bodyRequest body is not valid JSON or missing required fields
internal_errorServer 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.
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
Call POST /api/v1/connect/{service} — where service is spotify, apple-music, tidal, or deezer
Get back an authorization_url — send it to the user
User visits the URL, logs into their service, and approves access
BeatBrain stores the tokens automatically — user never logs in again
Check all connections with GET /api/v1/connect/status?end_user_id=...
All set — plan sets and start playback on their connected service
Spotify
/api/v1/connect/spotifyAuth: OAuth PKCE
Apple Music
/api/v1/connect/apple-musicAuth: MusicKit JS
Tidal
/api/v1/connect/tidalAuth: OAuth 2.1 PKCE
Deezer
/api/v1/connect/deezerAuth: OAuth
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.