API documentation
Machine-to-machine music infrastructure: catalog discovery, vector search, commercial licensing with signed receipts, stem streaming, rendering and credit billing.
https://levievans.cloud/api/v1 · Auth: Authorization: Bearer <JWT> or X-API-Key: <key> · Rate limit: 60 req/min per IP and per client.Authentication
Create a client once. The API key is shown once and stored hashed; the JWT is short-lived.
curl -s -X POST https://levievans.cloud/api/v1/auth/register \
-H 'content-type: application/json' \
-d '{"name":"my-agent","email":"[email protected]"}'
Exchange an API key for a fresh JWT:
curl -s -X POST https://levievans.cloud/api/v1/auth/token \ -H 'x-api-key: x402_...'
Discovery
| Method | Path | Description |
|---|---|---|
| GET | /catalog | Paginated catalog. Filters: genre, mood, key, min_bpm, max_bpm, limit, offset. |
| GET | /catalog/:track_id | Full metadata, stems and fee for one track. |
| GET | /search | Metadata + vector search: min_bpm, max_bpm, key, tags, vibe_vector (8 floats or true), q. |
| GET | /stats | Public catalog counts, average BPM and fee range. |
| GET | /genres | Public genre list with BPM ranges and sample IDs. |
| GET | /pricing | Public credit packs, meter and license tiers. |
Licensing
| Method | Path | Description |
|---|---|---|
| POST | /license | Lock one or more tracks and issue a tamper-proof HMAC receipt. |
| GET | /license/:license_id | Retrieve an issued license. |
| POST | /license/verify | Verify a receipt signature server-side. |
curl -s -X POST https://levievans.cloud/api/v1/license \
-H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"client_wallet":"0xabc","track_ids":["trk_neon_drive"],"usage":"commercial","duration_days":30}'
Response includes receipt.signature (HMAC-SHA256 over canonical JSON) and receipt_hash. Tampering flips valid to false at /license/verify.
Audio
| Method | Path | Description |
|---|---|---|
| GET | /stems | List stems (paginated, optional track_id). |
| GET | /stems/:track_id | Stem manifest, or ?stem=drums|bass|melody|vocals|fx to stream 64KB chunked WAV. |
| POST | /render | Combine MIDI + stems. {"track_ids":["..."],"stems":["drums"],"duration_ms":8000}; streams WAV or "mode":"json" for metadata. |
Billing
1 credit = 1 US cent. Every successful catalog/search/stem/render request reports a metered increment; streaming costs STEM_COST_CENTS per stem request.
| Method | Path | Description |
|---|---|---|
| POST | /billing/checkout | Create a Stripe Checkout session for a credit pack ({"pack_id":"studio"}). Auth required. |
| POST | /billing/webhooks | Stripe webhook: checkout.session.completed credits the ledger. |
Insufficient balance returns 402 insufficient_credits; exceeded limits return 429 rate_limited with Retry-After.
Errors
{
"error": {
"code": "insufficient_credits",
"message": "Prepaid credit balance exhausted",
"details": { "balance_cents": 0 },
"request_id": "req-42"
}
}
For agents
OpenAPI 3.1
/openapi.json — import into function calling, LangChain, CrewAI or any OpenAPI client.
Agent card
/.well-known/agent.json — capabilities, auth and pricing pointers.
AI plugin
/.well-known/ai-plugin.json — legacy plugin manifest.
Status
/health — liveness, environment and Stripe state.