Reference

Contract surfaces for the API you actually ship.

This page stays close to the live FastAPI implementation: registration, `X-API-Key` auth, async analysis jobs, usage metering, and Stripe lifecycle handling.

Create API key Read quickstart

Primary resources

OpenAPI contract for tooling and generated clients
llms.txt for AI-assisted discovery and onboarding
Docs for lifecycle, pricing, and schema examples
API health check for production monitoring

Resources

Three ways to consume the contract

Human docs

Use the quickstart and migration guidance when you want a curated integration path.

Open docs

OpenAPI

Best for generated clients, contract tests, SDK experiments, and API tooling.

Download YAML

llms.txt

Best for AI-assisted onboarding, agent prompts, and machine-readable context loading.

Open guide

Auth + base URLs

Registration is public. Analysis routes require the raw key.

Production

Base URL
https://api.beatlyze.dev

Health check
GET /health

Authentication

Register
POST /v1/auth/register

Protected routes
X-API-Key: bz_your_api_key

Endpoints

Current production-facing routes

POST/v1/auth/register

Create a user, create a Stripe customer, and return a new API key. Returns `201 Created`.

POST/v1/analyze/upload

Accepts multipart file uploads up to 50 MB. Returns `202 Accepted` with `job_id` and `status`.

POST/v1/analyze/url

Accepts a public audio URL and optional `webhook_url`, then queues download and analysis.

GET/v1/analysis/{job_id}

Returns summary analysis data. Jobs still in progress continue to return `status: "processing"`.

GET/v1/analysis/{job_id}/full

Returns the same summary fields plus section-level structure data in the `sections` array.

POST/v1/batch

Queues up to 10 URL-based analysis jobs in one request and returns a list of accepted jobs.

GET/v1/usage

Returns billing-month usage count, tier limit, and paid-tier meter usage when available.

POST/webhooks/stripe

Handles subscription tier changes, payment failures, and customer state transitions from Stripe.

Status codes

What the frontend should expect

201 Created Registration succeeded and includes the raw key.

202 Accepted Analysis work was queued and is still processing asynchronously.

200 OK Health, usage, or completed analysis responses returned normally.

409 Conflict The email already exists during registration.

429 Too Many Requests Registration rate limit hit for the current IP window.

502 Bad Gateway Stripe customer creation failed upstream during registration.

Examples

Two first requests most integrators need

Register

curl -X POST https://api.beatlyze.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com"}'

Check usage

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