One versioned REST gateway, one API key. MCP and CLI surfaces share the same key. Catalog-scale is a contract, not an overage.
Provision a key, send it in the x-api-key header, call the gateway.
# 1 · x-api-key auth on every request — keys come from the console export MUSO_API_KEY="msk_51Ab…redacted" # 2 · Call the versioned REST gateway — a profile's verified credits curl "https://api.platform.muso.ai/v1/profile/e979669b-d99b-46be-91d6-bf1f1e2f44bf/credits" \ -H "x-api-key: $MUSO_API_KEY" # → 200 OK, x-request-id, x-ratelimit-remaining on the response
GET/v1/profile/e979669b-d99b-46be-91d6-bf1f1e2f44bf/credits…Sign in and add a card to run this live. Your first $5 is on us.
GET/v1/profile/e979669b-d99b-46be-91d6-bf1f1e2f44bf…Sign in and add a card to run this live. Your first $5 is on us.
GET/v1/profile/e979669b-d99b-46be-91d6-bf1f1e2f44bf/charts…Sign in and add a card to run this live. Your first $5 is on us.
Three short, real walkthroughs — pick the one that matches what you're building. Each is copy-paste and ends with something working.
Pull a profile's verified credits from the API and render them in your product — the core Muso integration. Server-side with a secret key; about ten minutes end to end.
Sign in at platform.muso.ai → Keys → create a secret key (msk_…). Add a card and your first $5 of usage is on us. Secret keys live on your server only — never in browser code (that's what publishable keys are for).
Resolve the artist you want by search, then keep their profile id.
curl "https://api.platform.muso.ai/v1/search/autocomplete?q=drake" -H "x-api-key: $MUSO_API_KEY" # → items[0].id = "e979669b-d99b-46be-91d6-bf1f1e2f44bf"
Credits are paginated — walk them with limit/offset. Each item carries the track, album, release date, and the credited roles.
const r = await fetch(
"https://api.platform.muso.ai/v1/profile/e979669b-d99b-46be-91d6-bf1f1e2f44bf/credits?limit=10",
{ headers: { "x-api-key": process.env.MUSO_API_KEY! } },
);
const { data, totalCount } = await r.json();Render the response directly to your users. Muso data is a live license: serve it at call time, don't store it. If your architecture needs caching, that's an enterprise agreement (see Data-use terms).
Users sign in with their Muso account, so your app knows who they are. Sharing their own credits with your app (with consent, never metered) is shipping. Standard OpenID Connect — if you've integrated Google sign-in you already know the shape.
Subscribe to the $99/mo per-app SSO fee at platform.muso.ai — it is the publishing gate — and we register your app: OIDC client id + secret and your redirect URIs.
Everything your OIDC library needs is published at the well-known endpoint — endpoints, JWKS, scopes.
curl https://login.muso.ai/.well-known/openid-configuration
Send the user to the authorize endpoint; exchange the code server-side; verify the id_token against the JWKS. The token's claims include the user's Muso identity (sub, email, name and the stable https://muso.ai/user_uuid).
Shipping, not live yet: with the member's consent (scope muso.credits.read), your app will read that member's own published credits with their access token. Never metered. Show what you get through Login with Muso only to the member who signed in. Public display to visitors who are not signed in, and any catalog-wide read, goes through your metered API key.
Put a live, verified Muso profile card on any web page with two lines of HTML — like a YouTube embed for music credits. Uses a publishable key that's safe in public code.
Console → Keys → Publishable → create. Register the domains that may use it. mpk_ keys are read-only and safe to ship in page source.
One div, one script. The widget renders in an isolated Shadow DOM — it inherits the Muso look and never touches your page's styles. If anything fails it renders nothing rather than break your site.
<div data-muso-profile="e979669b-d99b-46be-91d6-bf1f1e2f44bf" data-muso-key="mpk_your_key"></div> <script src="https://platform.muso.ai/embed/v1.js" async></script>
Building in React? The <MusoProfileCard/> component is built but not on public npm yet — the hosted script renders the same card in a React app today.
Looking for a package, the CLI, or the OpenAPI spec? Downloads & resources has every asset and where to get it.
x-api-key: msk_51Ab…redacted
11 operations across 3 tags in one machine-readable document. Generate clients, mocks, and types from the spec.
/v1x-muso-version: 2026-06-01 sunset: Wed, 01 Apr 2026 00:00:00 GMT # only on deprecated routes deprecation: true
Throughput is capped so the graph can't be cloned. Every response carries pacing headers; a 429 always includes Retry-After.
| Header | Example | Meaning |
|---|---|---|
RateLimit-Limit | 30 | Requests permitted per minute on the active key. |
RateLimit-Remaining | 29 | Requests left in the current window. |
RateLimit-Reset | 35 | SECONDS until the window refills — not a timestamp. |
X-RateLimit-Limit-Minute | 30 | Per-minute view of the same budget (sent alongside the above). |
X-Kong-Request-Id | 6925703b19f0c6484300e429c8d91d59 | Identifies this exact request. Echo it in any support report. |
HTTP/2 200 content-type: application/json RateLimit-Limit: 30 RateLimit-Remaining: 29 RateLimit-Reset: 35 X-RateLimit-Limit-Minute: 30 X-RateLimit-Remaining-Minute: 29 X-Kong-Request-Id: 6925703b19f0c6484300e429c8d91d59
HTTP/2 429 Retry-After: 35 RateLimit-Remaining: 0 RateLimit-Reset: 35 X-Kong-Request-Id: 6925703b19f0c6484300e429c8d91d59 # 429 comes from the gateway, so it carries the gateway error shape # (a message, no result/code envelope). Wait RateLimit-Reset seconds.
Log X-Request-Id — fastest path to a resolution. Pair it in the support email.
List endpoints page with limit and offset, and report the full size as totalCount. Read rows from data.items.
# First page — limit/offset. MAX limit is 50; asking for more is a 400.
GET https://api.platform.muso.ai/v1/profile/e979669b-d99b-46be-91d6-bf1f1e2f44bf/credits?limit=50&offset=0
{
"result": "ok",
"code": 200,
"data": {
"limit": 50,
"offset": 0,
"totalCount": 11701,
"items": [ /* up to 50 records */ ]
}
}
# Next page — advance offset by limit. Stop when offset >= totalCount
# (a page past the end returns items: [], not an error).
GET https://api.platform.muso.ai/v1/profile/e979669b-d99b-46be-91d6-bf1f1e2f44bf/credits?limit=50&offset=50Two shapes, and which one you get tells you how far the request travelled. The API answers with the same envelope it uses for success — result: "error", code, message. The gateway rejects auth and quota problems before the API runs, so those carry message and a request_id instead.
# API errors — same {result, code} envelope as a success, result: "error"
HTTP/2 400
{ "result": "error", "code": 400, "message": "Too big page, max page size is 50" }
# Gateway errors — your request never reached the API, so there is no
# result/code envelope. Log request_id; it is what support will ask for.
HTTP/2 401
{ "message": "No API key found in request", "request_id": "6925703b19f0c6484300e429c8d91d59" }| Status | Raised by | When |
|---|---|---|
| 400 | API | Bad request — e.g. limit above 50 ("Too big page, max page size is 50") or an id that resolves to nothing ("Profile not found"). |
| 401 | Gateway | No key sent ("No API key found in request") or the key is unknown/revoked ("Unauthorized"). |
| 403 | Gateway | The key is valid but not entitled to this route — e.g. a publishable mpk_ key against the paid /v1 API ("You cannot consume this service"). |
| 429 | Gateway | Per-minute rate limit for your key exceeded. Back off and retry. |
A 401 or 403 means the gateway stopped you, so retrying the same request will not help — fix the key. A 400 came from the API and its message says exactly what to change.
Put a live, verified Muso profile card or roster on any website — like a YouTube embed for music credits. Two lines of HTML, or a React component. Both use a publishable key that's safe in public code.
A second key type for browser code. Publishable keys (mpk_) are read-only, locked to your domains, and safe to ship in page source — the credential the widgets use.
| Secret key · msk_ | Publishable · mpk_ |
|---|---|
| Server-side only | Safe in browser / page source |
| Full catalog + writes | Read-only: profile + credits + charts |
| Any origin | Locked to your registered domains |
Base https://api.platform.muso.ai/v1 | Base https://api.platform.muso.ai/embed/v1 |
Give Claude, ChatGPT, or any agent tool-based access to the credit graph — ask 'who produced this track?' in plain language and get real answers. Twelve live tools, on the same key and meter as the REST API.
| Tool | What it does | Required arguments | Endpoint |
|---|---|---|---|
search | Keyword search across profiles, tracks, albums | keyword | POST /search |
search_autocomplete | Fast typeahead | q | GET /search/autocomplete |
search_profiles | Resolve profiles for a known track | names + track_ids or spotify_track_ids | GET /profiles/search |
get_profile | Profile identity, stats, links | id_value | GET /profile/{id} |
get_profile_credits | Verified credits (paginated) | id_value | GET /profile/{id}/credits |
get_profile_collaborators | Who they've worked with | id_value | GET /profile/{id}/collaborators |
get_profile_charts | Chart / analytics positions | id_value | GET /profile/{id}/charts |
get_track | Recording by ISRC or id | id_key, id_value | GET /track/{idKey}/{idValue} |
get_track_albums | Albums a recording appears on | id_key, id_value | GET /track/{k}/{v}/albums |
get_album | Album by UPC or id | id_key, id_value | GET /album/{idKey}/{idValue} |
get_album_credits | An album's full credit list | id_key, id_value | GET /album/{k}/{v}/credits |
get_roles | The credit-role taxonomy | (none) | GET /roles |
Works on any paid metered key — no separate MCP fee. Each tool call is one metered read.
Look up verified credits, profiles, and search from your terminal — then copy the same calls into your app. One binary, your secret key, the live API.
| Command | What it does |
|---|---|
muso login / logout | Store / clear your key |
muso whoami | Verify the active key |
muso profile <id> | Profile identity + headline stats |
muso credits <id> | Verified credits (paged, --limit/--offset) |
muso search <query> | Type-ahead across the catalog |
muso track <isrc> | A recording by ISRC |
muso usage | Current rate-limit headroom |
The muso CLI is built but not yet public; use the REST API or MCP server today. All calls use your account's standard metered API; no separate CLI fee.
Push live analytics deltas to your app over a WebSocket instead of polling — chart moves and consumption signals as they happen. Part of the streaming-analytics tier; the delivery endpoint is rolling out.
One key, four surfaces. SDKs handle auth, retries with backoff, and limit/offset paging.
Users sign in with their Muso account, so your app knows who they are. Sharing their own credits with your app (with consent, never metered) is shipping. Standard OpenID Connect, user-consented, scoped to the signed-in user's own data.
Register your app — the $99/mo per-app SSO fee is the publishing gate. We provision your OIDC client credentials and register your redirect URIs.
Authorization-code + PKCE against login.muso.ai — the same flow you already use for Google or Apple. Any standard OIDC library works.
Your app gets a verified id_token for the signed-in Muso user, including a stable Muso user id.
# Discovery — endpoints, keys, everything your OIDC library needs curl https://login.muso.ai/.well-known/openid-configuration # authorization_endpoint https://login.muso.ai/api/auth/oauth2/authorize # token_endpoint https://login.muso.ai/api/auth/oauth2/token # userinfo_endpoint https://login.muso.ai/api/auth/oauth2/userinfo # jwks_uri https://login.muso.ai/api/auth/jwks # grants authorization_code (+ PKCE), refresh_token # scopes openid profile email offline_access
Already pay for Muso Pro or Business? Your own roster's credits & stats are free through the Workspace API key — a read-only key scoped to the profiles on your roster. It's issued and managed inside the Muso app, not here.
How capacity, billing, and account features work — everything is self-service.
Your subscription licenses Muso credits & stats for use INSIDE your own application, for your own users. It does not grant the right to resell, redistribute, or feed Muso data into another product or service — and it is a LIVE license: data is fetched from the API at the moment of use, never stored on your side.
Everything we ship, in one place — with exactly where to get it. Hosted resources work right now with no install. Client libraries are publishing to public registries (scoped GitHub Packages today); the hosted embed script and API need no package at all.