{"openapi":"3.1.0","info":{"title":"mu$ic API","description":"Show your artists a RUN advance offer inside your own product.\n\nRUN prices every account ahead of time. You ask whether an account is eligible, then open the offer page for it in an iframe. Amounts are in your configured currency.\n\nEvery `/v1` call needs your secret key: `Authorization: Bearer sk_...`. Call from your backend, never from a browser.","license":{"name":""},"version":"0.1.0"},"paths":{"/health":{"get":{"tags":["Service"],"summary":"Health","description":"Needs no key.","operationId":"health","responses":{"200":{"description":"The API is up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/v1/account":{"get":{"tags":["Account"],"summary":"Your account","description":"Who the key belongs to, and its limits.","operationId":"account","responses":{"200":{"description":"The account behind the key.","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over your requests per minute. `Retry-After` says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"api_key":[]}]}},"/v1/accounts/{account}/offer":{"get":{"tags":["Offers"],"summary":"Get an account's offer","description":"The newest open offer for one of your accounts, with whether the account is eligible.\nUse it to decide whether to show the advance to an artist. When we read your backend,\noffers are priced ahead of time, so this answers at once.","operationId":"get_account_offer","parameters":[{"name":"account","in":"path","description":"Your own id for the artist or label.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The offer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoredOffer"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No open offer for that account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over your requests per minute. `Retry-After` says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"api_key":[]}]}},"/v1/embed/sessions":{"post":{"tags":["Offers"],"summary":"Open an embedded offer page","description":"Call this from your backend when an artist opens your page, then put the `url` in an\niframe. The URL carries a one-hour pass for that offer only, so your secret key never\nreaches the browser.","operationId":"create_embed_session","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewEmbedSession"}}},"required":true},"responses":{"201":{"description":"The page to embed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedSession"}}}},"400":{"description":"The request is wrong. `code` says how.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such offer, or no open offer for the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over your requests per minute. `Retry-After` says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"api_key":[]}]}},"/v1/offers/{id}":{"get":{"tags":["Offers"],"summary":"Get an offer","description":"A kept offer as the artist sees it: the options in the display currency, when it\nexpires, and which option the artist chose, if any.","operationId":"get_offer","parameters":[{"name":"id","in":"path","description":"The offer's id, `ofr_...`.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The offer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoredOffer"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such offer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over your requests per minute. `Retry-After` says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"api_key":[]}]}},"/v1/requests":{"get":{"tags":["Account"],"summary":"Request log","description":"Your latest API calls, newest first.","operationId":"requests","parameters":[{"name":"limit","in":"query","description":"How many, 1 to 500. Default 50.","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"The calls made with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestList"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over your requests per minute. `Retry-After` says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"api_key":[]}]}},"/v1/usage":{"get":{"tags":["Account"],"summary":"Usage summary","description":"Requests, errors, offers and time per step, per day.","operationId":"usage_summary","parameters":[{"name":"days","in":"query","description":"How many days back, 1 to 90. Default 14.","required":false,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Totals and breakdowns for the period.","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over your requests per minute. `Retry-After` says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"api_key":[]}]}}},"components":{"schemas":{"ArtistOption":{"type":"object","description":"One offer as the artist sees it. None of RUN's own numbers.","required":["years","artist_share","advance"],"properties":{"years":{"type":"integer","minimum":0},"artist_share":{"type":"number","format":"double","description":"What the artist keeps once the advance is repaid."},"advance":{"type":"number","format":"double","description":"In the offer's display currency."}}},"EmbedSession":{"type":"object","required":["object","id","offer","url","expires"],"properties":{"object":{"type":"string","example":"embed_session"},"id":{"type":"string"},"offer":{"type":"string"},"url":{"type":"string","description":"Put this in the `src` of an iframe, exactly as given, including the part after\n`#`. It works for one hour and for this offer only."},"expires":{"type":"string","description":"RFC 3339, UTC."}}},"Error":{"type":"object","description":"Every error has this shape.","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","required":["type","code","message"],"properties":{"type":{"type":"string","description":"`invalid_request_error`, `authentication_error`, `rate_limit_error` or `api_error`.","example":"invalid_request_error"},"code":{"type":"string","description":"A stable code to branch on.","example":"unknown_format"},"message":{"type":"string","description":"For people. The wording can change."}}},"Health":{"type":"object","required":["status","version","model","consumption"],"properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string"},"model":{"type":"string","description":"`loaded` or `missing`: the stream model."},"consumption":{"type":"string","description":"`on` or `off`: consumption data."}}},"NewEmbedSession":{"type":"object","description":"Say which offer to show: `offer`, or `account` for that account's newest open offer.","properties":{"offer":{"type":["string","null"],"description":"An offer id, `ofr_...`."},"account":{"type":["string","null"],"description":"Your own id for the artist or label."},"locale":{"type":["string","null"],"description":"The page's language. Default: your first configured language.","example":"es"},"signer":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Signer","description":"The person who will sign the agreement. With it, the artist can sign right in\nthe page after choosing. Without it, the page stops after choosing."}]}},"additionalProperties":false},"Record":{"type":"object","required":["id","time","method","route","status","ms","timings","warnings"],"properties":{"id":{"type":"string"},"time":{"type":"string","description":"RFC 3339, UTC."},"partner":{"type":["string","null"],"description":"The partner that key belongs to."},"method":{"type":"string"},"route":{"type":"string"},"status":{"type":"integer","format":"int32","minimum":0},"ms":{"type":"number","format":"double"},"format":{"type":["string","null"]},"files":{"type":["integer","null"],"minimum":0},"rows":{"type":["integer","null"],"minimum":0},"tracks":{"type":["integer","null"],"minimum":0},"mode":{"type":["string","null"]},"advance_5y":{"type":["number","null"],"format":"double"},"timings":{"type":"object","additionalProperties":{},"propertyNames":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"error":{"type":["string","null"]}}},"RequestList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Record"},"description":"Newest first."}}},"Signer":{"type":"object","description":"The person signing.","required":["name","email"],"properties":{"name":{"type":"string","description":"Full name, as it should appear on the agreement.","example":"Lucía Moreno"},"email":{"type":"string","example":"lucia@lunaroja.example"}}},"StoredOffer":{"type":"object","description":"A kept offer.","required":["id","object","created","expires","expired","currency","options","eligible","source"],"properties":{"id":{"type":"string"},"object":{"type":"string","example":"offer"},"account":{"type":["string","null"],"description":"The partner's own id for the artist or label."},"created":{"type":"string","description":"RFC 3339, UTC."},"expires":{"type":"string"},"expired":{"type":"boolean"},"currency":{"type":"string","description":"The currency the artist is shown."},"options":{"type":"array","items":{"$ref":"#/components/schemas/ArtistOption"}},"selected_years":{"type":["integer","null"],"description":"The option the artist chose, if any.","minimum":0},"selected_at":{"type":["string","null"]},"eligible":{"type":"boolean","description":"Whether the account may be offered an advance at all."},"ineligible_reason":{"type":["string","null"],"description":"Why not: `too_small` or `too_little_history`."},"source":{"type":"string","description":"Where the statements came from. `precalc`: read from your backend. `manual`:\nloaded by RUN.","example":"precalc"},"account_name":{"type":["string","null"],"description":"The account's name on your side, when we know it."},"signed_at":{"type":["string","null"],"description":"When the artist signed the agreement. Set only once the signing service confirms\nit. RFC 3339, UTC."}}}},"securitySchemes":{"api_key":{"type":"http","scheme":"bearer","description":"Your secret key, `sk_live_...` or `sk_test_...`."}}},"tags":[{"name":"Offers","description":"An account's advance offer, and the embedded page that shows it."},{"name":"Account","description":"Your account, usage and request log."},{"name":"Service","description":"Is the API up."}]}