Podchaser API

Access comprehensive podcast data including shows, episodes, creators, networks, charts, and sponsorship information via GraphQL.

Official docs: https://api-docs.podchaser.com/docs/overview

When to Use

Use this skill when you need to:

Search and discover podcasts by topic, category, or keywords
Get detailed podcast and episode metadata
Access Apple Podcasts and Spotify chart rankings
Find sponsorship and advertising data
Retrieve episode transcripts
Look up podcast creators and networks

Prerequisites

Create an account at https://www.podchaser.com/
Go to Account Settings > API Settings to get your Client ID and Secret
Use Development credentials during integration (Production works identically)

Set environment variables:

export PODCHASER_CLIENT_ID="your-client-id"
export PODCHASER_CLIENT_SECRET="your-client-secret"

Important: Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly. Wrap the command containing $VAR in bash -c '...', keep jq outside.

How to Use

1. Get Access Token

Request an access token (valid for 1 year) and save to a temp file:

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" -d "{\"query\": \"mutation { requestAccessToken(input: { grant_type: CLIENT_CREDENTIALS, client_id: \\\"$PODCHASER_CLIENT_ID\\\", client_secret: \\\"$PODCHASER_CLIENT_SECRET\\\" }) { access_token token_type expires_in } }\"}"' | jq -r '.data.requestAccessToken.access_token' > /tmp/podchaser_token.txt

Verify the token was saved:

cat /tmp/podchaser_token.txt | head -c 50

2. Search Podcasts

Search for podcasts by keyword:

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $(cat /tmp/podchaser_token.txt)" -d '"'"'{"query": "{ podcasts(searchTerm: \"technology\", first: 5) { paginatorInfo { count } data { id title description author { name } } } }"}'"'"'' | jq .

3. Get Podcast Details

Get detailed information about a specific podcast by ID:

Note: The type field is required in the identifier. Use PODCHASER for Podchaser IDs, APPLE_PODCASTS for Apple IDs, or SPOTIFY for Spotify IDs.

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $(cat /tmp/podchaser_token.txt)" -d '"'"'{"query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { id title description url imageUrl language ratingAverage ratingCount author { name } categories { title } } }"}'"'"'' | jq .

4. Search Episodes

Search for episodes across all podcasts:

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $(cat /tmp/podchaser_token.txt)" -d '"'"'{"query": "{ episodes(searchTerm: \"AI\", first: 5) { paginatorInfo { count } data { id title description airDate length podcast { title } } } }"}'"'"'' | jq .

5. Get Podcast Episodes

Get episodes for a specific podcast:

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $(cat /tmp/podchaser_token.txt)" -d '"'"'{"query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { id title episodes(first: 10) { data { id title description airDate length } } } }"}'"'"'' | jq .

6. Get Episode Details

Get detailed information about a specific episode:

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $(cat /tmp/podchaser_token.txt)" -d '"'"'{"query": "{ episode(identifier: { id: \"789012\", type: PODCHASER }) { id title description airDate length url imageUrl podcast { id title } } }"}'"'"'' | jq .

7. Get Podcast Categories

Categories are available as a field on podcast objects. Get categories for a specific podcast:

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $(cat /tmp/podchaser_token.txt)" -d '"'"'{"query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { title categories { title slug } } }"}'"'"'' | jq .

8. Filter Podcasts by Category

Get podcasts in a specific category:

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $(cat /tmp/podchaser_token.txt)" -d '"'"'{"query": "{ podcasts(filters: { categories: [\"technology\"] }, first: 10) { data { id title description ratingAverage } } }"}'"'"'' | jq .

9. Get Chart Rankings

Get Apple Podcasts chart data:

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $(cat /tmp/podchaser_token.txt)" -d '"'"'{"query": "{ podcasts(filters: { hasAppleChartRank: true }, sort: { sortBy: APPLE_CHART_RANK, direction: ASC }, first: 10) { data { id title appleChartRank } } }"}'"'"'' | jq .

10. Get Creator/Host Information

Search for podcast creators:

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $(cat /tmp/podchaser_token.txt)" -d '"'"'{"query": "{ creators(searchTerm: \"Joe Rogan\", first: 5) { data { pcid name bio credits { data { podcast { title } } } } } }"}'"'"'' | jq .

11. Preview Query Cost

Check how many points a query will cost before executing:

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql/cost" --header "Content-Type: application/json" --header "Authorization: Bearer $(cat /tmp/podchaser_token.txt)" -d '"'"'{"query": "{ podcasts(searchTerm: \"tech\", first: 10) { data { id title description episodes(first: 5) { data { id title } } } } }"}'"'"'' | jq .

GraphQL Schema Reference

Main Queries

Query	Description
`podcast(identifier: {id: "...", type: PODCHASER})`	Get single podcast by ID
`podcasts(searchTerm: "...", first: N)`	Search podcasts
`episode(identifier: {id: "...", type: PODCHASER})`	Get single episode by ID
`episodes(searchTerm: "...", first: N)`	Search episodes
`creators(searchTerm: "...", first: N)`	Search creators/hosts
`networks(searchTerm: "...", first: N)`	Search podcast networks
`chartCategories(platform: APPLE_PODCASTS)`	List chart categories (requires paid plan)

Identifier Types

The type field is required when using identifier to fetch a podcast or episode:

Type	Description
`PODCHASER`	Podchaser internal ID
`APPLE_PODCASTS`	Apple Podcasts ID
`SPOTIFY`	Spotify ID

Podcast Fields

Field	Type	Description
`id`	ID	Unique identifier
`title`	String	Podcast title
`description`	String	Podcast description
`url`	String	Podcast website URL
`imageUrl`	String	Cover art URL
`language`	String	Primary language
`ratingAverage`	Float	Average user rating
`ratingCount`	Int	Number of ratings
`author`	Creator	Podcast author/creator
`categories`	[Category]	Associated categories
`episodes(first: N)`	EpisodeList	Podcast episodes (paginated)

Episode Fields

Field	Type	Description
`id`	ID	Unique identifier
`title`	String	Episode title
`description`	String	Episode description
`airDate`	Date	Publication date
`length`	Int	Duration in seconds
`url`	String	Episode URL
`imageUrl`	String	Episode artwork URL
`podcast`	Podcast	Parent podcast

Creator Fields

Field	Type	Description
`pcid`	String	Unique identifier
`name`	String	Creator name
`bio`	String	Biography
`imageUrl`	String	Profile image URL
`credits`	CreditList	Podcast appearances

Filter Options

Filter	Values
`categories`	Category slugs
`language`	ISO language codes
`hasAppleChartRank`	Boolean
`hasSpotifyChartRank`	Boolean

Sort Options

sortBy	Description
`RELEVANCE`	Search relevance
`POPULARITY`	Overall popularity
`RATING`	User rating
`APPLE_CHART_RANK`	Apple ranking
`SPOTIFY_CHART_RANK`	Spotify ranking
`LATEST_EPISODE`	Most recent episode

Rate Limits

Request Limit: 50 requests per 10 seconds
Points System: Query cost based on fields returned
Response Headers:
- X-Podchaser-Points-Remaining: Available points
- X-Podchaser-Query-Cost: Points consumed

Example costs:

Basic podcast metadata: ~9 points
Search 10 podcasts with details: ~100 points

Guidelines

Store Access Token: Tokens last 1 year, avoid requesting new tokens for each query
Preview Costs: Use /graphql/cost endpoint to estimate query cost before execution
Use Limited Scope: For client-side apps, request tokens with limited_scope: true (1 hour expiry)
Optimize Queries: Request only needed fields to minimize points consumption
Handle Rate Limits: Check Retry-After header on 429 responses
Security: Never expose regular access tokens in client-side code

podchaser