Podchaser

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

1. Create an account at https://www.podchaser.com/
2. Go to Account Settings > API Settings to get your Client ID and Secret
3. 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:

Write to /tmp/podchaser_request.json:

{
  "query": "mutation { requestAccessToken(input: { grant_type: CLIENT_CREDENTIALS, client_id: \"<your-client-id>\", client_secret: \"<your-client-secret>\" }) { access_token token_type expires_in } }"
}

Replace <your-client-id> and <your-client-secret> with your actual credentials from the Prerequisites section.

Then run:

bash -c 'curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" -d @/tmp/podchaser_request.json' | jq -r '.data.requestAccessToken.access_token' > /tmp/podchaser_token.txt

Store the token for use in subsequent requests.

Verify the token was saved:

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

2. Search Podcasts

Search for podcasts by keyword:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(searchTerm: \"technology\", first: 5) { paginatorInfo { count } data { id title description author { name } } } }"
}

Then run:

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 @/tmp/podchaser_request.json'

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.

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { id title description url imageUrl language ratingAverage ratingCount author { name } categories { title } } }"
}

Then run:

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 @/tmp/podchaser_request.json'

4. Search Episodes

Search for episodes across all podcasts:

Write to /tmp/podchaser_request.json:

{
  "query": "{ episodes(searchTerm: \"AI\", first: 5) { paginatorInfo { count } data { id title description airDate length podcast { title } } } }"
}

Then run:

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 @/tmp/podchaser_request.json'

5. Get Podcast Episodes

Get episodes for a specific podcast:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { id title episodes(first: 10) { data { id title description airDate length } } } }"
}

Then run:

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 @/tmp/podchaser_request.json'

6. Get Episode Details

Get detailed information about a specific episode:

Write to /tmp/podchaser_request.json:

{
  "query": "{ episode(identifier: { id: \"789012\", type: PODCHASER }) { id title description airDate length url imageUrl podcast { id title } } }"
}

Then run:

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 @/tmp/podchaser_request.json'

7. Get Podcast Categories

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

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { title categories { title slug } } }"
}

Then run:

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 @/tmp/podchaser_request.json'

8. Filter Podcasts by Category

Get podcasts in a specific category:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(filters: { categories: [\"technology\"] }, first: 10) { data { id title description ratingAverage } } }"
}

Then run:

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 @/tmp/podchaser_request.json'

9. Get Chart Rankings

Get Apple Podcasts chart data:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(filters: { hasAppleChartRank: true }, sort: { sortBy: APPLE_CHART_RANK, direction: ASC }, first: 10) { data { id title appleChartRank } } }"
}

Then run:

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 @/tmp/podchaser_request.json'

10. Get Creator/Host Information

Search for podcast creators:

Write to /tmp/podchaser_request.json:

{
  "query": "{ creators(searchTerm: \"Joe Rogan\", first: 5) { data { pcid name bio credits { data { podcast { title } } } } } }"
}

Then run:

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 @/tmp/podchaser_request.json'

11. Preview Query Cost

Check how many points a query will cost before executing:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(searchTerm: \"tech\", first: 10) { data { id title description episodes(first: 5) { data { id title } } } } }"
}

Then run:

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 @/tmp/podchaser_request.json'

GraphQL Schema Reference

Main Queries

Identifier Types

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

Podcast Fields

Episode Fields

Creator Fields

Filter Options

Sort Options

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

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