Reference

Everything the landing page promised, documented cleanly.

These docs mirror the current FastAPI routes, the `X-API-Key` header, the async job flow, and the usage tiers already defined in the project.

Create API key Open reference

Quick facts

Header auth via `X-API-Key`
Upload files or submit audio URLs
Batch endpoint currently accepts URLs
Results arrive via polling or webhook
Usage endpoint exposes monthly counters and paid-tier meter usage
Machine-readable surfaces ship with OpenAPI + `llms.txt`

Quickstart

Upload, queue, poll, consume.

curl -X POST https://api.beatlyze.dev/v1/analyze/upload \
  -H "X-API-Key: bz_your_api_key" \
  -F "file=@track.mp3"

# response
{
  "job_id": "8b7a5c17-b1a1-42fd-aab8-51d0c4ff3d2a",
  "status": "processing"
}

curl https://api.beatlyze.dev/v1/analysis/8b7a5c17-b1a1-42fd-aab8-51d0c4ff3d2a \
  -H "X-API-Key: bz_your_api_key"

Authentication

Use `X-API-Key`, not `Authorization: Bearer`.

Register

`POST /v1/auth/register` creates a user, creates a Stripe customer, and returns an API key once.

{
  "email": "dev@example.com"
}

Send the key

Every protected endpoint expects the raw key in the request header below.

X-API-Key: bz_your_api_key

Lifecycle

The product is asynchronous by design.

Submit audio

Use the upload endpoint for local files or the URL endpoint for remotely hosted audio.

Receive `job_id`

The API returns an accepted response with `status: "processing"` while workers perform analysis.

Retrieve results

Poll `GET /v1/analysis/{job_id}` or supply `webhook_url` when you submit the job.

Endpoints

Current app surface

POST/v1/auth/register

Create a user, Stripe customer, and default API key. Returns the raw key once.

POST/v1/analyze/upload

Upload an audio file up to 50 MB and receive an async analysis job ID.

POST/v1/analyze/url

Submit a publicly accessible audio URL for download + analysis in the background.

GET/v1/analysis/{job_id}

Retrieve the summary result. The compact response omits section-level detail.

GET/v1/analysis/{job_id}/full

Retrieve the full result including the `sections` array.

POST/v1/batch

Queue multiple URL analyses. The current implementation expects URL items, not uploaded files.

GET/v1/usage

Return current billing-month usage, tier limit, and meter usage for paid plans.

POST/webhooks/stripe

Handle subscription lifecycle and payment-failure events from Stripe.

Schema

Result shape

Summary result

{
  "job_id": "8b7a5c17-b1a1-42fd-aab8-51d0c4ff3d2a",
  "status": "completed",
  "result": {
    "bpm": 127.8,
    "bpm_confidence": 0.94,
    "key": "A",
    "scale": "minor",
    "key_notation": "Am",
    "key_confidence": 0.88,
    "energy": 0.86,
    "danceability": 0.91,
    "valence": 0.44,
    "loudness_lufs": -8.1,
    "mood_tags": ["energetic", "dark"],
    "genre_suggestions": ["techno", "house"],
    "duration_seconds": 247.3,
    "time_signature": 4
  }
}

Full result additions

The full endpoint adds a `sections` array with structural segment detail.

"sections": [
  {
    "start_time": 0.0,
    "duration": 31.4,
    "key": "Am",
    "loudness": -9.2,
    "energy": 0.71
  }
]

Usage + billing

Tier limits currently modeled in the app

Free 50 analyses / month

Starter 2,000 analyses / month

Pro 10,000 analyses / month

The API stores monthly usage locally and can also fetch Stripe meter summaries for paid users. Free-tier enforcement is hard-capped in the request flow.

Migration

How to present Spotify replacement credibly

Lead with “no OAuth, submit file or URL, receive structured JSON.”
Keep the async workflow visible so buyers understand job-based latency.
Prefer “migration-friendly” over “drop-in exact replacement” unless the schema truly matches.

Agent-ready docs

Small 2026-proof addition

# See the machine-readable guide
curl https://beatlyze.dev/llms.txt

# And the contract source
curl https://beatlyze.dev/openapi.yaml