canonical: https://jentic.com/apis/hubhopper.com/hubhopper

# Hubhopper Partner Integration API(s) - Production

The Hubhopper Partner Integration API gives partner platforms read access to the Hubhopper podcast catalogue, exposing categories, podcasts, episodes, and supported languages. Partners can list and browse categories, list podcasts within a category, fetch the metadata for a specific podcast, and pull the episode list for that podcast. Authentication uses an x-api-key header alongside an hhPartnerId header that scopes the response to the partner's allowed catalogue. The API is read-only and is intended for podcast directory and discovery integrations.

## For AI agents

Browse the Hubhopper podcast catalogue by category, retrieve podcast metadata, and list episodes for use in directory or discovery experiences.

## Scope

Does not upload podcasts, manage subscriptions, or stream audio - use only to read partner-licensed Hubhopper catalogue data such as categories, podcasts, and episodes.

## Capabilities

- List the podcast categories available to a Hubhopper partner
- Retrieve a single category by id with its display metadata
- List the podcasts that belong to a specific category
- Browse the full partner-allowed podcast catalogue with pagination
- Fetch the metadata for a single podcast by podcast id
- Retrieve the episode list for a podcast
- Look up the supported languages for filtering podcast results

## Use cases

### Power a partner podcast directory page

A partner site that surfaces podcasts to its users can render category pages, podcast detail pages, and episode lists from the Hubhopper API. GET /categories drives the navigation, GET `/categories/{categoryId}/podcasts` populates each category page, and GET `/podcasts/{podcastId}/episodes` loads the episode list for a podcast detail page. The hhPartnerId header scopes results to the partner's licensed catalogue.

Example prompt: Call GET /categories to render navigation, then GET `/categories/{categoryId}/podcasts` to populate the page for the selected category

### Fetch episode metadata for a podcast player

An audio player surfaces the episode list and metadata for a podcast the user clicked on. GET `/podcasts/{podcastId}` returns the podcast's title, description, and image, and GET `/podcasts/{podcastId}/episodes` returns the episode list with publish dates and audio references. Together they fully populate a player view without scraping.

Example prompt: Call GET `/podcasts/{podcastId}` for the header metadata and GET `/podcasts/{podcastId}/episodes` for the playable episode list

### Localise the catalogue by language

Apps targeting specific Indian-language audiences can use GET `/util/languages` to list supported language codes, then filter podcast browsing accordingly. The languages endpoint is the source of truth for valid locale values that appear elsewhere in the catalogue.

Example prompt: Call GET `/util/languages` and store the supported language codes for use as filters in the partner UI

### Agent integration via Jentic

A content-recommendation agent can fetch fresh podcast metadata for a user query without managing API keys directly. The agent searches Jentic for the catalogue operation, loads the schema, and executes the call. The Hubhopper x-api-key and hhPartnerId stay encrypted in your Jentic One instance.

Example prompt: Search Jentic for 'list hubhopper podcasts in a category', load the schema for GET `/categories/{categoryId}/podcasts`, and execute with the chosen categoryId

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/categories` | List all podcast categories |
| GET | `/categories/{categoryId}` | Retrieve a single category |
| GET | `/categories/{categoryId}/podcasts` | List podcasts in a category |
| GET | `/podcasts` | List the partner-allowed podcast catalogue |
| GET | `/podcasts/{podcastId}` | Retrieve podcast metadata |
| GET | `/podcasts/{podcastId}/episodes` | List episodes for a podcast |
| GET | `/util/languages` | List supported languages |

## Key resources

- **Category** — List and read podcast categories
- **Podcast** — List podcasts, read podcast metadata, and list episodes
- **Util** — Read supported languages used elsewhere in the catalogue

## Why Jentic

- **Setup:** Wiring the Hubhopper Partner Integration API by hand means sending both the x-api-key and hhPartnerId headers on every call to apis.hubhopper.com/partner and paging the catalogue records yourself. Through Jentic you install once, import the Hubhopper Partner Integration API from the API Directory, store the partner key once, and your agent calls it.
- **Permission scoping:** Hubhopper puts the category and podcast ids in the URL path (`/categories/{categoryId}`, `/podcasts/{podcastId}`), so a rule can pin your agent to reading one category or podcast and nothing else. Every operation here is read-only, so the agent has no write or delete calls to grant.
- **Credential handling:** Your Hubhopper x-api-key and hhPartnerId are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list podcasts in a hubhopper category', and Jentic returns GET `/categories/{categoryId}/podcasts` with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Listen Notes API** — Listen Notes provides a global podcast search and metadata API rather than a partner-licensed catalogue
- **Spotify Web API** — Spotify exposes podcast and episode metadata for users with a Spotify account
- **SoundCloud API** — SoundCloud exposes audio track and playlist metadata for music and spoken-word content

## FAQ

### What authentication does the Hubhopper Partner API use?

The spec defines two apiKey schemes that are used together: x-api-key in the request header for the partner API key, and hhPartnerId in the request header to identify the partner account. Both must be present on every call. Through Jentic these credentials are stored encrypted in the vault.

### Can I list podcasts within a specific category with the Hubhopper API?

Yes. GET `/categories/{categoryId}/podcasts` returns the podcasts that belong to a given category, scoped to the partner catalogue identified by the hhPartnerId header. Use GET /categories first to discover valid category ids.

### What are the rate limits for the Hubhopper Partner API?

The spec does not publish an explicit rate limit. Hubhopper sets per-partner quotas at provisioning time, so contact your Hubhopper partner manager to confirm the cap on x-api-key calls per minute for your account.

### How do I list podcasts through Jentic?

Search Jentic for 'list podcasts in a hubhopper category', load the schema for GET `/categories/{categoryId}/podcasts`, and execute with the chosen categoryId. Jentic returns the JSON list of podcasts with their metadata.

### Is the Hubhopper Partner API free?

The Partner Integration API is gated by a partner agreement with Hubhopper. Pricing is negotiated per partner and is not exposed in the spec - request access by contacting Hubhopper directly.

### Can I create or upload podcasts with this API?

No. All seven endpoints are GET requests. The Partner Integration API is read-only and is intended for distribution and discovery rather than catalogue management.

### Can I limit what my agent is allowed to do with the Hubhopper Partner API?

Yes. Because you run Jentic One yourself, your own rules decide which Hubhopper operations and credentials the agent may use. Every endpoint here is read-only, so there are no write or delete calls to grant, and since the category and podcast ids sit in the URL path (`/categories/{categoryId}`, `/podcasts/{podcastId}`), a rule can pin the agent to reading a single category or podcast and nothing else. Your x-api-key and hhPartnerId stay with your instance and are injected only when an allowed call runs.