{"openapi":"3.1.0","info":{"title":"BeatBrain API","version":"2.3.0","description":"Music intelligence layer for AI agents. BeatBrain provides contextual intelligence — context interpretation, set planning with energy arcs, real-time signal fusion, and a learning taste genome. Supports Spotify (full remote playback), Apple Music (database-driven BeatBrain Web Player queue via session_tracks), Tidal (playlist management + deep links), and Deezer (wired but pending developer app approval). Production controls include circuit breakers for external service protection, database-backed feature flags for safe rollback, per-session skip throttling, and playback/continuation/provider metrics. Health endpoint at /api/v1/health. MCP manifest at /api/v1/mcp includes 65 tools, including memory/personality/session-episode context retrieval and personalization quality metrics.","contact":{"name":"BeatBrain Developer Support","url":"https://getbeatbrain.com/developers"}},"servers":[{"url":"https://getbeatbrain.com","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"API key obtained from POST /api/v1/register or the developer dashboard. Pass as: Authorization: Bearer <api_key>"}},"schemas":{"QueueStrategy":{"type":"string","enum":["insert_next","append_end","replace_upcoming"],"description":"Queue placement mode. insert_next = place directly after the current track. append_end = add to the end of the queue. replace_upcoming = keep current track and replace everything after it."},"SceneDescriptor":{"type":"object","properties":{"genres":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"weight":{"type":"number"}}}},"energy":{"type":"number","minimum":0,"maximum":1},"valence":{"type":"number","minimum":0,"maximum":1},"scene_tags":{"type":"array","items":{"type":"string"}},"energy_curve":{"type":"string","enum":["building","sustaining","declining","wave","peak_valley"]},"transition_style":{"type":"string","enum":["smooth","punchy","ambient"]},"instrumental_only":{"type":"boolean"},"suggested_tracks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"artist":{"type":"string"}}},"description":"GPT-suggested track+artist pairs for precision catalog lookup"}}},"TrackResult":{"type":"object","properties":{"spotify_uri":{"type":"string"},"spotify_id":{"type":"string"},"title":{"type":"string"},"artist":{"type":"string"},"album":{"type":"string"},"album_art_url":{"type":"string"},"duration_ms":{"type":"integer"},"bpm":{"type":"number"},"key":{"type":"string"},"energy":{"type":"number"},"valence":{"type":"number"},"genre":{"type":"string"},"fit_score":{"type":"number"},"explanation":{"type":"object","nullable":true}}},"SensorData":{"type":"object","properties":{"heart_rate":{"type":"number","description":"BPM from wearable"},"stress_level":{"type":"number","minimum":0,"maximum":1},"sleep_quality":{"type":"number","minimum":0,"maximum":1},"steps_today":{"type":"integer"},"ambient_noise_db":{"type":"number"},"vehicle_speed_kmh":{"type":"number"},"device_type":{"type":"string","enum":["headphones","speaker","car","smart_display"]},"people_count":{"type":"integer"},"conversation_mood":{"type":"string","enum":["positive","negative","neutral"]},"location_type":{"type":"string","enum":["home","office","gym","car","restaurant","outdoors","commuting"]},"latitude":{"type":"number"},"longitude":{"type":"number"}}},"CalendarData":{"type":"object","properties":{"is_meeting":{"type":"boolean"},"day_of_week":{"type":"string"},"next_event_in_minutes":{"type":"integer"},"season":{"type":"string","enum":["spring","summer","fall","winter"]}}}}},"paths":{"/api/v1/health":{"get":{"operationId":"getHealth","summary":"System health check","description":"Returns system health status including circuit breaker states and feature flag values. No authentication required. Use this to monitor service availability and verify production controls are active.","tags":["Operations"],"security":[],"responses":{"200":{"description":"Health status with circuit breakers and feature flags","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"timestamp":{"type":"string","format":"date-time"},"circuit_breakers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"state":{"type":"string","enum":["closed","open","half_open"]},"failureCount":{"type":"integer"},"lastFailureTime":{"type":"integer"}}}},"feature_flags":{"type":"object","additionalProperties":{"type":"boolean"}}}}}}}}}},"/api/v1/context/interpret":{"post":{"operationId":"interpretContext","summary":"Interpret context into musical parameters","description":"Convert natural language, sensor data, calendar info, and environmental signals into structured musical parameters (SceneDescriptor). Supports weather auto-fetch from lat/lon.","tags":["Intelligence"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","example":"chill coding vibes at 2am"},"mood":{"type":"string"},"activity":{"type":"string"},"energy":{"type":"number"},"genre_hints":{"type":"array","items":{"type":"string"}},"sensors":{"$ref":"#/components/schemas/SensorData"},"calendar":{"$ref":"#/components/schemas/CalendarData"},"end_user_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Interpretation result with scene descriptor and musical parameters"}}}},"/api/v1/search":{"post":{"operationId":"searchTracks","summary":"Search tracks with BeatBrain intelligence","description":"Search Spotify, enrich results with cultural metadata, and score with 10-dimension fitness algorithm.","tags":["Discovery"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["end_user_id"],"properties":{"prompt":{"type":"string"},"mood":{"type":"string"},"activity":{"type":"string"},"energy":{"type":"number"},"genre_hints":{"type":"array","items":{"type":"string"}},"end_user_id":{"type":"string"},"limit":{"type":"integer","default":20},"include_explanation":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Scored track results"}}}},"/api/v1/recommendations":{"post":{"operationId":"getRecommendations","summary":"Get personalized recommendations","tags":["Discovery"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["end_user_id"],"properties":{"seed_tracks":{"type":"array","items":{"type":"string"}},"seed_artists":{"type":"array","items":{"type":"string"}},"prompt":{"type":"string"},"end_user_id":{"type":"string"},"limit":{"type":"integer","default":20}}}}}},"responses":{"200":{"description":"Recommended tracks"}}}},"/api/v1/sets/plan":{"post":{"operationId":"planSet","summary":"Plan a complete music set with energy arcs","description":"The crown jewel: interprets context, searches streaming catalog, enriches candidates, runs beam search with energy arcs and harmonic sequencing. Returns ordered Spotify URIs with per-track explanations.","tags":["Planning"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prompt","end_user_id"],"properties":{"prompt":{"type":"string"},"end_user_id":{"type":"string"},"track_count":{"type":"integer","default":12,"maximum":30},"energy_curve":{"type":"string","enum":["building","sustaining","declining","wave","peak_valley"]},"genre_hints":{"type":"array","items":{"type":"string"}},"avoid_genres":{"type":"array","items":{"type":"string"}},"sensors":{"$ref":"#/components/schemas/SensorData"},"calendar":{"$ref":"#/components/schemas/CalendarData"},"play_history":{"type":"array","items":{"type":"string"}},"objective":{"type":"object","description":"Optional compiled objective envelope (targets, constraints, weights)"},"planning_mode":{"type":"string","enum":["balanced","explore","safe"],"description":"Optional high-level planning strategy hint"},"determinism_seed":{"type":"integer","description":"Optional seed for deterministic orchestration controls"},"include_explanation":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Set plan with tracks, energy arc, and explanations"}}}},"/api/v1/objectives/compile":{"post":{"operationId":"compileObjective","summary":"Compile natural language into a structured objective envelope","tags":["Planning"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string"},"mood":{"type":"string"},"activity":{"type":"string"},"energy":{"type":"number"},"genre_hints":{"type":"array","items":{"type":"string"}},"avoid_genres":{"type":"array","items":{"type":"string"}},"sensors":{"$ref":"#/components/schemas/SensorData"},"calendar":{"$ref":"#/components/schemas/CalendarData"},"end_user_id":{"type":"string"},"planning_mode":{"type":"string","enum":["balanced","explore","safe"]}}}}}},"responses":{"200":{"description":"Compiled objective with targets, constraints, and weights"}}}},"/api/v1/candidates/query":{"post":{"operationId":"queryCandidates","summary":"Retrieve candidate tracks for a compiled objective","tags":["Planning"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["end_user_id"],"properties":{"end_user_id":{"type":"string"},"prompt":{"type":"string"},"objective":{"type":"object"},"limit":{"type":"integer","default":50,"maximum":100},"include_explanation":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Candidate track list with optional scene metadata"}}}},"/api/v1/candidates/score":{"post":{"operationId":"scoreCandidates","summary":"Score candidate tracks against an objective","tags":["Planning"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["objective","candidates"],"properties":{"objective":{"type":"object"},"candidates":{"type":"array","items":{"type":"object"}}}}}}},"responses":{"200":{"description":"Scored candidates with acceptance/rejection diagnostics"}}}},"/api/v1/sequences/plan":{"post":{"operationId":"planSequence","summary":"Create an ordered sequence from candidates","tags":["Planning"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["candidates"],"properties":{"objective":{"type":"object"},"candidates":{"type":"array","items":{"type":"object"}},"track_count":{"type":"integer","default":12,"maximum":50}}}}}},"responses":{"200":{"description":"Ordered candidate sequence with energy targets"}}}},"/api/v1/plans/simulate":{"post":{"operationId":"simulatePlan","summary":"Dry-run objective planning pipeline without playback","tags":["Planning"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["end_user_id"],"properties":{"end_user_id":{"type":"string"},"prompt":{"type":"string"},"objective":{"type":"object"},"planning_mode":{"type":"string","enum":["balanced","explore","safe"]},"track_count":{"type":"integer","default":12,"maximum":50}}}}}},"responses":{"200":{"description":"Simulated plan with pipeline diagnostics"}}}},"/api/v1/connect/spotify":{"post":{"operationId":"connectSpotify","summary":"Initiate Spotify OAuth connection","description":"Start Spotify PKCE OAuth flow. Returns an auth_url for the user to visit. Spotify supports full remote playback control.","tags":["Connection"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["end_user_id"],"properties":{"end_user_id":{"type":"string"},"redirect_uri":{"type":"string"}}}}}},"responses":{"200":{"description":"Authorization URL for user to visit"}}}},"/api/v1/connect/apple-music":{"post":{"operationId":"connectAppleMusic","summary":"Initiate Apple Music connection","description":"Start Apple Music authorization via MusicKit JS. Returns an auth_url for the user to visit. Apple Music supports playlist management and deep links (no server-side remote playback).","tags":["Connection"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["end_user_id"],"properties":{"end_user_id":{"type":"string"},"agent_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Authorization URL for user to visit"}}}},"/api/v1/connect/tidal":{"post":{"operationId":"connectTidal","summary":"Initiate Tidal OAuth 2.1 (PKCE) connection","description":"Start Tidal OAuth 2.1 PKCE flow. Returns an auth_url for the user to visit. Tidal supports playlist management + deep links (no embedded web player — Tidal's Web SDK only supports 30-second previews for third-party apps).","tags":["Connection"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["end_user_id"],"properties":{"end_user_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Authorization URL for user to visit"}}}},"/api/v1/connect/deezer":{"post":{"operationId":"connectDeezer","summary":"Initiate Deezer OAuth connection (coming soon)","description":"Start Deezer OAuth flow. Returns an auth_url for the user to visit. Note: Deezer developer app approval is currently pending — connection is wired but playback is not yet functional.","tags":["Connection"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["end_user_id"],"properties":{"end_user_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Authorization URL for user to visit"}}}},"/api/v1/connect/status":{"get":{"operationId":"getConnectionStatus","summary":"Check streaming service connection status","description":"Returns connection status for all supported services (Spotify, Apple Music, Tidal, Deezer) including capability flags per service.","tags":["Connection"],"parameters":[{"name":"end_user_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Connection status for all services with capability flags"}}}},"/api/v1/playback/play":{"post":{"operationId":"startPlayback","summary":"Start playback","description":"Start music playback. For Spotify: remote playback on any active device. For Apple Music: resolves tracks and writes session_tracks for the web player queue (no playlist required). For Tidal: creates a playlist and returns a deep_link (opens in Tidal's own player — no embedded web player).","tags":["Playback"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["end_user_id"],"properties":{"end_user_id":{"type":"string"},"session_id":{"type":"string"},"track_uris":{"type":"array","items":{"type":"string"}},"device_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Playback started"}}}},"/api/v1/playback/control":{"post":{"operationId":"controlPlayback","summary":"Control playback (pause, resume, skip, volume, etc.)","description":"Control active playback. Only available for services with remote playback (Spotify). Skip and previous commands are rate-limited to 3 per 10 seconds per user to prevent API overload. Throttled requests return 429. Device transfer includes automatic retry with verification. For Apple Music and Tidal, use update_context to change the vibe instead.","tags":["Playback"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["end_user_id","action"],"properties":{"end_user_id":{"type":"string"},"action":{"type":"string","enum":["pause","resume","skip","previous","seek","volume","shuffle","repeat","transfer"]},"value":{"description":"Action value: seek=ms, volume=0-100, shuffle=true/false, repeat=off/track/context"},"device_id":{"type":"string","description":"Target device ID (required for transfer action)"}}}}}},"responses":{"200":{"description":"Control acknowledged"}}}},"/api/v1/playback/state":{"get":{"operationId":"getPlaybackState","summary":"Get current playback state (+ auto-continuation)","description":"Returns current playback state. For Spotify: real-time playback state. For Apple Music: recently played (not real-time). Not available for Tidal (no playback state access). When session_id is provided, BeatBrain automatically monitors remaining tracks and plans + queues continuation tracks when ≤3 remain.","tags":["Playback"],"parameters":[{"name":"end_user_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"session_id","in":"query","schema":{"type":"string"},"description":"Enables automatic set continuation when tracks run low"}],"responses":{"200":{"description":"Current playback state with optional session/continuation info"}}}},"/api/v1/playback/queue":{"post":{"operationId":"queueTracks","summary":"Add tracks to playback queue","tags":["Playback"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["end_user_id","track_uris"],"properties":{"end_user_id":{"type":"string"},"track_uris":{"type":"array","items":{"type":"string"}},"queue_strategy":{"$ref":"#/components/schemas/QueueStrategy"}}}}}},"responses":{"200":{"description":"Tracks queued"}}}},"/api/v1/playback/devices":{"get":{"operationId":"getDevices","summary":"List playback devices with smart recommendation","description":"List available playback devices and get a smart recommendation based on activity/location context. Only available for Spotify. Apple Music and Tidal do not support device listing.","tags":["Playback"],"parameters":[{"name":"end_user_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"activity","in":"query","schema":{"type":"string"},"description":"running, workout, driving, cooking, coding, etc."},{"name":"location","in":"query","schema":{"type":"string"},"description":"home, gym, car, office, kitchen, etc."}],"responses":{"200":{"description":"Device list with smart recommendation and reasoning"}}}},"/api/v1/sessions":{"post":{"operationId":"createSession","summary":"Create a new music session","tags":["Sessions"],"responses":{"200":{"description":"Session created"}}}},"/api/v1/sessions/{sessionId}/feedback":{"post":{"operationId":"reportFeedback","summary":"Report feedback signals (like, dislike, skip, save, re_request, rating)","description":"Report user feedback for taste learning. Supports both simple format (signal_type) and full format (signals array). BeatBrain learns from every signal.","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signals":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["like","dislike","skip","save","volume_change","time_to_skip","re_request","session_rating","track_complete"]},"track_id":{"type":"string"},"value":{"type":"number"}}}},"end_user_id":{"type":"string"},"context":{"type":"object"}}}}}},"responses":{"200":{"description":"Feedback processed, taste updated"}}}},"/api/v1/sessions/{sessionId}/context":{"post":{"operationId":"updateSessionContext","summary":"Push updated context to an active session","description":"Update the musical context mid-session. BeatBrain replans the remaining set to match the new vibe.","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Context updated and set replanned"}}}},"/api/v1/sessions/{sessionId}/events":{"get":{"operationId":"sessionEvents","summary":"Server-Sent Events stream for session updates","description":"SSE stream emitting real-time events: playback.started, track.changed, set.ending (tracks_remaining, estimated_time_remaining_ms), context.updated, session.ended.","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SSE event stream","content":{"text/event-stream":{"schema":{"type":"string"}}}}}}},"/api/v1/sessions/{sessionId}/commands":{"post":{"operationId":"sendCommand","summary":"Send a command to an active session (nudge, skip, etc.)","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Command accepted"}}}},"/api/v1/register":{"post":{"operationId":"selfProvision","summary":"Self-provision an API key (no auth required)","description":"Create a new BeatBrain account and get an API key. No existing authentication needed. Returns a sandbox-tier key (50 req/hr).","tags":["Agents"],"security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","agent_name"],"properties":{"email":{"type":"string"},"agent_name":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"200":{"description":"API key and agent created"}}}},"/api/v1/agents":{"post":{"operationId":"createAgent","summary":"Create a sub-agent under your API key","tags":["Agents"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"default_context":{"type":"object"}}}}}},"responses":{"200":{"description":"Agent created"}}}},"/api/v1/agents/me":{"get":{"operationId":"getCurrentAgent","summary":"Get current agent profile and taste genome","tags":["Agents"],"parameters":[{"name":"include_taste_genome","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Agent profile with contextual taste genome"}}}},"/api/v1/agents/{agentId}/users/{endUserId}/profile":{"post":{"operationId":"submitUserProfile","summary":"Seed a user taste profile with a narrative description","description":"Send a natural language description of the user (age, lifestyle, concerts, preferences) to pre-seed their taste profile before any listening.","tags":["Agents"],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"endUserId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["narrative"],"properties":{"narrative":{"type":"string"},"structured_data":{"type":"object"}}}}}},"responses":{"200":{"description":"Profile seeded"}}}},"/api/v1/mcp":{"get":{"operationId":"getMCPManifest","summary":"MCP server manifest (tools + resources)","tags":["MCP"],"security":[],"responses":{"200":{"description":"MCP manifest with tool and resource definitions"}}}},"/api/v1/tracks/resolve":{"post":{"operationId":"resolveTracks","summary":"Resolve catalog tracks to playable Spotify URIs","tags":["Tracks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tracks","end_user_id"],"properties":{"tracks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"artist":{"type":"string"},"isrc":{"type":"string"},"external_ids":{"type":"object"}}}},"end_user_id":{"type":"string"},"target_service":{"type":"string","enum":["spotify","apple_music","tidal","deezer"]}}}}}},"responses":{"200":{"description":"Resolution results with URIs and confidence scores"}}}},"/api/v1/tracks/enrich":{"post":{"operationId":"enrichTrack","summary":"On-demand track enrichment via knowledge fusion pipeline","tags":["Tracks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","artist"],"properties":{"title":{"type":"string"},"artist":{"type":"string"},"isrc":{"type":"string"},"spotify_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Enrichment data with provenance and cross-service IDs"}}}},"/api/v1/sets/critique":{"post":{"operationId":"critiqueSet","summary":"Quality assessment of an existing set or playlist","tags":["Planning"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tracks"],"properties":{"tracks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"artist":{"type":"string"},"bpm":{"type":"number"},"key":{"type":"string"},"energy":{"type":"number"},"genre":{"type":"string"}}}},"context":{"type":"string"}}}}}},"responses":{"200":{"description":"Quality scores, suggestions, and per-track assessments"}}}},"/api/v1/transitions/plan":{"post":{"operationId":"planTransition","summary":"Plan optimal transition between two tracks","tags":["Planning"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from_track_id","to_track_id"],"properties":{"from_track_id":{"type":"string"},"to_track_id":{"type":"string"},"style":{"type":"string","enum":["smooth","cut","echo","slam"]}}}}}},"responses":{"200":{"description":"Transition plan with timing, FX, and harmonic analysis"}}}},"/api/v1/catalog/stats":{"get":{"operationId":"getCatalogStats","summary":"Get catalog statistics and genre distribution","tags":["Catalog"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Catalog statistics"}}}},"/api/v1/catalog/similar/{trackId}":{"get":{"operationId":"findSimilarTracks","summary":"Find similar tracks in the catalog using vector similarity","tags":["Catalog"],"parameters":[{"name":"trackId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Similar tracks with similarity scores"}}}},"/api/v1/skills":{"get":{"operationId":"listSkills","summary":"List available intelligence skills","tags":["Skills"],"parameters":[{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of available skills"}}}},"/api/v1/skills/{skillId}":{"get":{"operationId":"getSkill","summary":"Get skill details","tags":["Skills"],"parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Skill details"}}}},"/api/v1/skills/{skillId}/install":{"post":{"operationId":"installSkill","summary":"Install a skill for an agent","tags":["Skills"],"parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_id"],"properties":{"agent_id":{"type":"string"},"config":{"type":"object"}}}}}},"responses":{"200":{"description":"Skill installed"}}}},"/api/v1/webhooks":{"post":{"operationId":"registerWebhook","summary":"Register a webhook endpoint for event notifications","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"description":{"type":"string"}}}}}},"responses":{"200":{"description":"Webhook registered"}}},"get":{"operationId":"listWebhooks","summary":"List registered webhooks","tags":["Webhooks"],"responses":{"200":{"description":"List of webhooks"}}}},"/api/v1/intelligence/trending":{"get":{"operationId":"getTrendingTracks","summary":"Get tracks trending across all agents","tags":["Intelligence"],"parameters":[{"name":"context","in":"query","schema":{"type":"string"},"description":"Filter by context (workout, party, etc.)"},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Trending tracks with momentum scores"}}}},"/api/v1/intelligence/collaborative":{"post":{"operationId":"getCollaborativeRecommendations","summary":"Get collaborative recommendations based on track co-occurrence","tags":["Intelligence"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["track_ids"],"properties":{"track_ids":{"type":"array","items":{"type":"string"}},"context":{"type":"string"},"limit":{"type":"integer","default":20}}}}}},"responses":{"200":{"description":"Collaborative recommendations and context popularity"}}}},"/api/v1/intelligence/experiments":{"get":{"operationId":"listExperiments","summary":"List A/B experiments","tags":["Intelligence"],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","running","paused","completed"]}},{"name":"analyze","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"List of experiments with optional analysis"}}},"post":{"operationId":"createExperiment","summary":"Create a new A/B experiment","tags":["Intelligence"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","parameter_path","variants"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"parameter_path":{"type":"string"},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"value":{},"weight":{"type":"number"}}}},"traffic_pct":{"type":"number","default":0.1}}}}}},"responses":{"200":{"description":"Created experiment"}}}},"/api/v1/intelligence/health":{"get":{"operationId":"getCatalogHealth","summary":"Get catalog health and quality assurance metrics","tags":["Intelligence"],"parameters":[{"name":"refresh","in":"query","schema":{"type":"boolean"},"description":"Force fresh computation"}],"responses":{"200":{"description":"Health snapshot with gaps, quality scores, and recent issues"}}}},"/api/v1/batch":{"post":{"operationId":"batchOperations","summary":"Execute multiple API operations in a single call","tags":["Batch"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["operations"],"properties":{"operations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"},"body":{"type":"object"}}}}}}}}},"responses":{"200":{"description":"Array of operation results"}}}},"/api/v1/stats/listening":{"get":{"operationId":"getListeningStats","summary":"Get user listening statistics","description":"Returns Wrapped-style listening stats: total sessions, tracks, hours, top genres, top artists, skip rate, new discoveries, most active day/time.","tags":["Insights"],"parameters":[{"name":"end_user_id","in":"query","required":true,"schema":{"type":"string"},"description":"User identifier"},{"name":"time_range","in":"query","schema":{"type":"string","enum":["this_week","this_month","all_time"],"default":"this_week"},"description":"Time range for stats"}],"responses":{"200":{"description":"Listening statistics","content":{"application/json":{"schema":{"type":"object","properties":{"time_range":{"type":"string"},"total_sessions":{"type":"integer"},"total_tracks_played":{"type":"integer"},"estimated_listening_hours":{"type":"number"},"skip_rate":{"type":"number"},"top_genres":{"type":"array","items":{"type":"object","properties":{"genre":{"type":"string"},"count":{"type":"integer"}}}},"top_artists":{"type":"array","items":{"type":"object","properties":{"artist":{"type":"string"},"count":{"type":"integer"}}}},"unique_artists":{"type":"integer"},"new_artists_discovered":{"type":"integer"},"most_active_day":{"type":"string"},"most_active_time":{"type":"string"}}}}}}}}},"/api/v1/share":{"post":{"operationId":"shareSong","summary":"Get shareable link for a song","description":"Resolves a track to a streaming URL and returns shareable data. Default mode returns link data; set mode to \"imessage\" to send via SMS. Can share the currently playing track or a specific track by title/artist.","tags":["Social"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["end_user_id"],"properties":{"end_user_id":{"type":"string","description":"User identifier"},"recipient_phone":{"type":"string","description":"Recipient phone in E.164 format"},"mode":{"type":"string","enum":["link","imessage"],"default":"link","description":"link returns shareable data, imessage sends via SMS (requires recipient_phone)"},"track":{"type":"object","properties":{"title":{"type":"string"},"artist":{"type":"string"}},"description":"Track to share. Omit to share currently playing."},"message":{"type":"string","description":"Optional custom message"}}}}}},"responses":{"200":{"description":"Share result with track info and URL"}}}},"/api/v1/share/set":{"post":{"operationId":"shareSet","summary":"Get shareable session tracklist","description":"Snapshots the active session tracks and returns the full tracklist with playlist URL. Default mode returns data; set mode to \"imessage\" to send via SMS.","tags":["Social"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["end_user_id"],"properties":{"end_user_id":{"type":"string","description":"User identifier"},"recipient_phone":{"type":"string","description":"Recipient phone in E.164 format"},"recipient_name":{"type":"string","description":"Recipient name (optional, used in the message)"},"mode":{"type":"string","enum":["link","imessage"],"default":"link","description":"link returns shareable data, imessage sends via SMS (requires recipient_phone)"}}}}}},"responses":{"200":{"description":"Share result with track count and context label"}}}},"/api/v1/lyrics":{"get":{"operationId":"getLyrics","summary":"Look up song lyrics","description":"Fetch lyrics for a track via Musixmatch (primary) with Genius fallback. Also supports identifying a song from a lyric snippet.","tags":["Insights"],"parameters":[{"name":"title","in":"query","schema":{"type":"string"},"description":"Track title"},{"name":"artist","in":"query","schema":{"type":"string"},"description":"Artist name"},{"name":"lyrics_snippet","in":"query","schema":{"type":"string"},"description":"Lyric snippet for song identification"}],"responses":{"200":{"description":"Lyrics result with source attribution"}}}},"/api/v1/concerts":{"get":{"operationId":"getConcertAlerts","summary":"Get upcoming concert alerts","description":"Check Bandsintown for upcoming concerts by a user's favorite artists near their location. Can also look up events for a specific artist.","tags":["Insights"],"parameters":[{"name":"end_user_id","in":"query","required":true,"schema":{"type":"string"},"description":"User identifier"},{"name":"artist","in":"query","schema":{"type":"string"},"description":"Specific artist to check (optional)"}],"responses":{"200":{"description":"Array of concert alerts with venue, date, ticket URL"}}}},"/api/v1/milestones":{"get":{"operationId":"getMilestones","summary":"Get user milestone status","description":"Returns a user's milestone status: session count, listening hours, artist discoveries, account age, and which milestones have been celebrated.","tags":["Insights"],"parameters":[{"name":"end_user_id","in":"query","required":true,"schema":{"type":"string"},"description":"User identifier"}],"responses":{"200":{"description":"Milestone status with counts and history"}}}}},"tags":[{"name":"Intelligence","description":"Context interpretation and signal fusion"},{"name":"Discovery","description":"Search and recommendations with BeatBrain scoring"},{"name":"Planning","description":"Set planning with energy arcs and harmonic sequencing"},{"name":"Tracks","description":"Track resolution, enrichment, and analysis"},{"name":"Catalog","description":"BeatBrain knowledge base and catalog operations"},{"name":"Skills","description":"Intelligence skills marketplace and management"},{"name":"Connection","description":"Streaming service OAuth connection (Spotify, Apple Music, Tidal, Deezer)"},{"name":"Playback","description":"Playback control (Spotify: full remote, Apple Music: Web Player + playlist, Tidal: deep links + playlist)"},{"name":"Sessions","description":"Session lifecycle and feedback"},{"name":"Agents","description":"Agent registration and profile"},{"name":"Webhooks","description":"Event notification webhooks"},{"name":"Batch","description":"Batch multiple operations"},{"name":"MCP","description":"Model Context Protocol integration"},{"name":"Social","description":"Song sharing and social features"},{"name":"Insights","description":"Listening stats, lyrics, concerts, and milestones"},{"name":"Operations","description":"Health checks, circuit breakers, feature flags, and production monitoring"}]}