Docs

Integrate the live Beatlyze API without guessing the flow.

These docs describe the current production surface at https://api.beatlyze.dev. Start with the anonymous demo or create a key and submit one public URL.

Quickstart

Create a key, submit a URL, then poll the job.

URL analysis is the lowest-friction first authenticated request. Uploads use the same job lifecycle once you are ready to send local files.

cURL Register, submit, poll

curl -X POST https://api.beatlyze.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  --data '{"email":"[email protected]"}'

curl -X POST https://api.beatlyze.dev/v1/analyze/url \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bz_your_api_key" \
  --data '{"url":"https://samplelib.com/lib/preview/mp3/sample-15s.mp3"}'

JOB_ID="<returned_job_id>"

curl https://api.beatlyze.dev/v1/analysis/$JOB_ID \
  -H "X-API-Key: bz_your_api_key"

Anonymous demo

Check the JSON before signup.

The demo route accepts a public audio URL and returns a token-gated polling path. It is rate-limited and intended for evaluation, not production ingestion.

cURL POST /v1/demo/analyze/url

curl -X POST https://api.beatlyze.dev/v1/demo/analyze/url \
  -H "Content-Type: application/json" \
  --data '{"url":"https://samplelib.com/lib/preview/mp3/sample-15s.mp3"}'

Authentication

Use one API key header for protected routes.

Header

Send X-API-Key: bz_your_api_key on protected API routes.

Verification

If email verification is enabled, the key exists immediately but protected routes remain blocked until verification completes.

Submit audio

Use public URL analysis for remote assets and upload analysis for local files.

`POST /v1/analyze/url`

Submit a public audio URL. Private and internal network targets are blocked by URL validation.

`POST /v1/analyze/upload`

Multipart upload for local files. Current max upload size is 50 MB and supported audio extensions include MP3, WAV, FLAC, OGG, AAC, M4A, AIFF, and AIF.

cURL Upload with optional webhook URL

curl -X POST https://api.beatlyze.dev/v1/analyze/upload \
  -H "X-API-Key: bz_your_api_key" \
  -H "Idempotency-Key: upload-track-001" \
  -F "[email protected]" \
  -F "webhook_url=https://example.com/beatlyze/webhook"

Result shape

Poll until status is completed or failed.

In-progress jobs return lifecycle state. Completed jobs include result; failed jobs include error.

JSON GET /v1/analysis/{job_id}

{
  "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,
    "loudness_lufs": -8.1,
    "duration_seconds": 247.3,
    "time_signature": 4,
    "energy": 0.86,
    "danceability": 0.91,
    "valence": 0.44,
    "mood_tags": ["energetic", "dark"],
    "genre_suggestions": ["techno", "house"],
    "genre_confidence": 0.81,
    "genre_taxonomy": "beatlyze_broad_6_v1",
    "genre_review_recommended": false,
    "genre_review_code": null,
    "sections": []
  },
  "error": null,
  "created_at": "2026-04-26T10:12:00Z",
  "completed_at": "2026-04-26T10:12:18Z"
}

Errors and rate limits

Design retries around explicit HTTP failures.

401 Missing or invalid key

422 Invalid URL, file, or webhook

429 Rate limit or monthly quota

503 Temporary dependency unavailable

Example 429 rate limit

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 42

{
  "detail": "Rate limit exceeded. 60 requests per 60s."
}

Batch and webhooks

Batch URL jobs and inspect webhook delivery.

Batch accepts 1 to 10 URL items. Webhook URLs can be attached to upload, URL, and batch items, and delivery attempts are queryable per job.

cURL POST /v1/batch

curl -X POST https://api.beatlyze.dev/v1/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bz_your_api_key" \
  --data '{
    "items": [
      {
        "url": "https://example.com/audio-1.mp3",
        "webhook_url": "https://example.com/beatlyze/webhook"
      },
      {
        "url": "https://example.com/audio-2.wav"
      }
    ]
  }'

cURL + JSON Webhook delivery log

curl https://api.beatlyze.dev/v1/analysis/$JOB_ID/webhooks \
  -H "X-API-Key: bz_your_api_key"

{
  "job_id": "8b7a5c17-b1a1-42fd-aab8-51d0c4ff3d2a",
  "webhook_configured": true,
  "delivered": true,
  "latest_attempt": 1,
  "success_count": 1,
  "deliveries": [
    {
      "attempt": 1,
      "status_code": 200,
      "success": true,
      "error_detail": null
    }
  ]
}

Fields

Core response fields.

Field	Type	Use
`bpm`	number	Tempo estimate. Interpret with bpm_confidence.
`key_notation`	string	Readable key and scale, for example Am.
`loudness_lufs`	number	Integrated loudness estimate.
`duration_seconds`	number	Track duration returned by analysis.
`genre_suggestions`	array	Broad semantic candidates, useful as hints.
`sections`	array	Optional section snapshots when available.

Reference assets

Use the machine-readable contract for exact schemas.

OpenAPI Endpoint reference llms.txt