MusicXen for Developers

The MusicXen public API lets your apps and websites use MusicXen's public band, venue, and show data — and submit listens ("scrobbles") to your own listening history. It's the same API foundation the official MusicXen apps are built on.

1. Get a key

Sign in, open Settings → Developer API, name your app, pick its scopes, and create a key. Your key is shown exactly once — we store only a hash of it. Keys look like mxk_…. Treat a key like a password: don't publish it, don't commit it to a public repository. If one leaks, revoke it in Settings and make a new one.

2. Authenticate

Send the key on every request, either way:

Authorization: Bearer mxk_your_key_here
X-API-Key: mxk_your_key_here

Verify a key and see its scopes and limits:

curl -H "Authorization: Bearer mxk_…" https://musicxen.onrender.com/api/v1/public/ping

3. Endpoints

Endpoint	Scope	What it returns
`GET /api/v1/public/ping`	public	Key check: name, scopes, rate limits.
`GET /api/v1/public/bands`	public	Band list. Filters: `q`, `city`. Paging: `page`, `per_page`.
`GET /api/v1/public/bands/{id}`	public	Band detail: bio, members (names and positions), upcoming shows.
`GET /api/v1/public/venues`	public	Venue list. Filters: `q`, `city`.
`GET /api/v1/public/venues/{id}`	public	Venue detail: address, capacity, age policy, upcoming shows.
`GET /api/v1/public/shows`	public	Upcoming shows. Filters: `band_id`, `venue_id`, `city`.
`POST /api/v1/public/scrobbles`	scrobble	Submit one listen to the key owner's history (see below).

All responses are JSON. Lists are wrapped: { "bands": […], "page": 1, "per_page": 20, "total": 42 }. Errors use standard HTTP status codes with a detail message: 401 (missing/invalid key), 403 (key lacks the scope), 404, 429 (rate limited).

4. Example: a band's live calendar

The most popular use: put a band's MusicXen shows on the band's own website.

curl -H "Authorization: Bearer mxk_…" \
  "https://musicxen.onrender.com/api/v1/public/shows?band_id=12"

{ "shows": [ { "id": 34, "title": "…", "venue_name": "…",
               "venue_id": 5, "date": "2026-11-02T20:00:00",
               "bands": ["…"], "ticket_url": "" } ], … }

5. Scrobbling

With a key that has the scrobble scope, your app can record listens to your own MusicXen listening history — the same history the MusicXen Player builds. (A key can only ever write to its owner's account.)

curl -X POST -H "Authorization: Bearer mxk_…" \
  -H "Content-Type: application/json" \
  -d '{"artist": "Savatage", "title": "Hall of the Mountain King",
       "played_at": "2026-10-14T13:05:00Z"}' \
  https://musicxen.onrender.com/api/v1/public/scrobbles

Required: artist, title, played_at (ISO 8601). Optional: album, release_year, duration_sec, track_id (a MusicXen track), external_app (defaults to your key's app name). Re-submitting the same listen within a minute returns the existing record instead of a duplicate. Listening history stays private unless the owner makes it public — the API never exposes anyone's listening history to other keys.

6. Rate limits

Per key: 300 reads/hour and 300 scrobbles/hour. Exceeding them returns 429 — back off and retry after the hour window. If you need more for a real project, ask us.

7. Sign in with MusicXen (OAuth)

Let MusicXen members sign in to your app with their MusicXen account — and, only with their approval on a consent screen, read their profile basics, listening history, or playlists. Register your app in Settings → Developer API ("Sign in with MusicXen"); you'll get a client ID and a client secret (shown once).

Flow (authorization code):

Send the member to GET /oauth/authorize?response_type=code&client_id=…&redirect_uri=YOUR_REGISTERED_URI&scope=profile&state=… — the redirect URI must match the registered one exactly.
After they approve, we redirect back with ?code=…&state=… (codes live 10 minutes, single use).
Exchange it: POST /api/v1/oauth/token with form fields grant_type=authorization_code, code, redirect_uri, client_id, client_secret. You get an access token (30 days) and a refresh token (90 days); refreshing rotates both.

Endpoints (header Authorization: Bearer <access token>):

GET /api/v1/oauth/me — scope profile: id, username, display name, city/state, profile URL, member-since. Never email, phone, or date of birth.
GET /api/v1/oauth/listening/recent and GET /api/v1/oauth/listening/stats — scope listening. Consent covers history the member keeps private on MusicXen itself — that's what the approval means.
GET /api/v1/oauth/playlists — scope playlists.

Members can revoke your app any time in Settings; revoking kills its tokens immediately.

8. Managing shows + webhooks

API keys can carry the manage scope. With it, the key's owner can manage shows for bands they admin/book for and venues they manage:

POST /api/v1/public/shows — JSON {"band_id": …, "venue_id": …, "show_date": "YYYY-MM-DD", "ticket_url": "…", "cover_price": "…", "notes": "…"}
PATCH /api/v1/public/shows/{id} — change date, venue, ticket link, cover, or notes.
DELETE /api/v1/public/shows/{id} — cancel the show.

Webhooks: register a URL in Settings → Developer API and pick events (show.created, show.updated, show.cancelled, follower.new). We POST JSON with headers X-MusicXen-Event and X-MusicXen-Signature (HMAC-SHA256 of the raw body with your webhook's secret). Verify the signature before trusting a delivery.

9. API terms

Public data only: the API never returns member email addresses, phone numbers, dates of birth, messages, or private listening history. Don't attempt to reconstruct private data from the API.
Don't resell API data as a dataset, and don't use it to send spam (see the Anti-Spam Policy).
Cache politely and respect rate limits; abusive keys can be revoked.
Where reasonable, credit MusicXen and link back to the band or venue's MusicXen page (each record includes its profile_url).
The Terms of Service and Privacy Policy govern API use. The API is provided as-is; endpoints may evolve with notice on this page.

Questions: musicxen@gmail.com