API reference
Base URL: https://binauralbeatmachine.com. All responses are JSON. CORS is open for browser prototypes; production apps should call from your backend when possible.
Authentication
For metered API calls, send one of:
Authorization: Bearer bbm_test_… or bbm_live_… X-Api-Key: bbm_test_…
Invalid or revoked keys → 401. Monthly quota exceeded → 429 with X-RateLimit-* headers.
Dashboard routes use X-BBM-Session: <sessionToken> (from Free signup, checkout fulfill, or magic-link email).
GET /api/v1/presets
List the program preset catalog (currently matching the free console’s automated programs).
| Query | Description |
|---|---|
id | Return a single preset by id (e.g. deep-sleep) |
category | Filter: sleep, focus, calm, energy, meditation, … |
Auth optional. Public browse does not consume quota. Requests with a valid API key are metered.
curl -sS "https://binauralbeatmachine.com/api/v1/presets?category=sleep" \ -H "X-Api-Key: $BBM_KEY"
curl -sS "https://binauralbeatmachine.com/api/v1/presets?id=deep-sleep"
POST /api/free-signup
{ "email": "you@company.com" }
Creates a Free-tier customer and one development key. Secret is returned once in key.secret. Also returns sessionToken for the keys dashboard.
POST /api/checkout
{ "email": "you@company.com", "tier": "starter" }
tier: starter | pro | enterprise. Returns { url } — redirect the user to Stripe Checkout.
POST /api/fulfill
{ "session_id": "cs_live_…" }
After Stripe success, exchanges the Checkout session for a production key (once) + dashboard session.
GET /api/keys
Header: X-BBM-Session. Lists key prefixes, tier, and quota usage (never full secrets).
POST /api/keys
{ "action": "create", "name": "Prod", "env": "production" }
{ "action": "revoke", "keyId": "uuid" }
{ "action": "claim", "keyId": "uuid" }
POST /api/magic-login
{ "email": "you@company.com" }
Production: emails a dashboard link (requires Resend). Does not return a session token in the JSON body. Local mock may return sessionToken for development.
Errors
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, email, or tier |
| 401 | Missing/invalid API key or session |
| 403 | Max keys for tier reached |
| 404 | Unknown preset or checkout session |
| 405 | Wrong HTTP method |
| 429 | Monthly quota exceeded |
| 503 | Upstream not configured (email, etc.) |
Netlify function aliases also work: /.netlify/functions/api-v1-presets etc. Prefer the clean /api/… paths.
Not medical advice. Contact binauralbeatmachine@gmail.com