{ "item": [ { "name": "authentication", "description": "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`.", "item": [ { "id": "44d36e5f-7c73-4301-8d5c-12a393a1053b", "name": "Create a session token", "request": { "name": "Create a session token", "description": { "content": "Exchanges your `client_id` + `client_signature` for an 8-hour JWT session token.\n\nDuring normal service the token is at `session.token.token` (note the nesting — this differs from `/partners/session/with-user`, where `session.token` is the string itself). Send it raw in the `Authorization` header on all other endpoints.\n\n**During standby mode the shape differs**: the endpoint returns a short-lived (~15 min) token *without verifying credentials*, and `session.token` is the JWT **string directly** (no inner object). Handle both: `typeof session.token === 'string' ? session.token : session.token.token`. Standby-minted tokens stop working (401) as soon as normal service resumes.", "type": "text/plain" }, "url": { "path": [ "partners", "session" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"client_id\": \"a1b2c3d4e5\",\n \"client_signature\": \"f6e5d4c3b2a1098765432109876543210fedcba9\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": { "type": "noauth" } }, "response": [ { "id": "e2b7c1a8-790d-4cd2-8dfc-5631d0be1fd5", "name": "Session created. `session.token` is an object during normal service and a plain JWT string during standby mode (see examples).", "originalRequest": { "url": { "path": [ "partners", "session" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"client_id\": \"a1b2c3d4e5\",\n \"client_signature\": \"f6e5d4c3b2a1098765432109876543210fedcba9\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "x-fitradio-served-by", "value": "" } ], "body": "{\n \"session\": {\n \"token\": {\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJhMWIyYzNkNGU1IiwidWlkIjoxMjUwOTQ3NiwiaWF0IjoxNzU0MzgwODAwLCJleHAiOjE3NTQ0MDk2MDB9.signature\",\n \"error\": null\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bfed68fc-b907-4f73-abdb-be3d14ea0000", "name": "Credentials invalid.", "originalRequest": { "url": { "path": [ "partners", "session" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"client_id\": \"a1b2c3d4e5\",\n \"client_signature\": \"f6e5d4c3b2a1098765432109876543210fedcba9\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"credentials invalid\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d37bc86e-4bf4-497d-9572-9a8da4801856", "name": "`client_id` or `client_signature` missing from the request body.", "originalRequest": { "url": { "path": [ "partners", "session" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"client_id\": \"a1b2c3d4e5\",\n \"client_signature\": \"f6e5d4c3b2a1098765432109876543210fedcba9\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"please provide user information to create session: email, salt\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "02ab356a-6b05-406c-90da-b1e8eb47a36c", "name": "Internal error. Retry with backoff; contact FitRadio if it persists.", "originalRequest": { "url": { "path": [ "partners", "session" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"client_id\": \"a1b2c3d4e5\",\n \"client_signature\": \"f6e5d4c3b2a1098765432109876543210fedcba9\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"internal service error\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "24839597-d7a4-464f-a411-863b5a4dcc9b", "name": "Create a session token bound to a partner account", "request": { "name": "Create a session token bound to a partner account", "description": { "content": "Like `POST /partners/session`, but additionally requires the partner account `email` registered with FitRadio and binds the token to that partner identity. Use this variant if your agreement uses the restricted catalog (`GET /partners/catalog/restricted`) — the restricted endpoint filters by the partner identity carried in this token.\n\n**Note the response shape difference:** here `session.token` is the JWT string directly, while `/partners/session` nests it one level deeper (`session.token.token`).", "type": "text/plain" }, "url": { "path": [ "partners", "session", "with-user" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"client_id\": \"a1b2c3d4e5\",\n \"client_signature\": \"f6e5d4c3b2a1098765432109876543210fedcba9\",\n \"email\": \"integration@yourcompany.com\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": { "type": "noauth" } }, "response": [ { "id": "0a9bfbe1-1bd6-423e-9742-db122f575e1b", "name": "Session created.", "originalRequest": { "url": { "path": [ "partners", "session", "with-user" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"client_id\": \"a1b2c3d4e5\",\n \"client_signature\": \"f6e5d4c3b2a1098765432109876543210fedcba9\",\n \"email\": \"integration@yourcompany.com\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "x-fitradio-served-by", "value": "" } ], "body": "{\n \"session\": {\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJhMWIyYzNkNGU1IiwidWlkIjo0MiwiaWF0IjoxNzU0MzgwODAwLCJleHAiOjE3NTQ0MDk2MDB9.signature\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e431a81c-8031-4614-b319-33ed6071d79c", "name": "Credentials invalid, partner not found for the given email, or session creation failed.", "originalRequest": { "url": { "path": [ "partners", "session", "with-user" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"client_id\": \"a1b2c3d4e5\",\n \"client_signature\": \"f6e5d4c3b2a1098765432109876543210fedcba9\",\n \"email\": \"integration@yourcompany.com\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"credentials invalid\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5c9dd60e-a376-4e9a-8f1c-9bffc466d6db", "name": "`client_id` or `client_signature` missing from the request body.", "originalRequest": { "url": { "path": [ "partners", "session", "with-user" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"client_id\": \"a1b2c3d4e5\",\n \"client_signature\": \"f6e5d4c3b2a1098765432109876543210fedcba9\",\n \"email\": \"integration@yourcompany.com\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"please provide user information to create session: email, client_id, client_signature\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b91441bc-6ce8-437c-ae4b-29ff08b75da5", "name": "Internal error. Retry with backoff; contact FitRadio if it persists.", "originalRequest": { "url": { "path": [ "partners", "session", "with-user" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"client_id\": \"a1b2c3d4e5\",\n \"client_signature\": \"f6e5d4c3b2a1098765432109876543210fedcba9\",\n \"email\": \"integration@yourcompany.com\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"internal service error\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "catalog", "description": "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.", "item": [ { "id": "774bf478-f079-4d8e-8e72-897f0de36d2c", "name": "List catalog pages", "request": { "name": "List catalog pages", "description": { "content": "Returns the pages (music rows) of the partner catalog — the top level of the content hierarchy. Use each entry's `page_id` with `GET /partners/page/{page_id}`.", "type": "text/plain" }, "url": { "path": [ "partners", "catalog" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "a85b3e3e-6b19-44d2-a362-2d769250a367", "name": "Catalog pages.", "originalRequest": { "url": { "path": [ "partners", "catalog" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "x-fitradio-served-by", "value": "" } ], "body": "{\n \"catalogs\": [\n {\n \"page_id\": 71,\n \"title\": \"Featured\",\n \"type\": \"genre\",\n \"ranking\": 1,\n \"list_count\": 12\n },\n {\n \"page_id\": 46,\n \"title\": \"SWEATBASE\",\n \"type\": \"genre\",\n \"ranking\": 2,\n \"list_count\": 8\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "17f30354-d4c9-4a28-b595-0188f6206a32", "name": "No catalog available.", "originalRequest": { "url": { "path": [ "partners", "catalog" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"no catalogs available\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "eb1d0c24-85df-45a1-a96b-9007f72c3a8c", "name": "Session token missing, malformed, expired, or minted during standby. The body is plain text, not JSON. Create a new session via `POST /partners/session` and retry.", "originalRequest": { "url": { "path": [ "partners", "catalog" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "text/plain" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "Unauthorized", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "a2cecce8-cfd6-47e5-a3bc-0a766db33346", "name": "Internal error. Retry with backoff; contact FitRadio if it persists.", "originalRequest": { "url": { "path": [ "partners", "catalog" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"internal service error\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "27ff15b4-a8c2-4e70-b02a-e9fccdfb8e55", "name": "The standby failover failed to serve the request. Retry with backoff.", "originalRequest": { "url": { "path": [ "partners", "catalog" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"standby upstream error\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "be69188f-0f68-4649-aece-382a74c0f6d3", "name": "List catalog pages allowed for your partner account", "request": { "name": "List catalog pages allowed for your partner account", "description": { "content": "Same shape as `GET /partners/catalog`, additionally filtered by the content restrictions configured for your partner account.\n\nThe partner identity is read from the session token, so call this with a token from `POST /partners/session/with-user`. With a plain `/partners/session` token (no partner identity), the response falls back to the unrestricted country catalog.", "type": "text/plain" }, "url": { "path": [ "partners", "catalog", "restricted" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "ISO 3166-1 alpha-2 country. On production Cloudflare sets it automatically from the caller's IP; server-to-server integrations may send it explicitly. Read only by this endpoint (the partner-restriction lookup is per country); values that are not exactly two letters are ignored.", "type": "text/plain" }, "key": "CF-IPCountry", "value": "US" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "50309dc0-4063-4d78-9836-c73dec5f1a68", "name": "Catalog pages allowed for this partner.", "originalRequest": { "url": { "path": [ "partners", "catalog", "restricted" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "ISO 3166-1 alpha-2 country. On production Cloudflare sets it automatically from the caller's IP; server-to-server integrations may send it explicitly. Read only by this endpoint (the partner-restriction lookup is per country); values that are not exactly two letters are ignored.", "type": "text/plain" }, "key": "CF-IPCountry", "value": "US" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "x-fitradio-served-by", "value": "" } ], "body": "{\n \"catalogs\": [\n {\n \"page_id\": 46,\n \"title\": \"SWEATBASE\",\n \"type\": \"genre\",\n \"ranking\": 1,\n \"list_count\": 8\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e879495c-be72-449c-afd2-e281b7ccaa85", "name": "No catalog available for this partner.", "originalRequest": { "url": { "path": [ "partners", "catalog", "restricted" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "ISO 3166-1 alpha-2 country. On production Cloudflare sets it automatically from the caller's IP; server-to-server integrations may send it explicitly. Read only by this endpoint (the partner-restriction lookup is per country); values that are not exactly two letters are ignored.", "type": "text/plain" }, "key": "CF-IPCountry", "value": "US" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"no catalogs available for this partner\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4c7e7b52-05ad-4a9f-9477-d25fb99eb3a0", "name": "Session token missing, malformed, expired, or minted during standby. The body is plain text, not JSON. Create a new session via `POST /partners/session` and retry.", "originalRequest": { "url": { "path": [ "partners", "catalog", "restricted" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "ISO 3166-1 alpha-2 country. On production Cloudflare sets it automatically from the caller's IP; server-to-server integrations may send it explicitly. Read only by this endpoint (the partner-restriction lookup is per country); values that are not exactly two letters are ignored.", "type": "text/plain" }, "key": "CF-IPCountry", "value": "US" }, { "key": "Accept", "value": "text/plain" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "Unauthorized", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "8ac54127-9021-404b-9495-04b401416898", "name": "Internal error. Retry with backoff; contact FitRadio if it persists.", "originalRequest": { "url": { "path": [ "partners", "catalog", "restricted" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "ISO 3166-1 alpha-2 country. On production Cloudflare sets it automatically from the caller's IP; server-to-server integrations may send it explicitly. Read only by this endpoint (the partner-restriction lookup is per country); values that are not exactly two letters are ignored.", "type": "text/plain" }, "key": "CF-IPCountry", "value": "US" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"internal service error\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e9c9a05d-bd35-4c44-97fc-5d0d2c10df10", "name": "The standby failover failed to serve the request. Retry with backoff.", "originalRequest": { "url": { "path": [ "partners", "catalog", "restricted" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "ISO 3166-1 alpha-2 country. On production Cloudflare sets it automatically from the caller's IP; server-to-server integrations may send it explicitly. Read only by this endpoint (the partner-restriction lookup is per country); values that are not exactly two letters are ignored.", "type": "text/plain" }, "key": "CF-IPCountry", "value": "US" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"standby upstream error\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "page", "description": "A page (music row) groups related lists — e.g. a genre or featured collection. Returns the lists on the page.", "item": [ { "id": "7499942e-ff31-425c-9c99-8677b342cdc1", "name": "Get the lists on a page", "request": { "name": "Get the lists on a page", "description": { "content": "Returns the lists on one catalog page. Use each list's `list_id` with `GET /partners/list/{list_id}`.", "type": "text/plain" }, "url": { "path": [ "partners", "page", ":page_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "71", "key": "page_id", "disabled": false, "description": { "content": "(Required) Page id from `GET /partners/catalog` (`page_id`).", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "8344a8ed-5cf8-4708-abeb-510691ff91fa", "name": "The page with its lists.", "originalRequest": { "url": { "path": [ "partners", "page", ":page_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Page id from `GET /partners/catalog` (`page_id`).", "type": "text/plain" }, "type": "any", "value": "71", "key": "page_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "x-fitradio-served-by", "value": "" } ], "body": "{\n \"page\": {\n \"id\": 71,\n \"title\": \"Featured\",\n \"lists\": [\n {\n \"list_id\": 529,\n \"ranking\": 1,\n \"title\": \"Straight Outta Hollywood\",\n \"description\": \"Hip hop and Top 40 for lifting and HIIT workouts.\",\n \"mix_count\": 14,\n \"image\": {\n \"thumbnail\": \"https://cdn.fitradio.com/resources/artwork/android_xxhdpi/0362102862_thumb.jpg\",\n \"large\": \"https://cdn.fitradio.com/resources/artwork/0857061661_large.jpg\",\n \"player\": \"https://cdn.fitradio.com/resources/artwork/1768199292_player.jpg\"\n }\n }\n ]\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "46168dce-676b-4eb5-9453-c2a6861e589c", "name": "Missing/unknown page id, or the page has no content.", "originalRequest": { "url": { "path": [ "partners", "page", ":page_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Page id from `GET /partners/catalog` (`page_id`).", "type": "text/plain" }, "type": "any", "value": "71", "key": "page_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"no results for given type\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d80c5522-04c5-40ca-9c5f-29898c80f8e7", "name": "Session token missing, malformed, expired, or minted during standby. The body is plain text, not JSON. Create a new session via `POST /partners/session` and retry.", "originalRequest": { "url": { "path": [ "partners", "page", ":page_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Page id from `GET /partners/catalog` (`page_id`).", "type": "text/plain" }, "type": "any", "value": "71", "key": "page_id" } ] }, "header": [ { "key": "Accept", "value": "text/plain" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "Unauthorized", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "5f2d9a1f-be1d-4abb-abab-509aef77efe0", "name": "Internal error. Retry with backoff; contact FitRadio if it persists.", "originalRequest": { "url": { "path": [ "partners", "page", ":page_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Page id from `GET /partners/catalog` (`page_id`).", "type": "text/plain" }, "type": "any", "value": "71", "key": "page_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"internal service error\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b9ef99bc-5f05-4c7c-abcd-6d093951daa1", "name": "The standby failover failed to serve the request. Retry with backoff.", "originalRequest": { "url": { "path": [ "partners", "page", ":page_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Page id from `GET /partners/catalog` (`page_id`).", "type": "text/plain" }, "type": "any", "value": "71", "key": "page_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"standby upstream error\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "list", "description": "A list is an ordered collection of mixes (a station or curated genre list). Returns list metadata plus lightweight mix summaries.", "item": [ { "id": "d6601cd4-31a6-41c9-a922-879a8f849f32", "name": "Get the mixes in a list", "request": { "name": "Get the mixes in a list", "description": { "content": "Returns one list's metadata plus lightweight summaries of its mixes. Use each mix's `id` with `GET /partners/mix/{mix_id}` to get playable URLs and the track listing.", "type": "text/plain" }, "url": { "path": [ "partners", "list", ":list_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "529", "key": "list_id", "disabled": false, "description": { "content": "(Required) List id from `GET /partners/page/{page_id}` (`list_id`).", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "4ff9d2de-f161-42f5-b445-7f1680ddd91c", "name": "The list with its mixes.", "originalRequest": { "url": { "path": [ "partners", "list", ":list_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) List id from `GET /partners/page/{page_id}` (`list_id`).", "type": "text/plain" }, "type": "any", "value": "529", "key": "list_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "x-fitradio-served-by", "value": "" } ], "body": "{\n \"list\": {\n \"id\": 529,\n \"ranking\": 1,\n \"title\": \"Straight Outta Hollywood\",\n \"description\": \"Hip hop and Top 40 for lifting and HIIT workouts.\",\n \"image\": {\n \"thumbnail\": \"https://cdn.fitradio.com/resources/artwork/android_xxhdpi/0362102862_thumb.jpg\",\n \"large\": \"https://cdn.fitradio.com/resources/artwork/0857061661_large.jpg\",\n \"player\": \"https://cdn.fitradio.com/resources/artwork/1768199292_player.jpg\"\n },\n \"mixes\": [\n {\n \"id\": 9252,\n \"title\": \"Straight Outta Hollywood 3\",\n \"description\": \"General lifting mix of hip hop, top 40, and EDM.\",\n \"length\": \"00:56:13\",\n \"explicit\": 0,\n \"bpm\": 80,\n \"max_bpm\": 150,\n \"list_id\": 529\n }\n ]\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "08dae197-6d06-4b2b-bf09-3c028e70e118", "name": "Missing/unknown list id, or the list has no content.", "originalRequest": { "url": { "path": [ "partners", "list", ":list_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) List id from `GET /partners/page/{page_id}` (`list_id`).", "type": "text/plain" }, "type": "any", "value": "529", "key": "list_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"no results for given type\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e026df98-63a2-4f00-afe9-b4760ea57602", "name": "Session token missing, malformed, expired, or minted during standby. The body is plain text, not JSON. Create a new session via `POST /partners/session` and retry.", "originalRequest": { "url": { "path": [ "partners", "list", ":list_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) List id from `GET /partners/page/{page_id}` (`list_id`).", "type": "text/plain" }, "type": "any", "value": "529", "key": "list_id" } ] }, "header": [ { "key": "Accept", "value": "text/plain" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "Unauthorized", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "044c8a19-9fd8-4f1c-9200-b9823499510a", "name": "Internal error. Retry with backoff; contact FitRadio if it persists.", "originalRequest": { "url": { "path": [ "partners", "list", ":list_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) List id from `GET /partners/page/{page_id}` (`list_id`).", "type": "text/plain" }, "type": "any", "value": "529", "key": "list_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"internal service error\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "fe33e3a6-f78a-4c52-b99c-f77a57490e69", "name": "The standby failover failed to serve the request. Retry with backoff.", "originalRequest": { "url": { "path": [ "partners", "list", ":list_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) List id from `GET /partners/page/{page_id}` (`list_id`).", "type": "text/plain" }, "type": "any", "value": "529", "key": "list_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"standby upstream error\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "genres", "description": "Raw items of a single music row, with the full artwork set per item.", "item": [ { "id": "0ba934bd-f014-466e-979f-9d43fd032dd9", "name": "Get the items of a music row with full artwork", "request": { "name": "Get the items of a music row with full artwork", "description": { "content": "Returns the raw items of a single music row with the complete artwork set per item (wide, spotlight, player, thumbnail, basic). Useful for building richer browse UIs than the catalog/page endpoints allow. Not country-filtered.", "type": "text/plain" }, "url": { "path": [ "partners", "genres", ":music_row_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "46", "key": "music_row_id", "disabled": false, "description": { "content": "(Required) Music row id (same id space as catalog `page_id`).", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "fbb27026-edbd-4107-85c0-4a2b18af9dba", "name": "Items of the music row. `items` is `null` when the row exists but has no items.", "originalRequest": { "url": { "path": [ "partners", "genres", ":music_row_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Music row id (same id space as catalog `page_id`).", "type": "text/plain" }, "type": "any", "value": "46", "key": "music_row_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "x-fitradio-served-by", "value": "" } ], "body": "{\n \"rows\": {\n \"items\": [\n {\n \"id\": 529,\n \"title\": \"Straight Outta Hollywood\",\n \"description\": \"Hip hop and Top 40 for lifting and HIIT workouts.\",\n \"bpm\": 80,\n \"image\": \"https://cdn.fitradio.com/resources/artwork/0857061661_large.jpg\",\n \"image_wide_url\": \"https://cdn.fitradio.com/resources/artwork/0857061661_wide.jpg\",\n \"player_image\": \"https://cdn.fitradio.com/resources/artwork/1768199292_player.jpg\",\n \"thumbnail\": \"https://cdn.fitradio.com/resources/artwork/0362102862_thumb.jpg\",\n \"basic_image\": \"https://cdn.fitradio.com/resources/artwork/0857061661_basic.jpg\",\n \"wide_image\": \"https://cdn.fitradio.com/resources/artwork/0857061661_wide.jpg\",\n \"spotlight_image\": \"https://cdn.fitradio.com/resources/artwork/0857061661_spot.jpg\",\n \"ordering\": 1\n }\n ]\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "fbe59e5b-90ed-4506-ae20-ec90d943ed30", "name": "Music row id missing from the URL.", "originalRequest": { "url": { "path": [ "partners", "genres", ":music_row_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Music row id (same id space as catalog `page_id`).", "type": "text/plain" }, "type": "any", "value": "46", "key": "music_row_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"please provide a music row id as a URL parameter\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "684cf592-904a-4fe0-90db-267d38960c1c", "name": "Session token missing, malformed, expired, or minted during standby. The body is plain text, not JSON. Create a new session via `POST /partners/session` and retry.", "originalRequest": { "url": { "path": [ "partners", "genres", ":music_row_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Music row id (same id space as catalog `page_id`).", "type": "text/plain" }, "type": "any", "value": "46", "key": "music_row_id" } ] }, "header": [ { "key": "Accept", "value": "text/plain" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "Unauthorized", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "445387a7-d713-4624-9b26-021508e66c96", "name": "Internal error. Retry with backoff; contact FitRadio if it persists.", "originalRequest": { "url": { "path": [ "partners", "genres", ":music_row_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Music row id (same id space as catalog `page_id`).", "type": "text/plain" }, "type": "any", "value": "46", "key": "music_row_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"internal service error\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "12bcb535-7ad2-459b-ada0-87f3fdd8253e", "name": "The standby failover failed to serve the request. Retry with backoff.", "originalRequest": { "url": { "path": [ "partners", "genres", ":music_row_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Music row id (same id space as catalog `page_id`).", "type": "text/plain" }, "type": "any", "value": "46", "key": "music_row_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"standby upstream error\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "mix", "description": "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.", "item": [ { "id": "ba250974-26d9-4f76-baee-7237c5b96050", "name": "Get a mix with playback URLs and track listing", "request": { "name": "Get a mix with playback URLs and track listing", "description": { "content": "Returns everything needed to play one mix and stay license-compliant:\n\n* `android_hls_url` / `ios_hls_url` — ready-to-play HLS manifests per platform. `hls_url` mirrors the Android rendition for backwards compatibility.\n* `url` — the raw MP3.\n* `tracks` — the full track listing with each track's `isrc` and start `time`, which you need for royalty reporting.\n\nThis endpoint is **not** geo-gated.\n\n**Choosing a stream:** pick the HLS manifest for your platform (`ios_hls_url` on Apple platforms, `android_hls_url` elsewhere; treat `hls_url` as a legacy alias). If the chosen manifest fails to load or parse, fall back to the other HLS field, then to the MP3 `url`, rather than surfacing an error to the user.\n\nDuring standby mode, all three HLS fields may point at the same rendition, or may carry a direct MP3 URL instead of an HLS manifest (do not assume the payload is HLS), and some metadata may be degraded (equal `min_bpm`/`max_bpm`, empty `description`).", "type": "text/plain" }, "url": { "path": [ "partners", "mix", ":mix_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "9252", "key": "mix_id", "disabled": false, "description": { "content": "(Required) Mix id from `GET /partners/list/{list_id}` (`mixes[].id`).", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "7479b683-0524-4850-81be-595ac9a57265", "name": "The mix.", "originalRequest": { "url": { "path": [ "partners", "mix", ":mix_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Mix id from `GET /partners/list/{list_id}` (`mixes[].id`).", "type": "text/plain" }, "type": "any", "value": "9252", "key": "mix_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "x-fitradio-served-by", "value": "" } ], "body": "{\n \"mix\": {\n \"id\": 9252,\n \"title\": \"Straight Outta Hollywood 3\",\n \"description\": \"General lifting mix of hip hop, top 40, and EDM.\",\n \"length\": \"00:56:13\",\n \"min_bpm\": 80,\n \"max_bpm\": 150,\n \"explicit\": false,\n \"url\": \"https://cdn.fitradio.com/resources/mixes/1703282564_straight_outta_hollywood_3.mp3\",\n \"android_hls_url\": \"https://cdn.fitradio.com/hls_android/mix_9252_android.m3u8\",\n \"ios_hls_url\": \"https://cdn.fitradio.com/hls_ios/9252/mix_9252.m3u8\",\n \"hls_url\": \"https://cdn.fitradio.com/hls_android/mix_9252_android.m3u8\",\n \"image_large\": \"https://cdn.fitradio.com/resources/artwork/0857061661_art.jpg\",\n \"image_thumbnail\": \"https://cdn.fitradio.com/resources/artwork/ios_retina/0857061661_art.jpg\",\n \"dj\": {\n \"name\": \"Breis Gordan\",\n \"image_large\": \"https://cdn.fitradio.com/resources/artwork/1768199292_dj.jpg\",\n \"image_thumbnail\": \"https://cdn.fitradio.com/resources/artwork/ios_retina/1768199292_dj.jpg\"\n },\n \"tracks\": [\n {\n \"id\": 704991,\n \"time\": \"00:00:00\",\n \"isrc\": \"USUM71703861\",\n \"artist\": \"Example Artist\",\n \"title\": \"Example Track\"\n },\n {\n \"id\": 704992,\n \"time\": \"00:03:33\",\n \"isrc\": \"GBUM71603392\",\n \"artist\": \"Another Artist\",\n \"title\": \"Another Track\"\n }\n ],\n \"genres\": [\n {\n \"id\": 2,\n \"title\": \"Hip Hop\",\n \"description\": \"Hip hop and rap workout mixes.\"\n }\n ],\n \"tags\": [\n \"lifting\",\n \"crossfit\"\n ]\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6ceba459-72d2-4b85-b50c-f659928fcc3b", "name": "Mix id missing from the URL.", "originalRequest": { "url": { "path": [ "partners", "mix", ":mix_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Mix id from `GET /partners/list/{list_id}` (`mixes[].id`).", "type": "text/plain" }, "type": "any", "value": "9252", "key": "mix_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"Please provide a mix ID as a URL parameter\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "90950a01-a0b8-4f46-b5a4-882c2e0848ef", "name": "Session token missing, malformed, expired, or minted during standby. The body is plain text, not JSON. Create a new session via `POST /partners/session` and retry.", "originalRequest": { "url": { "path": [ "partners", "mix", ":mix_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Mix id from `GET /partners/list/{list_id}` (`mixes[].id`).", "type": "text/plain" }, "type": "any", "value": "9252", "key": "mix_id" } ] }, "header": [ { "key": "Accept", "value": "text/plain" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "Unauthorized", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "796bee55-ec1b-4be3-8aa8-be2a72aedc5a", "name": "No mix with this id.", "originalRequest": { "url": { "path": [ "partners", "mix", ":mix_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Mix id from `GET /partners/list/{list_id}` (`mixes[].id`).", "type": "text/plain" }, "type": "any", "value": "9252", "key": "mix_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"Mix not found\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6b32e153-35ad-474d-8c30-7d11edc6972b", "name": "Internal error. Retry with backoff; contact FitRadio if it persists.", "originalRequest": { "url": { "path": [ "partners", "mix", ":mix_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Mix id from `GET /partners/list/{list_id}` (`mixes[].id`).", "type": "text/plain" }, "type": "any", "value": "9252", "key": "mix_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"internal service error\",\n \"mix\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0b781f1b-c622-4673-b415-40972b119f0f", "name": "The standby failover failed to serve the request. Retry with backoff.", "originalRequest": { "url": { "path": [ "partners", "mix", ":mix_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Mix id from `GET /partners/list/{list_id}` (`mixes[].id`).", "type": "text/plain" }, "type": "any", "value": "9252", "key": "mix_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "GET", "body": {} }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"standby upstream error\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "royalty", "description": "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.", "item": [ { "id": "96d2d124-7c0d-4ef1-994e-f1e18630ac79", "name": "Report a track play", "request": { "name": "Report a track play", "description": { "content": "Report every track play — one call per track, sent when the track finishes (or playback stops). Required for licensing compliance.\n\n**Read the *Data types and formats* section first.** The most common integration mistakes, all of which corrupt reporting silently or fail the request:\n\n* `playedat` sent in seconds instead of **milliseconds**\n* numeric fields serialized with a trailing `.0`\n* `userid` or `isrc` omitted (a missing `playlength` fails loudly with `400`)\n\n`isrc` should be echoed from the mix's track listing; if omitted, FitRadio falls back to looking it up from `trackid`, but sending it explicitly is strongly preferred. Send your real per-request values — do not hardcode example payloads from this page.\n\nDuring standby mode (see *Standby mode* in the introduction) reports are accepted with `200` but are not validated or forwarded: the standby layer has no royalty pipeline, so keep reporting and normal processing resumes when live service does.", "type": "text/plain" }, "url": { "path": [ "partners", "royalty-tracking" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"trackid\": 704991,\n \"playedat\": 1754380800000,\n \"playlength\": 213,\n \"sourcestream\": \"mix\",\n \"sourcedetail\": \"Burst of Energy Vol. 7\",\n \"os\": \"iOS 18.1\",\n \"device\": \"iPhone\",\n \"country\": \"US\",\n \"vendor\": 12,\n \"userid\": \"573042\",\n \"isrc\": \"USUM71703861\",\n \"endreason\": 1,\n \"cachedplay\": false,\n \"jumpforward\": false\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "500d0eb8-0483-4edf-9316-02e40d9792cf", "name": "Play accepted by FitRadio's ingest for processing. Downstream processing is asynchronous, so a `200` confirms the report passed validation and was handed off, not that it has finished processing.", "originalRequest": { "url": { "path": [ "partners", "royalty-tracking" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"trackid\": 704991,\n \"playedat\": 1754380800000,\n \"playlength\": 213,\n \"sourcestream\": \"mix\",\n \"sourcedetail\": \"Burst of Energy Vol. 7\",\n \"os\": \"iOS 18.1\",\n \"device\": \"iPhone\",\n \"country\": \"US\",\n \"vendor\": 12,\n \"userid\": \"573042\",\n \"isrc\": \"USUM71703861\",\n \"endreason\": 1,\n \"cachedplay\": false,\n \"jumpforward\": false\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "x-fitradio-served-by", "value": "" } ], "body": "{\n \"error\": false,\n \"message\": \"success\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "944c86eb-db62-4ddd-8b98-1487bfbbd780", "name": "One or more required fields are missing or invalid. `message` lists the offending fields.", "originalRequest": { "url": { "path": [ "partners", "royalty-tracking" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"trackid\": 704991,\n \"playedat\": 1754380800000,\n \"playlength\": 213,\n \"sourcestream\": \"mix\",\n \"sourcedetail\": \"Burst of Energy Vol. 7\",\n \"os\": \"iOS 18.1\",\n \"device\": \"iPhone\",\n \"country\": \"US\",\n \"vendor\": 12,\n \"userid\": \"573042\",\n \"isrc\": \"USUM71703861\",\n \"endreason\": 1,\n \"cachedplay\": false,\n \"jumpforward\": false\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"message\": \"include the required fields: playedat,country\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "790c22f0-0922-4ea5-ae67-868a30670905", "name": "Session token missing, malformed, expired, or minted during standby. The body is plain text, not JSON. Create a new session via `POST /partners/session` and retry.", "originalRequest": { "url": { "path": [ "partners", "royalty-tracking" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "text/plain" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"trackid\": 704991,\n \"playedat\": 1754380800000,\n \"playlength\": 213,\n \"sourcestream\": \"mix\",\n \"sourcedetail\": \"Burst of Energy Vol. 7\",\n \"os\": \"iOS 18.1\",\n \"device\": \"iPhone\",\n \"country\": \"US\",\n \"vendor\": 12,\n \"userid\": \"573042\",\n \"isrc\": \"USUM71703861\",\n \"endreason\": 1,\n \"cachedplay\": false,\n \"jumpforward\": false\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "Unauthorized", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "d5be47e0-13f9-4ff6-a0a7-2a9fc5251fd7", "name": "Internal error. Queue the report and retry with backoff.", "originalRequest": { "url": { "path": [ "partners", "royalty-tracking" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"trackid\": 704991,\n \"playedat\": 1754380800000,\n \"playlength\": 213,\n \"sourcestream\": \"mix\",\n \"sourcedetail\": \"Burst of Energy Vol. 7\",\n \"os\": \"iOS 18.1\",\n \"device\": \"iPhone\",\n \"country\": \"US\",\n \"vendor\": 12,\n \"userid\": \"573042\",\n \"isrc\": \"USUM71703861\",\n \"endreason\": 1,\n \"cachedplay\": false,\n \"jumpforward\": false\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"message\": \"internal service error\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e3c083c6-e5f2-41d2-8ac4-341cca321511", "name": "The standby failover failed to serve the request. Retry with backoff.", "originalRequest": { "url": { "path": [ "partners", "royalty-tracking" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "Authorization", "value": "" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"trackid\": 704991,\n \"playedat\": 1754380800000,\n \"playlength\": 213,\n \"sourcestream\": \"mix\",\n \"sourcedetail\": \"Burst of Energy Vol. 7\",\n \"os\": \"iOS 18.1\",\n \"device\": \"iPhone\",\n \"country\": \"US\",\n \"vendor\": 12,\n \"userid\": \"573042\",\n \"isrc\": \"USUM71703861\",\n \"endreason\": 1,\n \"cachedplay\": false,\n \"jumpforward\": false\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"reason\": \"standby upstream error\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ], "auth": { "type": "apikey", "apikey": [ { "type": "any", "value": "Authorization", "key": "key" }, { "type": "any", "value": "{{apiKey}}", "key": "value" }, { "type": "any", "value": "header", "key": "in" } ] }, "event": [], "variable": [ { "key": "baseUrl", "value": "https://p-staging2.fitradio.com" } ], "info": { "_postman_id": "5c7bb62c-690f-4e5e-96e2-e682279237ae", "name": "FitRadio Partner API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "# Overview\n\nThe FitRadio Partner API gives approved partners access to FitRadio's licensed workout-music catalog. The content model is a simple hierarchy:\n\n**Catalog → Page → List → Mix**\n\n1. `GET /partners/catalog` returns the *pages* (music rows) of the partner catalog.\n2. `GET /partners/page/{page_id}` returns the *lists* on one page.\n3. `GET /partners/list/{list_id}` returns the *mixes* in one list.\n4. `GET /partners/mix/{mix_id}` returns one mix with its playable HLS/MP3 URLs, artwork, DJ, and full track listing.\n5. `POST /partners/royalty-tracking` reports every track play back to FitRadio — required for licensing compliance.\n\n# Base URL\n\nAll endpoints are served from `https://p-staging2.fitradio.com`.\n\nRequests are fronted by Cloudflare, which blocks default script user agents (curl, wget, some HTTP-library defaults) with `403` and Cloudflare error `1010` before they reach the API. Send a distinctive product `User-Agent` header (for example `YourApp/1.0 (partner integration)`) from every client, including test scripts and Postman.\n\n# Authentication\n\nAll endpoints except the two `POST /partners/session*` endpoints require a session token.\n\n1. FitRadio issues you a `client_id` and `client_signature` out of band.\n2. Call `POST /partners/session` with them. The response contains a JWT session token.\n3. Send that token on every subsequent request in the `Authorization` header.\n\n**Important — send the raw token.** The `Authorization` header value must be the JWT *by itself*, with **no `Bearer ` prefix** and no other decoration:\n\n```\nAuthorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOi...\n```\n\nA value of `Bearer eyJ...` is rejected with `401`.\n\nThere 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.\n\nTokens 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.\n\n# Quickstart\n\n```bash\n# 1. Create a session\ncurl -s -A 'YourApp/1.0 (partner integration)' -X POST https://p-staging2.fitradio.com/partners/session \\\n -H 'Content-Type: application/json' \\\n -d '{\"client_id\": \"YOUR_CLIENT_ID\", \"client_signature\": \"YOUR_CLIENT_SIGNATURE\"}'\n# → {\"session\":{\"token\":{\"token\":\"eyJhbGciOi...\",\"error\":null}}}\n\nTOKEN='eyJhbGciOi...' # the inner session.token.token value, used raw\n\n# 2. Discover content\ncurl -s -A 'YourApp/1.0 (partner integration)' https://p-staging2.fitradio.com/partners/catalog -H \"Authorization: $TOKEN\"\ncurl -s -A 'YourApp/1.0 (partner integration)' https://p-staging2.fitradio.com/partners/page/71 -H \"Authorization: $TOKEN\"\ncurl -s -A 'YourApp/1.0 (partner integration)' https://p-staging2.fitradio.com/partners/list/529 -H \"Authorization: $TOKEN\"\ncurl -s -A 'YourApp/1.0 (partner integration)' https://p-staging2.fitradio.com/partners/mix/9252 -H \"Authorization: $TOKEN\"\n\n# 3. Report a play (required for every track you play)\ncurl -s -A 'YourApp/1.0 (partner integration)' -X POST https://p-staging2.fitradio.com/partners/royalty-tracking \\\n -H \"Authorization: $TOKEN\" -H 'Content-Type: application/json' \\\n -d '{\n \"trackid\": 704991,\n \"playedat\": 1754380800000,\n \"playlength\": 213,\n \"sourcestream\": \"mix\",\n \"sourcedetail\": \"Burst of Energy Vol. 7\",\n \"os\": \"iOS 18.1\",\n \"device\": \"iPhone\",\n \"country\": \"US\",\n \"vendor\": 12,\n \"userid\": \"573042\",\n \"isrc\": \"USUM71703861\",\n \"endreason\": 1\n }'\n```\n\n# Data types and formats\n\nThese rules exist because getting them wrong silently corrupts royalty reporting. Please read them carefully.\n\n| Rule | Detail |\n|---|---|\n| **IDs are JSON integers** | Send `\"trackid\": 704991` — never `704991.0`, never `\"704991\"`. Serializers that add a trailing `.0` (e.g. Python floats, spreadsheet exports) break processing. |\n| **`playedat` is epoch milliseconds** | A 13-digit Unix timestamp, e.g. `1754380800000`. Sending *seconds* (10 digits) is not rejected but corrupts play-time reporting — always milliseconds. |\n| **`playlength` is seconds** | Integer number of seconds the track actually played, e.g. `213`. Required: a report without it is rejected with `400`. The legacy `playLength` casing is still accepted. |\n| **Mix/track durations are strings** | `length` and `time` fields are `HH:MM:SS` strings, e.g. `\"00:56:13\"`. |\n| **ISRC** | Every track in `GET /partners/mix/{mix_id}` includes its `isrc` (International Standard Recording Code). Echo the value back in royalty reports **exactly as received** — do not reformat, trim, or reconstruct it. |\n| **Country codes** | ISO 3166-1 alpha-2, uppercase, e.g. `US`, `GB`, `DE`. |\n\n# Country\n\nCatalog, 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.\n\nRequesting a page or list id that has no content returns `400` with `reason: \"no results for given type\"`.\n\n# Standby mode\n\nWhen 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:\n\n* Responses include the header `x-fitradio-served-by: standby` (or `live-bypass`). Absence of the header means normal live service.\n* `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`.\n* 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`.\n* 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).\n* `POST /partners/royalty-tracking` accepts and acknowledges reports; queue and re-send your reports after standby ends if you require delivery guarantees.\n\n# Errors\n\nTwo error envelopes are in use:\n\n* Most endpoints: `{ \"error\": true, \"reason\": \"\", \"mix\": null }` (the legacy `mix` field is always `null` and can be ignored).\n* `POST /partners/royalty-tracking`: `{ \"error\": true, \"message\": \"\" }`.\n* `401` responses from the authentication layer have a plain-text body (`Unauthorized`), not JSON.\n\n| Status | Meaning |\n|---|---|\n| `400` | Missing/invalid parameter, or no content for the given id |\n| `401` | Missing, malformed, expired, or standby-minted token; invalid session credentials |\n| `404` | Mix not found |\n| `500` | Internal error — retry with backoff, then contact FitRadio |\n| `503` | Standby failover error — retry with backoff |\n\n# Downloads\n\n* [Raw OpenAPI spec](./openapi.json)\n* [Postman collection](./fitradio-partner-api.postman_collection.json)\n\n\nContact Support:\n Name: FitRadio Partner Support", "type": "text/plain" } } }