canonical: https://jentic.com/apis/npr.org/npr-one # NPR One API Jentic publishes the only available OpenAPI specification for NPR One API, keeping it validated and agent-ready. The NPR One API is a unified surface across the four NPR One sub-services - Listening, Identity, Stations, and Authorization - that together power the NPR One personalised public-radio experience. It exposes recommendation queues, ratings, search, listening history, listener profile read and update, station search, and OAuth 2.0 authorize and token endpoints. Authentication is OAuth 2.0 bearer for user-facing endpoints, with the authorize and token endpoints handled directly under this API. ## For AI agents Build NPR One listening experiences end-to-end: authenticate, fetch personalised recommendations, search audio, rate playback, and manage stations and profile. ## Scope Does not handle music streaming rights, third-party podcast hosting, or sponsorship inventory - use for the NPR One personalised public-radio experience only. ## Capabilities - Get a personalised audio recommendation queue for the logged-in NPR One listener - Submit a rating or interaction event to refine future recommendations - Search NPR audio content for matching episodes and aggregations - Read and update the authenticated listener's profile - Search NPR member stations by call sign or location to set as the listener's home station - Run OAuth 2.0 authorize and token exchanges to obtain a bearer token for the platform - Retrieve recent listening history and the listener's available channels ## Use cases ### Full NPR One Client App Backend An NPR One client on iOS, Android, or a smart speaker uses this single unified API to handle authentication, the personalised recommendation queue, ratings, and station search. Building against one cross-service spec is significantly simpler than wiring each NPR sub-service separately, which is the canonical reason apps consume the NPR One API rather than the underlying Listening, Identity, Stations, and Authorization services individually. Example prompt: Authenticate with POST `/v2/token`, call GET `/v2/recommendations` to fill the play queue, then submit POST `/v2/ratings` as each item finishes. ### Personalised Search and Discovery Listeners often hunt for a specific topic, host, or show. GET `/v2/search/recommendations` returns a ranked list of audio and aggregation items matching a query, while GET `/v2/stations` supports finding a local member station to anchor the listener's recommendation profile. Example prompt: Call GET `/v2/search/recommendations` with q=federal budget, then on a station-switch intent call GET `/v2/stations` with the listener's ZIP. ### Profile and Station Management GET `/v2/user` reads the listener's profile and PUT `/v2/user` updates display name and preferences. Combined with GET `/v2/stations` for station search, this is enough to power a settings screen end-to-end inside an NPR One client app. Example prompt: Read the profile with GET `/v2/user`, then update display name and notification settings via PUT `/v2/user.` ### Agent-Driven Smart Speaker Listening A voice assistant agent handles a 'play NPR' intent by exchanging an OAuth code for a token, fetching the next recommendation, playing it, and submitting a completion rating. Because Jentic exposes each NPR One operation discretely, the agent does not need to chain low-level OAuth and recommendation logic by hand. Example prompt: Search Jentic for 'play the next npr one episode', execute POST `/v2/token` then GET `/v2/recommendations`, play the first item, then POST `/v2/ratings` on completion. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/v2/recommendations` | Get personalised audio recommendations | | POST | `/v2/ratings` | Send a rating or interaction event | | GET | `/v2/channels` | Get available listening channels | | GET | `/v2/history` | Get listening history | | GET | `/v2/search/recommendations` | Search for audio content | | GET | `/v2/user` | Get the authenticated user's profile | | PUT | `/v2/user` | Update the user's profile | | GET | `/v2/stations` | Search for NPR member stations | ## Key resources - **Listening** — Personalised recommendation queue, ratings, search, history, and channel listings - **Identity** — Read and update the authenticated listener's profile - **Stations** — Search NPR member stations to set as the listener's home station - **Authorization** — OAuth 2.0 authorize and token exchange for bearer tokens ## Why Jentic - **Setup:** Wiring the NPR One API by hand means carrying an OAuth 2.0 bearer token across three separate hosts, listening.api.npr.org, identity.api.npr.org, and station.api.npr.org, and mapping recommendations, profile, and station operations yourself. Through Jentic you install once, import the NPR One API from the API Directory, store the bearer token once, and your agent calls it. - **Permission scoping:** The listener profile and playback target here is the token holder rather than a URL path resource, so scope the agent to the operations it needs, such as reading recommendations or listing stations. You choose the operations it may call, so updating the user profile is not included unless you add it. - **Credential handling:** Your NPR One bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'play the next NPR One episode' or 'find an NPR station', and Jentic returns the matching NPR One operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **NPR Authorization Service** — Standalone OAuth 2.0 server backing NPR One; useful when you only need auth. - **NPR Listening Service** — Standalone listening sub-service if you only need recommendations and ratings. - **Spotify Web API** — General-purpose music and podcast streaming with its own recommendations. - **YouTube Data API** — Broad video and audio content discovery beyond public radio. ## FAQ ### Why is there no official OpenAPI spec for NPR One API? NPR publishes developer documentation but not a full OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call NPR One API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the NPR One API use? User-facing endpoints accept an OAuth 2.0 bearer access token, and the authorize and token endpoints under /v2 handle the OAuth flow itself. Jentic stores the bearer token in its encrypted vault and injects it into the Authorization header on each call. ### Can I get personalised audio recommendations with the NPR One API? Yes. GET `/v2/recommendations` returns a personalised queue tied to the bearer token's listener, and POST `/v2/ratings` feeds completion, skip, and share events back into the recommendation engine to shape future calls. ### How do I find an NPR member station with the NPR One API through Jentic? Search Jentic with 'find npr member station', load GET `/v2/stations`, and execute it with a ZIP code or call sign. The response lists matching stations, which you can then set as the listener's home station via the profile update endpoint. ### Does the NPR One API include OAuth 2.0 endpoints? Yes. GET `/v2/authorize` starts the OAuth 2.0 authorization flow and POST `/v2/token` exchanges an authorization code for a bearer access token. These mirror the standalone NPR Authorization Service and let you complete the full sign-in loop without leaving the unified NPR One API. ### Can I limit what my agent is allowed to do with the NPR One API? Yes. Because you run Jentic One yourself, your own rules decide which NPR One operations the agent may call and which bearer token it may use. Since access here targets the token holder rather than a path resource, you can scope the agent to just the operations it needs, such as GET `/v2/recommendations` to fill the queue and GET `/v2/stations` to find a member station, while leaving out others. Write operations like PUT `/v2/user` to update the listener profile are not available to the agent unless you explicitly add them.