mu$ic API
Offer your artists a royalty advance inside your own product. Every account is priced ahead of time, so the integration is two API calls from your backend and one iframe on your page.
Overview
Offers are priced ahead of time
mu$ic does not price an offer when you ask for one. RUN reads your accounts and their royalty statements from your systems, read-only, and prices every account each night. When an artist signs in to your product, their offer already exists.
Two calls, then the iframe
With the offers in place, the integration is a short exchange between your backend and mu$ic.
Your page then loads the URL in an iframe. The artist reviews the offers and selects one there, without leaving your product.
The offer page uses your product name, colours, languages and currency. RUN configures these with you during onboarding, together with the offer terms and the eligibility rules.
Before you start
| Environment | Base URL | Keys |
|---|---|---|
| Sandbox | https://api-sandbox.runwith.us/v0 | sk_test_… |
| Production | https://api.runwith.us/v0 | sk_live_… |
Authentication. Send your secret key as a Bearer token on every request. RUN issues the keys, and a key is displayed once, when it is created. A key is only accepted in its own environment.
Server side only. Call the API from your backend. The browser never needs a key: the iframe URL carries its own one-hour credential.
Accounts. account is the identifier your backend already uses for the artist or label.
Rate limits. Requests above your per-minute limit return 429 with a Retry-After header.
You are signed in, so the examples on this page use your key and can be run as shown.
Sign in with your key to have it filled into the examples. To request a key, contact RUN.
curl {BASE}/account \
-H "Authorization: Bearer {KEY}"
Step 1
Check eligibility
Returns the current offer for one of your accounts. Call it when the artist opens your dashboard, to decide whether to show the advance.
| Field | Description |
|---|---|
eligible | Whether to show the advance to this account. |
ineligible_reason | Set when not eligible: too_small or too_little_history. |
options | One entry per offer: years, artist_share and advance. |
currency | The currency shown to the artist. |
expires | When the offer stops being valid. |
selected_years | The option the artist selected. null until then. |
signed_at | When the artist accepted the agreement. null until then. |
An account with no current offer returns 404. The highest advance can be used for a teaser, for example "Get up to €205,000".
curl {BASE}/accounts/label_48213/offer \
-H "Authorization: Bearer {KEY}"
{
"id": "ofr_4e6287d71f6146e2b1bc",
"object": "offer",
"account": "label_48213",
"account_name": "Luna Roja Records",
"eligible": true,
"ineligible_reason": null,
"currency": "EUR",
"options": [
{ "years": 1, "artist_share": 0.8, "advance": 47000 },
{ "years": 3, "artist_share": 0.75, "advance": 135000 },
{ "years": 5, "artist_share": 0.7, "advance": 205000 }
],
"created": "2026-11-12T02:00:00Z",
"expires": "2026-11-26T02:00:00Z",
"expired": false,
"selected_years": null,
"selected_at": null,
"source": "precalc"
}
Step 2
Create an embed session
Call this from your backend when the artist opens the offer. It returns a URL for the iframe.
| Field | Description |
|---|---|
account | Your identifier for the artist or label. Opens their current offer. |
offer | Alternatively, an offer id (ofr_…). Send one of the two. |
locale | The language of the page. One of the languages configured for you. Defaults to the first. |
signer | The person who accepts: name and email. When provided, the artist reads the Terms & Conditions in the page after selecting an offer, ticks the box and accepts. When omitted, the page ends after the selection. |
The URL is valid for one hour and for that offer only. Create a new session each time the artist opens the page.
An account that is not eligible returns 400 not_eligible.
curl -X POST {BASE}/embed/sessions \
-H "Authorization: Bearer {KEY}" \
-H "Content-Type: application/json" \
-d '{"account": "label_48213", "locale": "es"}'
{
"object": "embed_session",
"id": "ems_0c3b1e4f5a6d7b8c9d0e",
"offer": "ofr_4e6287d71f6146e2b1bc",
"url": "https://…/embed?s=ems_…#es_…",
"expires": "2026-11-12T15:04:05Z"
}
Step 3
Embed the offer page
Load the URL in an iframe, exactly as returned. It only renders on the sites registered for your account.
The offer page explains how the advance works, presents the offers and, with a signer, takes the artist's acceptance of the Terms & Conditions. It reports progress to your page with postMessage. Every message has source: "music-embed" and a type:
| Type | Meaning |
|---|---|
ready | The page has loaded. |
resize | Includes height in pixels. Set the iframe height to this value. |
selected | Includes years. The artist selected an offer. |
signed | Includes years. The artist accepted the agreement. |
close | The artist dismissed the page. Hide the iframe. |
Confirm on your server. Messages come from the browser, so treat them as hints for your interface. For the actual state, call GET /v0/accounts/{account}/offer and read selected_years and signed_at.
You can preview the offer page with your key.
<iframe id="advance" src="URL"
style="width:100%;border:0"></iframe>
<script>
const frame = document.getElementById("advance");
addEventListener("message", (e) => {
if (e.source !== frame.contentWindow) return;
if (e.data?.source !== "music-embed") return;
if (e.data.type === "resize")
frame.style.height = e.data.height + "px";
if (e.data.type === "selected")
console.log("selected", e.data.years, "years");
if (e.data.type === "close") frame.hidden = true;
});
</script>
Errors
The API uses standard HTTP status codes and a single error format. Branch on code. The wording of message may change.
| Status | Type | Codes |
|---|---|---|
| 400 | invalid_request_error | invalid_parameter, invalid_body, not_eligible, offer_expired, embed_not_configured |
| 401 | authentication_error | invalid_api_key |
| 404 | invalid_request_error | not_found |
| 429 | rate_limit_error | rate_limited |
| 500 | api_error | internal |
{
"error": {
"type": "invalid_request_error",
"code": "not_eligible",
"message": "That account is not eligible for an advance right now."
}
}
Versioning
The version is part of the path, and every response includes a Music-Version header. The current version is v0.
Additive changes are made without notice: new routes, optional request fields, response fields, error codes and message types. Ignore fields, codes and message types you do not recognise.
Breaking changes are announced in advance. While the API is at v0, routes and fields may still be renamed or removed, and RUN notifies your technical contact before that happens.
v1 will be released once the interface is final. From then on, a breaking change is released as a new version, and the previous version remains available for at least 12 months.