FitRadio Partner API (2.0.0)

The FitRadio Partner API gives approved partners access to FitRadio's licensed workout-music catalog. The content model is a simple hierarchy:

Catalog → Page → List → Mix

1. GET /partners/catalog returns the pages (music rows) of the partner catalog.
2. GET /partners/page/{page_id} returns the lists on one page.
3. GET /partners/list/{list_id} returns the mixes in one list.
4. GET /partners/mix/{mix_id} returns one mix with its playable HLS/MP3 URLs, artwork, DJ, and full track listing.
5. POST /partners/royalty-tracking reports every track play back to FitRadio — required for licensing compliance.

All endpoints are served from https://p.fitradio.com.

All endpoints except the two POST /partners/session* endpoints require a session token.

1. FitRadio issues you a client_id and client_signature out of band.
2. Call POST /partners/session with them. The response contains a JWT session token.
3. Send that token on every subsequent request in the Authorization header.

Important — send the raw token. The Authorization header value must be the JWT by itself, with no Bearer prefix and no other decoration:

Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOi...

A value of Bearer eyJ... is rejected with 401.

There is no X-Client-Id header anywhere in this API. Older documentation that mentioned one was wrong — the session token is the only credential sent on API calls.

Tokens expire 8 hours after issue. Any 401 response means your token is missing, malformed, expired, or was minted during standby mode (see below) — create a new session and retry. Build automatic re-authentication on 401 into your client.

# 1. Create a session
curl -s -X POST https://p.fitradio.com/partners/session \
  -H 'Content-Type: application/json' \
  -d '{"client_id": "YOUR_CLIENT_ID", "client_signature": "YOUR_CLIENT_SIGNATURE"}'
# → {"session":{"token":{"token":"eyJhbGciOi...","error":null}}}

TOKEN='eyJhbGciOi...'   # the inner session.token.token value, used raw

# 2. Discover content
curl -s https://p.fitradio.com/partners/catalog        -H "Authorization: $TOKEN"
curl -s https://p.fitradio.com/partners/page/71        -H "Authorization: $TOKEN"
curl -s https://p.fitradio.com/partners/list/529       -H "Authorization: $TOKEN"
curl -s https://p.fitradio.com/partners/mix/9252       -H "Authorization: $TOKEN"

# 3. Report a play (required for every track you play)
curl -s -X POST https://p.fitradio.com/partners/royalty-tracking \
  -H "Authorization: $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "trackid": 704991,
    "playedat": 1754380800000,
    "playlength": 213,
    "sourcestream": "mix",
    "sourcedetail": "9252",
    "os": "web",
    "device": "chrome",
    "country": "US",
    "vendor": 12,
    "userid": "partner-user-42",
    "isrc": "USUM71703861",
    "endreason": 1
  }'

These rules exist because getting them wrong silently corrupts royalty reporting. Please read them carefully.

Catalog, page, list and mix responses are not filtered by country: every partner sees the same catalog. The country field of a royalty report is required and must be the listener's country (ISO 3166-1 alpha-2); a report without it is rejected with 400. It is never inferred from the request's IP or headers.

Requesting a page or list id that has no content returns 400 with reason: "no results for given type".

When FitRadio's primary database is unavailable, the API automatically fails over to a read-only standby service so playback keeps working. What changes for you:

• Responses include the header x-fitradio-served-by: standby (or live-bypass). Absence of the header means normal live service.
• POST /partners/session succeeds without verifying credentials and returns a short-lived token (~15 minutes) — and the response shape flattens: session.token is the JWT string directly instead of the live {token, error} object. Extract with typeof session.token === 'string' ? session.token : session.token.token.
• Standby-minted tokens are rejected with 401 the moment normal service resumes. This is the main reason your client must re-authenticate automatically on any 401.
• Some catalog metadata is served from cache and may be degraded (e.g. a mix's min_bpm/max_bpm may be equal, description may be empty).
• POST /partners/royalty-tracking accepts and acknowledges reports; queue and re-send your reports after standby ends if you require delivery guarantees.

Two error envelopes are in use:

• Most endpoints: { "error": true, "reason": "<human-readable message>", "mix": null } (the legacy mix field is always null and can be ignored).
• POST /partners/royalty-tracking: { "error": true, "message": "<human-readable message>" }.
• 401 responses from the authentication layer have a plain-text body (Unauthorized), not JSON.

• Raw OpenAPI spec
• Postman collection

Exchange your partner credentials for a session token. Tokens live 8 hours; send them raw in the Authorization header (no Bearer prefix). Re-authenticate automatically whenever you receive a 401.

The entry point for content discovery: the pages (music rows) of the partner catalog. Use /partners/catalog/restricted if your partner agreement scopes you to a subset of the catalog.

A page (music row) groups related lists — e.g. a genre or featured collection. Returns the lists on the page.

A list is an ordered collection of mixes (a station or curated genre list). Returns list metadata plus lightweight mix summaries.

Raw items of a single music row, with the full artwork set per item.

A mix is a continuous DJ mix. The detail endpoint returns everything needed for playback and compliance: HLS stream URLs (iOS/Android renditions), MP3 URL, artwork, DJ info, and the full track listing with ISRCs.

Report every track play. Required for licensing compliance — integrations are not approved for launch until reporting is verified end-to-end by FitRadio. Read the Data types and formats section above before implementing.