BTR Music · Partner Platform

Partner API

Distributor delivery, catalogue status, identity mapping, usage reports, and urgent takedowns.

OpenAPI 3.1 YAML Apply for access Sign in

Base URL

https://partners.btrmusic.com/api/v1

Authentication

Bearer API key

Catalogue format

DDEX ERN 4.3.x

Recommended

ERN 4.3.2

Start here

Authorised partner users create scoped API keys inside the portal. Send the key in the standard bearer header—never in a URL.

Authorization: Bearer btrp_live_…
Content-Type: application/zip

Upload one complete ZIP containing the ERN XML and every referenced media asset. A successful request returns 202 Accepted and a delivery reference to poll. Validation is atomic.

Delivery lifecycle

received→processing→staged→pending→live

staged means validated in private quarantine. Only BTR Music staff can publish it into the standard pending moderation flow. Alternate states include needs_artist, rejected, failed, and takedown.

Endpoints

Method	Path	Scope	Purpose
GET	/me	—	Partner, key, limits, and ERN versions.
GET	/reference/genres	—	Versioned supported DDEX genres and subgenres.
POST	/deliveries	deliveries:write	Submit multipart or raw ZIP.
GET	/deliveries	catalog:read	List deliveries.
GET	/deliveries/{ref}	catalog:read	Delivery state and validation issues.
GET	/releases	catalog:read	List catalogue releases.
GET	/releases/{upc}	catalog:read	Release and resources.
POST	/releases/{upc}/artist	catalog:write	Assign the approved `music_app.users._id` in `btr_user_id`.
POST	/releases/{upc}/takedown	takedown:write	Ownership-checked urgent takedown.
GET	/artists	catalog:read	List artist mappings.
POST	/artists	catalog:write	Request an artist connection; only BTR Music admin can approve it.
GET	/reports	reports:read	List usage reports.
POST	/reports/{period}	reports:read	Generate (or rebuild) a closed month's report.
GET	/reports/{period}	reports:read	Download TSV or CSV.

Signed webhooks

Events: delivery.staged, delivery.needs_artist, delivery.rejected, delivery.failed, release.pending, release.live, and release.takedown.

X-BTR-Event: delivery.staged
X-BTR-Timestamp: 1790100000
X-BTR-Signature: sha256=…

Verify HMAC-SHA256 over timestamp + "." + raw_body, reject stale timestamps, and deduplicate by event id.

Operational contract

120 requests/minute per key by default.
20 uploads/minute per key.
429 includes Retry-After.
Stable JSON error.code values (full catalogue in the spec and Integration Guide).
Retry POSTs only as documented.
Use sandbox keys through certification.