# MeloLab Public API

MeloLab Public API v1 is a bearer-authenticated API for AI music in apps, agents, scripts, and MeloPulse workflows.

Base URL: https://melolab.ai

Authentication:
- Send API keys with Authorization: Bearer <api_key>.
- API keys use scopes such as models:read, credits:read, generations:create, generations:read, and library:read.

Credits:
- Public API uses existing MeloLab credits.
- Read endpoints do not consume credits.
- POST /api/v1/generations consumes credits using the same model cost, concurrency, and refund logic as the MeloLab web app.
- Failed provider submissions follow the existing MeloLab refund behavior.

Idempotency:
- POST /api/v1/generations requires an Idempotency-Key header.
- Reusing the same key with the same body returns the stored response.
- Reusing the same key with a different body returns idempotency_conflict.

Endpoints:
- GET /api/v1/me returns the authenticated API profile.
- GET /api/v1/credits returns existing MeloLab credit balance.
- GET /api/v1/usage returns redacted API usage events.
- GET /api/v1/models lists available MeloLab models and credit costs.
- GET /api/v1/models/{model_id} returns one model.
- POST /api/v1/generations creates an async music generation.
- GET /api/v1/generations lists recent generation jobs.
- GET /api/v1/generations/{id} polls a generation.
- GET /api/v1/jobs/{job_id} polls an async job and returns outputs when ready.
- GET /api/v1/logs lists recent API request logs (last 30 days).
- GET /api/v1/library/search searches playable MeloLab tracks and playlists.
- GET /api/v1/tracks/{id} returns playable track metadata.
- GET /api/v1/playlists lists playlists.
- GET /api/v1/playlists/{id} returns a playlist and its tracks.
- GET /api/v1/webhook-endpoints lists active webhook endpoints.
- POST /api/v1/webhook-endpoints registers a public HTTPS webhook endpoint.
- PATCH /api/v1/webhook-endpoints/{id} updates a webhook endpoint URL or status.
- DELETE /api/v1/webhook-endpoints/{id} removes a webhook endpoint.

Webhook delivery:
- Register a public HTTPS endpoint; the full signing secret is returned only once on creation.
- MeloLab signs deliveries so you can verify them using the signing secret; only the secret prefix is shown afterward.
- Use webhooks to learn when async generation jobs finish instead of polling.

MeloPulse:
- Use GET /api/v1/models and GET /api/v1/credits during setup.
- Use GET /api/v1/library/search for recommendations that do not consume credits.
- Use POST /api/v1/generations for soundtrack creation from safe Git context.

Responses:
- Success responses use { "data": ... }.
- Error responses use { "error": { "code": string, "message": string, "request_id": string, "details": object } }.