Agent-Skills.md

Agent Skills: podchaser

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",

Troubleshooting

If requests fail, run zero doctor check-connector --env-name PODCHASER_TOKEN or zero doctor check-connector --url https://api.podchaser.com/graphql --method POST

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