Music Distribution API for Developers

A music distribution API lets your own software do what an artist does in a distributor’s dashboard: create accounts, upload audio and artwork, describe a release, submit it for review and learn what happened to it. If you run a platform where people make or manage music, the API is how you put a release workflow inside your product instead of sending users to a separate site.

This guide is for developers, product owners and technical founders who are deciding whether to build on a distribution API, and how to design the integration so it holds up. It explains how WBBT’s API is organised, walks through a first integration, covers the decisions that save the most rework and says plainly what the API does not do. The WBBT Distributor API is invite-only early access, so treat the live documentation as the source of truth for endpoints, fields and limits.

What a distribution API does and does not do

A distribution API moves information and files between your application and a distributor. The distributor still reviews the release, still delivers it to the stores, and the stores still decide whether and when it goes live. Calling the API does not bypass any of that.

• It does: create accounts for your users, accept audio and cover uploads, validate and store release drafts, submit releases, report status, send events when a decision is made, and expose reported streams and earnings.
• It does not: publish instantly, guarantee a store accepts a track, promise playlist placement, pay artists automatically, or remove your responsibility for rights and support.

That boundary shapes your product copy as well as your code. If your interface says a release is live the moment a call succeeds, your users will be misled. A good integration shows each stage honestly: draft, submitted, in review, approved, rejected, live in the stores.

When an API is the right choice

Building against an API is real engineering work with an ongoing maintenance cost. Choose it for the right reasons.

You are	Consider
An artist or a small label releasing your own music	The Release Wizard in a normal account. If you like working in a chat, WBBT MCP prepares drafts for you.
A label that wants a branded place for its artists, without writing code	White-label music distribution
A team with its own app, such as a creator platform, a production tool or an artist-services product	The Distributor API
A label with internal tools that already prepare catalogue data	The API, if you want a defined hand-over into distribution

If you are unsure, label, white-label or API: which do you need compares the three routes from a business point of view.

How WBBT’s API is organised

The API is a REST interface over HTTPS with JSON bodies, meant for server-to-server use. Your users are modelled as sub-accounts under your partner account, and everything else hangs off them.

• Partner account. Your business, with an eligible Label account and an agreed API offer.
• Sub-accounts. One per end user. You create them through the API and tell each request which sub-account it is for. You can use your own identifier for the user.
• Artists, uploads, releases and tracks. A sub-account has artist profiles, uploaded files and releases made of tracks.
• API keys. Bearer keys with scopes, in a live mode and a test mode. A key carries only the scopes you chose, so a reporting tool does not need permission to submit releases.
• Reference data. Lookups for stores, genres, languages, countries and contributor roles, so your forms offer valid choices.
• Webhooks. Signed events sent to your server when a release is approved or rejected, when an edit is approved or rejected, and when a takedown is approved.
• Analytics and royalties. Reported listening activity and statement rows, with freshness information so you can tell a missing value from zero.

Releases created through the API go into the same human review queue as releases uploaded by hand. The rules are also the same. The API holds a submission to the checks the Release Wizard applies, so your integration cannot skip what an artist in the web form has to answer, such as the AI declaration, credits and the legal confirmations.

Steps to build a first integration

1. Request access. Contact sales with a description of your platform and users. Access is invite-only. The offer is accepted, signed and paid before live use, and an eligible Label account is part of the requirement.
2. Read the documents. Start with the public guide and the OpenAPI file. Note the scopes, error codes and idempotency rules before you write a line of code.
3. Create a test key and check it. A call to the key information endpoint tells you the mode, the scopes and your limits. Never ship a key in browser or app code.
4. Create a sub-account for a test user. The primary artist is created with it. Add other artists only for different names, such as featured artists.
5. Upload files. Upload the audio and the cover first, then use the returned file addresses in the release. Cover art must be square.
6. Validate the release. Send the release body to the validate endpoint. A failed check returns a list of problems, each with a code and a field, which you can show next to the matching form field.
7. Create the draft, then submit it. With a test key, submit runs every check and tells you that the release would have been submitted, but it stays a draft. With a live key it moves to review.
8. Register a webhook and send a test ping. Make sure your endpoint verifies the signature and answers quickly before you rely on it.
9. Handle the outcome. On approval, record the result. On rejection, show the reason, let the user correct the release and resubmit it.
10. Go live in a controlled way. Agree the live activation with WBBT, use a live key for a small first set of real releases, and watch the results before you open the feature to everyone.

The calls below show the shape of the first three requests. They use placeholders and the documented endpoint names. Check the current documentation for required fields before you copy any of it.

export WBBT_BASE=https://app.wbbt.net/api/v1
export WBBT_TEST_KEY=paste-your-test-key-here

# 1. Check the key: mode, scopes and limits
curl -s "$WBBT_BASE/me" -H "Authorization: Bearer $WBBT_TEST_KEY"

# 2. Create a sub-account for one of your users (writes need an Idempotency-Key)
curl -s -X POST "$WBBT_BASE/subaccounts" \
  -H "Authorization: Bearer $WBBT_TEST_KEY" \
  -H "Idempotency-Key: a-new-uuid-for-this-request" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "user-42", "name": "Example Artist"}'

# 3. Validate a release before you create it
curl -s -X POST "$WBBT_BASE/releases/validate" \
  -H "Authorization: Bearer $WBBT_TEST_KEY" \
  -H "X-Subaccount-Id: user-42" \
  -H "Idempotency-Key: another-new-uuid" \
  -H "Content-Type: application/json" \
  -d @release.json

