# Podseeker API
# The podcast data API. Built for automation.
# https://app.podseeker.co

## What Podseeker Does
Podseeker provides programmatic access to a curated database of 700,000+ podcasts with verified contact emails, booking difficulty ratings, host information, and audience data. The database focuses on active, high-quality podcasts -dormant and low-quality shows are filtered out so you only work with podcasts worth pitching. Built for AI agents, scripts, and automated outreach workflows.

## API Docs
https://app.podseeker.co/api/docs

## API Base URL
https://app.podseeker.co/api/v1

## Authentication
All requests require a Bearer token in the Authorization header:
Authorization: Bearer ps_your_api_key_here

Get an API key at https://app.podseeker.co/auth/registration (select the API plan).

## Endpoints

### Search Podcasts
GET /api/v1/podcasts/search

Find podcasts matching a query with filters. Returns 50 results per page, up to 5,000 total.

Parameters:
- query (string) -search term, e.g. "health", "entrepreneurship", "AI"
- active (boolean) -true/yes/1 to filter for active podcasts
- has_guest (boolean) -true/yes/1 to filter for podcasts that accept guests
- has_email (boolean) -true/yes/1 to filter for podcasts with verified contact emails
- topic (string, repeatable) -filter by topic, e.g. topic=leadership&topic=coaching
- location (string, repeatable) -usa, uk, au, ca, ie, sg, nz, za
- listener (string, repeatable) -filter by listener range: <100, 100-1k, 1k-10k, 10k-100k, 100k-1m, >1m
- booking_difficulty (string, repeatable) -very_low, low, medium, high, very_high
- gender_skew (string) -male, female, neutral
- sort (string) -listeners_desc, listeners_asc, latest_episode_desc, latest_episode_asc, youtube_subscribers_desc, instagram_followers_desc
- page (integer) -0-99

Example:
curl -H "Authorization: Bearer ps_your_key" "https://app.podseeker.co/api/v1/podcasts/search?query=entrepreneurship&active=true&has_guest=true&has_email=true"

Response fields per podcast:
- id, title, publisher, description
- topics (array of up to 5 keywords)
- location, estimated_listeners (rounded estimate per episode, not exact), episode_count, episode_frequency
- latest_episode_date, rating
- has_guests (boolean), has_email (boolean)
- booking_difficulty (very_low/low/medium/high/very_high)
- gender_skew (male/female/neutral)

### Get Podcast Details
GET /api/v1/podcasts/:id

Get full details for a single podcast including contacts, hosts, and social stats.

Example:
curl -H "Authorization: Bearer ps_your_key" "https://app.podseeker.co/api/v1/podcasts/625373"

Response includes everything from search plus:
- contacts.primary_email -verified email address
- contacts.all_emails -all known email addresses
- contacts.has_contact_form -whether the podcast website has a contact form
- website_url -official podcast website
- rss_url -RSS feed URL
- pitching_description -AI-generated summary of what the podcast covers and what guests they look for
- hosts -array of host objects with full_name, role, professional_bio
- guest_caliber -prominence_level, booking_difficulty, typical_credentials, typical_achievements
- recent_guests -array of recent guest names
- social.youtube_subscribers, social.instagram_followers

## Pricing
$99/month -2,000 credits included. Pay-as-you-go overage at $0.05/credit.
1 credit = 1 API call (any endpoint).

## Usage Headers
Every response includes usage headers:
- X-Credits-Used
- X-Credits-Included
- X-Credits-Remaining
- X-Overage-Credits
- X-Overage-Charge

## Rate Limits
60 requests per minute. 429 response with Retry-After header when exceeded.

## Errors
- 401: Invalid or missing API key
- 402: Credits exhausted
- 404: Podcast not found
- 429: Rate limited (wait 60 seconds)

## Typical Agent Workflow
1. Search for podcasts matching your client's niche: GET /podcasts/search?query=leadership&has_email=true&active=true
2. Present the shortlist to the user -show title, listeners, booking difficulty. Do NOT fetch details yet.
3. Get full details only for confirmed podcasts: GET /podcasts/:id (each call costs 1 credit)
4. Use contacts.primary_email and hosts information to craft personalized pitches

## Support
support@podseeker.co