PUBLIC REST API v1 SPECIFICATION
Developer Documentation
Learn how to authenticate requests, manage granular permission scopes, stay within rate limit boundaries, and interact with the DistroVibe REST API v1.
1. Authentication
The DistroVibe Public REST API v1 uses Bearer token authentication via cryptographically generated live keys (dv_live_...).
Every request must include your secret API key in the Authorization header:
Authorization: Bearer dv_live_8f3a9b1c7d2e...
Security Principle: Never expose your API keys in clientside web applications (browser JavaScript) or public repositories. Always make calls from your secure backend servers or serverless functions.
2. Granular Scopes Matrix
| Scope Identifier | Category | Description | Access Level |
|---|---|---|---|
| artists:read | Catalog | View artist profiles & roster | Standard |
| artists:write | Catalog | Create and update artist profiles | Standard |
| releases:read | Releases | View releases, metadata & submission states | Standard |
| releases:write | Releases | Create & update draft release packages | Standard |
| releases:submit | Releases | Submit release for QA & store delivery | Sensitive |
| catalog:read | Catalog | Enumerate full catalog, query UPCs & ISRCs | Standard |
| analytics:read | Insights | Access stream telemetry & platform breakdown | Standard |
| royalties:read | Financials | Access monthly sales & track royalty ledger | Restricted |
| publishing:read | Publishing | View composition registrations & shares | Standard |
| publishing:write | Publishing | Update songwriting splits & agreements | Standard |
| teams:read | Organization | View team members & roles | Standard |
| teams:manage | Organization | Invite/remove team members | Sensitive |
| uploads:write | Media | Request presigned direct S3 upload URLs | Standard |
| webhooks:manage | Tools | Manage webhook endpoints & subscriptions | Standard |
3. Rate Limiting & Resource Protection
To ensure stable platform availability and prevent noisy neighbors on cluster nodes, the following limits are enforced per organization:
Minute Limit
60 req / min
Sliding minute window
Concurrency Limit
3 simultaneous
Active in-flight requests
Monthly Allowance
30,000 req / mo
Included with Label Pro
HTTP Response Headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 42 // Seconds until window resets
Retry-After: 42 // Only present when 429 Too Many Requests
4. Error Handling
The DistroVibe API uses standard HTTP status codes. Error responses always return a structured RFC-compliant JSON object:
{
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "This API key lacks the required scope: 'royalties:read'.",
"status": 403,
"requiredScope": "royalties:read"
}
}200 / 201Success
401Unauthorized
403Forbidden / Scope
429Rate Limited