Design decisions that save rework

Keep keys on your server and keep them narrow

The API is server-to-server only. A leaked key lets anyone act as your account, so never put it in a web page, a mobile app or a public repository. Issue each integration the narrowest scopes that do the job, and rotate keys by creating the new one, deploying it and then revoking the old one.

Make every write safe to repeat

Write requests carry an idempotency key, so a retry of the same operation does not create a duplicate. Generate the key once per user action, store it with the action, and reuse it only when you retry the exact same request. After you correct a failed request, send it with a new key, or you may get the earlier answer back. Retry rate-limit and server errors with backoff and honour any wait time the response gives.

Treat validation as part of your form

Use the lookup endpoints to build your genre, language and role pickers so users cannot choose a value the release will reject. Run the validate call before you create a draft, and map each returned field to a message beside the right input. This is cheaper than finding the problem in review. Our metadata and artwork checklist lists the rules your form should enforce.

Show the real status

Store the release status and the rejection reason in your own database. A rejected release that has not gone live can be corrected and resubmitted. A change to a live release uses the edit-request workflow, and a takedown is a separate request. Do not hide those paths behind a generic error.

Use webhooks, with polling as a backup

Webhooks tell you when a decision has been made. Verify the signature on every delivery, using the raw request body and the endpoint secret. Treat the event identifier as the key for de-duplication, because the same event can arrive more than once and in any order. Keep a periodic status poll as a fallback so a missed event does not leave a release stuck in your interface.

Collect the confirmations from the right person

The release form asks the artist to confirm things such as accuracy, responsibility for the content and that the release is not under another exclusive contract. Your agreement defines which confirmations it covers and which your interface must still collect from the end user. Do not tick them on a user’s behalf by default.

Show the attribution the terms require

Platforms built on the API must display the distribution attribution that the API terms require, such as a small “Distribution powered by WBBT” notice. Read that requirement before you finalise your design.

Streams, earnings and payouts

The reporting endpoints expose listening activity by day, track, release, platform or territory, and monthly earnings with statement rows. Treat these as reported figures. A daily listening chart is not a live counter of every stream, and it does not mean that revenue is settled daily. Royalties are posted in monthly cycles after the stores’ reports are processed, and source statement receipts, credited earnings and withdrawable balance are three different measures. If your product shows an earnings figure, label it with the period it covers and when it was last updated.

Where the payouts capability is part of your agreement, a live key can manage supported payout destinations and submit withdrawal requests, which go into a manual payment workflow. The API does not move money by itself, and test keys cannot store real payout details.

Your responsibilities as a platform

• Your interface and your users. You own the experience, the permissions you grant and the explanation you give of what each status means.
• Rights and honesty. You decide how your platform collects rights information and declarations. Pass on what users say accurately, and do not pre-fill an AI declaration or an ownership answer.
• Support. Agree who follows up on a rejected release, a wrong store profile or a takedown, and which identifiers to send to WBBT when you escalate.
• Capacity. Request rate, sub-account count and release volume are set in your agreement, and a capacity increase needs an updated offer. Ask the API what applies to you instead of assuming.
• Money. Do not promise users income, playlist placement or a delivery date. Stores decide those things.

Asking for access

A useful request describes the application you operate, who uses it, how many accounts and releases you expect each month, how large your audio and artwork files are, and what you need support to do. Say which parts of the workflow you want to connect first. Sales answers with a written proposal covering scope, capacity and any underlying subscription requirements. There is no fixed public price for the API, so do not plan a launch schedule until the proposal is agreed. Start from the Distributor API page and the Label plans that the integration depends on.

Frequently asked questions

Is there a free music distribution API?

WBBT does not advertise a free public tier. The Distributor API is invite-only early access with a sales quote, and an eligible Label account is required. Test credentials are part of onboarding, so you can build and check an integration before you use live keys.

Do I need a Label subscription to use the API?

Yes. An eligible Label account is required, together with an accepted, signed and paid API offer. A White-Label subscription is not required. Sales confirms the underlying account in your proposal. See the Distributor API page.

Does test mode send music to the stores?

No. A test submission runs the checks and reports whether the release would be accepted, but nothing enters distribution. Test and live keys use separate sub-accounts, catalogue ownership and webhook endpoints.

Can the API pay my artists automatically?

No. Where the payouts capability is enabled, the API can submit withdrawal requests, and those enter WBBT’s manual payment workflow. Reported royalties, available balance and payment processing are separate stages, and royalties follow monthly reporting cycles.

Can I use the API to release my own music?

You do not need it. For your own releases, use the Release Wizard in your account, or connect ChatGPT or Claude through WBBT MCP to prepare drafts. The API is for businesses that build software for other people’s releases.

Where are the developer docs?

The public guide is at app.wbbt.net/#/docs/api, and the machine-readable OpenAPI file is at app.wbbt.net/api/v1/openapi.json. Use the current documents for endpoints, fields and error codes, not this article.

Next steps and further reading

Read the Distributor API page for the current scope, the public API documentation for endpoints and the OpenAPI file for the machine-readable definitions. If a branded workspace suits you better than writing code, read about white-label music distribution. Planning how your own releases flow? How to distribute music to Spotify and Apple Music shows the same steps from the artist’s side, and the WBBT FAQ covers white-label and API questions. Early-access terms change, so rely on your written proposal and the live documents.