Agent-Skills.md

Agent Skills: Podchaser API

Podchaser API for podcast data. Use when user mentions "Podchaser", "podcast",

UncategorizedID: vm0-ai/vm0-skills/podchaser

Repository

vm0-ai/vm0-skills
vm0-ai
508

Install this agent skill to your local

pnpm dlx add-skill https://github.com/vm0-ai/vm0-skills/tree/HEAD/podchaser

Skill Files

Browse the full folder contents for podchaser.

Download Skill

Loading file tree…

podchaser/SKILL.md

Skill Metadata

Name
podchaser
Description
Podchaser API for podcast data. Use when user mentions "Podchaser", "podcast",

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

The PODCHASER_TOKEN environment variable is automatically injected by the connector.

How to Use

1. 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:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -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:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -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:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -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:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -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:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -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:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -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:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -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:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -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:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -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:

curl -s -X POST "https://api.podchaser.com/graphql/cost" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

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

  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