canonical: https://jentic.com/apis/npr.org

# NPR APIs

NPR's developer platform powers the NPR One personalised public-radio experience through a set of connected services. Agents can run the full listener loop across these APIs: obtain OAuth 2.0 tokens, fetch a personalised audio recommendation queue, search NPR audio, submit ratings that refine future recommendations, read and update the listener's profile and follows, look up NPR member stations by location, and retrieve sponsor spots for licensed audio apps. Together they cover authentication, listening, identity, station discovery, and sponsorship for public-radio applications on phones, smart speakers, and connected cars.

## For AI agents

An agent can authenticate a listener with OAuth 2.0 (including device flow for smart speakers), fetch and rate personalised NPR audio recommendations, search episodes, read and update the listener's profile, follows, and favorite stations, look up member stations by location, and pull sponsor spots for licensed audio apps.

## Scope

Use for: Building NPR One public-radio experiences: OAuth 2.0 login, personalised audio recommendations and ratings, listener profile and follows, NPR member station lookup, and sponsor-spot insertion for licensed audio apps

Not supported:
- music streaming rights
- third-party podcast hosting
- general advertising inventory
- audio file playback
- non-NPR user identity

## APIs

| API | Category | Endpoints | Description |
| --- | --- | --- | --- |
| NPR One API | media | 10 | Build NPR One listening experiences end-to-end: authenticate, fetch personalised recommendations, search audio, rate playback, and manage stations and profile. |
| NPR Listening Service | media | 9 | Fetch personalized NPR audio recommendations, search for episodes, list channels, and submit listener ratings to shape future recommendations. |
| NPR Identity Service | identity-auth | 5 | Read and update the logged-in NPR One listener's profile, station preferences, and follow list, plus inherit listening data from temporary accounts. |
| NPR Authorization Service | identity-auth | 3 | Issue and revoke OAuth 2.0 access tokens for the NPR One platform, including device-flow login for smart speakers and connected cars. |
| NPR Sponsorship Service | media | 2 | Fetch NPR sponsorship audio spots and impression-tracking metadata for insertion between NPR audio segments. |
| NPR Station Finder Service | media | 2 | Look up NPR member station metadata by geography or station ID, including stream URLs and donation pages. |

## Which API to use

| Need | API | Why |
| --- | --- | --- |
| Obtain or revoke an access token, including device-flow login for smart speakers and cars | authorization | The Authorization Service is the OAuth 2.0 issuer; every other NPR service requires a token from it. |
| Fetch personalised audio recommendations, search episodes, and submit ratings | listening | The Listening Service is the standalone recommendation, search, ratings, and history surface. |
| The same listening capabilities plus identity, stations, and OAuth in one unified spec | npr-one | The NPR One API bundles Listening, Identity, Stations, and Authorization behind a single cross-service surface for full client apps. |
| Read or update the listener's profile, follows, and favorite station | identity | The Identity Service is the standalone profile, follows, and station-preference surface. |
| Look up NPR member stations by geography or station ID with stream and donation URLs | npr-station-finder-service | The Station Finder Service is the dedicated member-station lookup surface. |
| Fetch sponsor audio spots and impression-tracking metadata for licensed audio apps | sponsorship | The Sponsorship Service is the only surface that returns sponsor creative and tracking pixels for NPR-licensed playback. |

## Cross-API use cases

### Authenticate then start a personalised listening session

An agent obtains an access token through the device flow, then fetches the listener's recommendation queue and submits ratings as each item finishes, refining future recommendations.

Example prompt: Call POST /v2/device and poll POST /v2/token on the Authorization Service to obtain a token, then call GET /v2/recommendations on the Listening Service and POST /v2/ratings after each item plays.

### Set a home station and get local recommendations

An agent looks up the listener's local member station, saves it as their favorite in the profile, and then requests station-scoped recommendations so the feed reflects the new home station.

Example prompt: Call GET /v3/stations on the Station Finder with the listener's ZIP, PUT /v2/stations on the Identity Service to save the favorite, then GET /v2/organizations/{orgId}/recommendations on the Listening Service.

### Resolve a station and insert a sponsor spot

An agent building a licensed third-party audio app resolves the listener's local station, then fetches the next sponsor spot and its tracking pixels to play compliantly before NPR content.

