# Podseeker Agent

Podseeker is a podcast data API. Search 700,000+ curated, active podcasts and get verified contacts, host information, booking difficulty, and guest caliber data. Built for automation.

For full response schemas and example JSON, see the API docs: https://app.podseeker.co/api/docs

## Authentication

All requests require a Bearer token in the Authorization header:
```
Authorization: Bearer $PODSEEKER_API_KEY
```

If the user doesn't have an API key, they can sign up at https://app.podseeker.co/auth/registration and select the API plan.

## Endpoints

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

### 1. Search Podcasts
```
GET /api/v1/podcasts/search
```

Parameters:
- query (string) -search term like "health", "entrepreneurship", "AI"
- active (boolean) -true to filter active podcasts only
- has_guest (boolean) -true to filter podcasts accepting guests
- has_email (boolean) -true to filter 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
- booking_difficulty (string) -very_low, low, medium, high, very_high
- gender_skew (string) -male, female, neutral
- listener (string, repeatable) -filter by listener range: <100, 100-1k, 1k-10k, 10k-100k, 100k-1m, >1m
- sort (string) -listeners_desc, listeners_asc, latest_episode_desc, latest_episode_asc, youtube_subscribers_desc, instagram_followers_desc
- page (integer) -0-99, 50 results per page

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

### 2. Get Podcast Details
```
GET /api/v1/podcasts/:id
```

Returns full podcast profile including verified contacts, website, RSS feed, host bios, guest caliber requirements, and social stats.

Example:
```bash
curl -H "Authorization: Bearer $PODSEEKER_API_KEY" \
  "https://app.podseeker.co/api/v1/podcasts/625373"
```

## Workflow

1. **Ask about their topic/niche** if not already clear from context.
2. **Search with filters based on user intent.** No default filters -start broad, then narrow. Apply filters when context calls for them:
   - `has_email=true` when the user needs contact info for outreach
   - `has_guest=true` when the user wants to pitch themselves or others as guests
   - `active=true` only when they want currently-publishing shows
   - `topic`, `location`, `booking_difficulty`, `listener` when specified
3. **Present the shortlist and stop.** Show title, listeners, booking difficulty. Do NOT call /podcasts/:id yet -wait for the user to confirm which podcasts to pursue. Each API call costs 1 credit.
4. **Get details only for confirmed podcasts** -fetch host names, emails, and guest caliber info.
5. **Hand off contacts and host info to the user.** Pitch drafting and sending is outside this API's scope.

## Key Concepts

- **Booking difficulty**: low = easier to book, high = competitive/selective.
- **Guest caliber**: Shows what kind of guests the podcast typically books. Use this to assess fit.
- **Estimated listeners**: This is an estimate per episode, not exact. Use it for relative sizing, not absolute numbers.
- **Credits**: Each API call costs 1 credit. 2,000/month included. Check X-Credits-Remaining in response headers.

## Rate Limits

60 requests per minute. If you get a 429, wait 60 seconds before retrying.

## Errors

- 401: Invalid API key
- 402: Credits exhausted
- 404: Podcast not found
- 429: Rate limited