canonical: https://jentic.com/apis/npr.org/npr-listening-service # NPR Listening Service Jentic publishes the only available OpenAPI specification for NPR Listening Service, keeping it validated and agent-ready. The NPR Listening Service delivers personalised audio recommendations to NPR One client apps. It exposes the main recommendation feed for a logged-in listener, channel listings, search-driven recommendations, organisation-scoped feeds, aggregation feeds, listening history, and a ratings endpoint that records listener feedback to shape future recommendations. All endpoints require an OAuth 2.0 access token issued by the NPR Authorization Service. ## For AI agents Fetch personalized NPR audio recommendations, search for episodes, list channels, and submit listener ratings to shape future recommendations. ## Scope Does not handle OAuth token issuance, listener profile management, or sponsorship - use for personalised NPR One audio recommendations, search, ratings, and history only. ## Capabilities - Retrieve a personalised list of audio recommendations for the logged-in listener - Submit listener ratings to record completion, skip, or share events that shape future recommendations - Search for audio and aggregations matching a query, returning ranked recommendation items - List the available NPR One listening channels for a listener - Fetch recommendations scoped to a specific NPR member organisation or category - Retrieve recent listener history including the latest promo audio heard ## Use cases ### Personalised Audio Stream for NPR One Apps An NPR One client app calls GET `/v2/recommendations` on launch to receive a queue of audio segments tailored to the listener - newscasts first, then stories, podcasts, and station promos blended by the recommendation engine. As each item plays, the app submits a rating with POST `/v2/ratings` so the next call returns a refined queue. Example prompt: Call GET `/v2/recommendations` with the listener's access token, then submit POST `/v2/ratings` with completion=true after each item plays to the end. ### Search Across NPR Audio Listeners often want to jump to a specific topic - election coverage, a favorite show, an interview they remember. GET `/v2/search/recommendations` returns a ranked list of matching audio and aggregation items, which client apps render as a search results page with playback hooks back into the recommendation queue. Example prompt: Call GET `/v2/search/recommendations` with q=climate policy and the listener's access token, then play the top-ranked item on the listener's device. ### Local Station Discovery via Organisations Listeners often want a feed scoped to their local NPR member station, optionally filtered by category. GET `/v2/organizations/{orgId}/recommendations` returns a feed for that station, and GET `/v2/organizations/{orgId}/categories/{category}/recommendations` narrows it to news, arts, or another category. This powers the local view inside NPR One client apps. Example prompt: Call GET `/v2/organizations/{orgId}/categories/news/recommendations` with the listener's home station orgId to render a local-news feed. ### Agent-Driven Voice Listening Session A voice agent on a smart speaker fetches the next NPR One recommendation, plays it, and reports the completion event back through Jentic. Because Jentic exposes both the recommendation fetch and the rating post as discrete operations, the agent can handle the full listening loop without bespoke integration code. Example prompt: Search Jentic for 'get the next npr audio recommendation', execute GET `/v2/recommendations`, play the first item, then call POST `/v2/ratings` with the rating event. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/v2/recommendations` | Get the listener's personalised recommendation queue | | POST | `/v2/ratings` | Submit a rating to shape future recommendations | | GET | `/v2/search/recommendations` | Search NPR audio and aggregations | | GET | `/v2/channels` | List the listener's available channels | | GET | `/v2/organizations/{orgId}/recommendations` | Get recommendations scoped to a specific organisation | | GET | `/v2/organizations/{orgId}/categories/{category}/recommendations` | Get recommendations for a category from a specific organisation | | GET | `/v2/aggregation/{aggId}/recommendations` | Get recommendations from a specific aggregation independent of the personalised queue | | GET | `/v2/history` | Get recent ratings the listener has submitted | ## Key resources - **Recommendations** — Personalised audio queues for the logged-in listener and for organisation-scoped or category-scoped feeds - **Ratings** — Submit listener feedback to shape future recommendations - **Search** — Search NPR One audio and aggregations - **Channels** — List the listener's available NPR One channels - **History** — Retrieve recent ratings and most recent promo audio heard ## Why Jentic - **Setup:** Wiring the NPR Listening Service by hand means carrying an OAuth 2.0 bearer token into every call to listening.api.npr.org and hand-mapping recommendations, search, ratings, and history yourself. Through Jentic you install once, import the NPR Listening Service from the API Directory, store the access token once, and your agent calls it. - **Permission scoping:** This service puts the organization and aggregation ids in the URL path (`/v2/organizations/{orgId}/recommendations`), so a rule can pin your agent to one organization's recommendations and nothing else. You choose the operations it may call, so writing ratings is not included unless you add it. - **Credential handling:** Your NPR OAuth 2.0 access 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 'get the next NPR audio recommendation' or 'search recommendations by keyword', and Jentic returns the matching Listening operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **NPR Authorization Service** — Issues the OAuth 2.0 tokens required on every Listening Service call. - **NPR Identity Service** — Holds the profile, follows, and favorite station that personalise the Listening feed. - **Spotify Web API** — Music and podcast streaming platform with its own recommendation and search APIs. - **YouTube Data API** — Video and audio content search and discovery on YouTube. ## FAQ ### Why is there no official OpenAPI spec for NPR Listening Service? NPR does not publish an OpenAPI specification for the Listening Service. Jentic generates and maintains this spec so that AI agents and developers can call NPR Listening Service 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 Listening Service use? Every endpoint requires an OAuth 2.0 bearer access token issued by the NPR Authorization Service. Jentic holds the listener's token in its encrypted vault and adds the Authorization header on each call, so agents never see the raw token. ### Can I get personalised audio recommendations with the NPR Listening Service? Yes. GET `/v2/recommendations` returns a personalised queue for the logged-in listener, and submitting feedback to POST `/v2/ratings` refines future calls. The same engine also powers organisation-scoped and category-scoped feeds via `/v2/organizations/{orgId}/recommendations.` ### How do I record a listener rating through Jentic? Search Jentic with 'submit npr rating', load POST `/v2/ratings`, and execute it with the rating event (completion, skip, share, or thumbs) along with the media id and the listener's access token. The next `/v2/recommendations` call reflects the new feedback. ### Does the NPR Listening Service support search? Yes. GET `/v2/search/recommendations` accepts a query string and returns a ranked list of audio and aggregation items, which is how NPR One client apps build their topic-search experience. ### Can I limit what my agent is allowed to do with the NPR Listening Service? Yes. Jentic One runs on your own infrastructure, so your rules decide which NPR Listening Service operations and credentials the agent can use. Because organisation and aggregation ids sit in the URL path, such as GET `/v2/organizations/{orgId}/recommendations`, you can pin the agent to a single station's feed and nothing else. You also choose which operations it may call, so writing feedback through POST `/v2/ratings` is excluded unless you grant it, and the OAuth 2.0 token stays with your instance rather than the agent.