by RUN

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.

Your royalty dataRead by RUN, read-only. Nothing to send or upload.
mu$ic prices every accountEach night. Each account is marked eligible or not.
Offers are readyYour calls return a stored offer, without delay.

Two calls, then the iframe

With the offers in place, the integration is a short exchange between your backend and mu$ic.

Your backend mu$ic 1 Is this account eligible? GET /v0/accounts/{account}/offer 2 Eligibility and the offers 3 Create an embed session POST /v0/embed/sessions 4 URL for the iframe, valid for one hour

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

EnvironmentBase URLKeys
Sandboxhttps://api-sandbox.runwith.us/v0sk_test_…
Productionhttps://api.runwith.us/v0sk_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.

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

GET/v0/accounts/{account}/offer

Returns the current offer for one of your accounts. Call it when the artist opens your dashboard, to decide whether to show the advance.

FieldDescription
eligibleWhether to show the advance to this account.
ineligible_reasonSet when not eligible: too_small or too_little_history.
optionsOne entry per offer: years, artist_share and advance.
currencyThe currency shown to the artist.
expiresWhen the offer stops being valid.
selected_yearsThe option the artist selected. null until then.
signed_atWhen 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

POST/v0/embed/sessions

Call this from your backend when the artist opens the offer. It returns a URL for the iframe.

FieldDescription
accountYour identifier for the artist or label. Opens their current offer.
offerAlternatively, an offer id (ofr_…). Send one of the two.
localeThe language of the page. One of the languages configured for you. Defaults to the first.
signerThe 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:

TypeMeaning
readyThe page has loaded.
resizeIncludes height in pixels. Set the iframe height to this value.
selectedIncludes years. The artist selected an offer.
signedIncludes years. The artist accepted the agreement.
closeThe 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.

StatusTypeCodes
400invalid_request_errorinvalid_parameter, invalid_body, not_eligible, offer_expired, embed_not_configured
401authentication_errorinvalid_api_key
404invalid_request_errornot_found
429rate_limit_errorrate_limited
500api_errorinternal
{
  "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.