Developer Portal
23 tools. 7 sources. 6 services.
One intelligence layer.
Composable API primitives that turn any agent into a context-aware music brain. Interpret signals, fuse knowledge, plan sets with energy arcs, resolve tracks across control playback on any Spotify device, and learn from every session. Auto-discoverable via MCP.
Composable Primitives
Interpret
Context → musical scene
Search
Context-aware discovery
Plan Set
Energy arcs + harmonic flow
Playback
Any Spotify device
Resolve
Cross-service track matching
Feedback
Taste genome + collaborative
Enrich
7 knowledge sources fused
MCP
23 auto-discoverable tools
Quick Start
import { BeatBrain } from '@beatbrain/sdk'
const bb = new BeatBrain(process.env.BEATBRAIN_KEY!)
// 1. Connect user's Spotify account (one-time)
const { authorization_url } = await bb.connectSpotify({
end_user_id: 'user_123',
redirect_uri: 'https://yourapp.com/callback'
})
// 2. Plan a set from context — finds tracks on Spotify
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 Spotify
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].spotify_id }],
context: { prompt: 'coding', energy: 0.35 }
})API Reference
All v1 endpoints require X-API-Key: <api_key> header. Full OpenAPI spec at /api/v1/openapi.
The crown jewel — interprets context, searches streaming catalog, scores across 10 dimensions, and plans a complete set with energy arcs. Returns Spotify URIs 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 auth via X-API-Key header. Keys are tiered (free / pro / enterprise) with rate limits. Register an agent to get started.
Rate Limits
Free: 100 req/hr. Pro: 10K/hr. Enterprise: unlimited. Redis-backed sliding window. Rate headers on every response.
Discovery
/api/v1/openapi for client generation./api/v1/mcp for LLM auto-discovery. Your agent finds BeatBrain on its own.
Model Context Protocol (MCP) — 23 Tools
BeatBrain is auto-discoverable via MCP. Point any MCP-compatible agent (OpenAI, Anthropic, Google, custom) at /api/v1/mcp and it discovers 23 tools automatically — context interpretation, set planning, cross-service playback, track resolution, knowledge enrichment, collaborative recommendations, trending, and more. Zero manual integration.