Example prompt: Call GET /v3/stations on the Station Finder to identify the active station, then GET /v2/ads on the Sponsorship Service and fire the returned impression pixels at playback start.

### Onboard a guest listener into a signed-in profile

After a guest signs in, an agent issues an access token, copies the guest listening history into the permanent account, and confirms the profile so recommendations do not reset.

Example prompt: Obtain a token via POST /v2/token on the Authorization Service, call POST /v2/user/inherit on the Identity Service with the guest identifier, then GET /v2/user to confirm the profile.

## Why Jentic

- **Setup:** Wiring NPR's services by hand means carrying an OAuth 2.0 token across separate hosts for authorization, identity, listening, stations, and sponsorship, and hand-mapping each operation. With Jentic you install once, add the NPR APIs you need from the Jentic directory, store the credentials once, and your agent calls them.
- **Permission scoping:** You choose which NPR operations an agent may call, so read-only work such as fetching recommendations or looking up a station can be allowed while writes such as updating a profile, deleting an account, or revoking a token stay excluded unless you add them. Path-scoped services like the Station Finder and organisation-scoped recommendations let a rule pin the agent to a single station or organisation.
- **Credential handling:** Your NPR OAuth 2.0 tokens and client credentials are stored encrypted by your own Jentic One instance and injected into the Authorization header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search the Jentic directory by intent, such as issuing an NPR One token, fetching the next recommendation, or finding a local station, and Jentic returns the matching NPR operation with its input schema so the agent calls the right endpoint without browsing NPR's reference docs.

## Related vendors

- **Spotify** — General-purpose music and podcast streaming with its own recommendation and search APIs, for use cases beyond curated NPR public radio.
- **Listen Notes** — Podcast and audio search across many publishers when an agent needs broader discovery than NPR's member-station network.
- **Auth0** — General-purpose OAuth 2.0 and OIDC authorization server for building user identity in non-NPR applications.
- **Okta** — Enterprise identity and OAuth 2.0 platform for workforce or customer identity outside the NPR One ecosystem.

## FAQ

### What can an agent do across NPR's APIs?

An agent can run the full NPR One listener loop: authenticate a listener with OAuth 2.0, fetch and rate personalised audio recommendations, search NPR audio, read and update the listener's profile and follows, look up member stations by location, and retrieve sponsor spots for licensed audio apps. The services are designed to chain together, so an agent can move from login to a personalised, locally scoped listening session in a single flow.

### Do all of NPR's services share one authentication model?

Yes. Every service uses OAuth 2.0. The Authorization Service is the token issuer, and the tokens it produces are accepted by the Identity, Listening, and Sponsorship services. The Authorization Service itself is called with a registered client ID and secret rather than an existing access token.

### Which API should I use for a full NPR One client versus a single capability?

The NPR One API is a unified surface that bundles listening, identity, station search, and OAuth behind one spec, which suits a complete client app. If you only need one capability, use the standalone service: Listening for recommendations, Identity for profiles, Authorization for tokens, or the Station Finder for station lookup.

### Can NPR's APIs support smart speakers and connected cars?

Yes. The Authorization Service provides an OAuth 2.0 device flow built for limited-input devices such as smart speakers, set-top boxes, and car head units. The device displays a short user code, the listener approves it on their phone, and the device polls for an access token that then unlocks the Listening, Identity, and Station Finder services.

### Are the NPR APIs suitable for third-party audio apps outside NPR One?

Apps licensed to play NPR audio outside NPR One use the Station Finder to resolve a local station and the Sponsorship Service to fetch sponsor spots with impression-tracking pixels. Sponsorship access requires an NPR One Enterprise licensing agreement and adherence to NPR's sponsor-insertion compliance terms.

### Do these APIs handle general music or podcast streaming?

No. The APIs are scoped to NPR's curated public-radio content and the NPR One experience. They do not cover general music streaming rights or third-party podcast hosting; for broad music or creator content you would use a general streaming or discovery platform instead.

### How does an agent discover the right NPR operation for a task?

Once Jentic One is installed, an agent searches the Jentic directory by intent, such as finding a local NPR station or fetching the next recommendation, and Jentic returns the matching NPR operation with its input schema so the agent calls the correct endpoint without reading the reference docs.