# Pod Engine API Reference

> Optimized for LLM consumption. Drop the URL or contents into your AI assistant for accurate API guidance.
> Source: https://www.podengine.ai/api-docs/llms.txt
> Auto-generated from the source-of-truth endpoint registry — kept in sync with the live API.

## Overview

Pod Engine is a podcast intelligence platform with access to 4M+ podcasts. The API enables:
- Searching podcasts and episodes by title, description, topic, or transcript content
- Retrieving detailed podcast/episode metadata including contact information
- Accessing full episode transcripts (when available)
- Tracking chart rankings across countries and categories
- Managing projects and organizing podcast research
- AI-powered guest profile generation, relevancy scoring, and outreach drafting

## Quick Start

1. Sign up at https://www.podengine.ai/get-started
2. Get your API key from your dashboard
3. Add to requests: `Authorization: Bearer YOUR_API_KEY`

**Base URL:** `http://localhost:4000`
**Interactive docs:** https://www.podengine.ai/api-docs
**OpenAPI 3.1 spec:** https://www.podengine.ai/api-docs/openapi.json
**Full reference (with inlined JSON schemas):** https://www.podengine.ai/api-docs/llms-full.txt
**Support:** support@podengine.ai

## Authentication

Endpoints labeled `(PUBLIC)` need no authentication. All other endpoints require a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

---

## Endpoints

### Agent

#### POST /api/v1/agent/alternative-spellings
**Alternative Spellings**

Generate phonetically plausible alternate spellings for a name or business. Useful for searching against auto-generated podcast transcripts where names are frequently misspelled.

```bash
curl -X POST "http://localhost:4000/api/v1/agent/alternative-spellings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "value": "Joe Tannorella"
}'
```

---

#### POST /api/v1/agent/project/relevancy
**Project Podcast Relevancy**

Analyze the relevancy of a podcast to a project using AI

```bash
curl -X POST "http://localhost:4000/api/v1/agent/project/relevancy" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "projectId": "example-project-id",
  "podcastId": "example-podcast-id",
  "forceRegenerate": false
}'
```

---

### Alerts

#### GET /api/v1/alerts/history
**Alert Match History**

Get the paginated history of alert matches for the team, optionally scoped to a single alert config.

```bash
curl -X GET "http://localhost:4000/api/v1/alerts/history" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### POST /api/v1/alerts/alert-config
**Create Alert Config**

Create a new alert configuration to monitor podcasts for mentions of a person, company, or custom keyword.

```bash
curl -X POST "http://localhost:4000/api/v1/alerts/alert-config" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "alertName": "Example Alert",
  "alertType": "person",
  "value": "Jason Calacanis"
}'
```

---

#### DELETE /api/v1/alerts/alert-config/:alertConfigId
**Delete Alert Config**

Soft-delete an alert configuration.

```bash
curl -X DELETE "http://localhost:4000/api/v1/alerts/alert-config/:alertConfigId" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/alerts/alert-config/:alertConfigId
**Get Alert Config**

Get a single alert configuration by ID.

```bash
curl -X GET "http://localhost:4000/api/v1/alerts/alert-config/:alertConfigId" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/alerts/alert-configs
**List Alert Configs**

Get all of the team's alert configurations.

```bash
curl -X GET "http://localhost:4000/api/v1/alerts/alert-configs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### PATCH /api/v1/alerts/alert-config/:alertConfigId
**Update Alert Config**

Update an existing alert configuration (name, settings, email frequency, or enabled state).

```bash
curl -X PATCH "http://localhost:4000/api/v1/alerts/alert-config/:alertConfigId" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

### Autocomplete

#### GET /api/v1/autocomplete/podcasts (PUBLIC)
**Podcasts**

Get autocomplete suggestions for podcasts

```bash
curl -X GET "http://localhost:4000/api/v1/autocomplete/podcasts?query=this" \
  -H "Content-Type: application/json"
```

---

### Charts

#### GET /api/v1/charts/:chartType/categories (PUBLIC)
**Chart Categories**

Get the categories for a chart

```bash
curl -X GET "http://localhost:4000/api/v1/charts/apple/categories" \
  -H "Content-Type: application/json"
```

---

#### GET /api/v1/charts/:chartType/countries (PUBLIC)
**Chart Countries**

Get the available countries for a chart type

```bash
curl -X GET "http://localhost:4000/api/v1/charts/apple/countries" \
  -H "Content-Type: application/json"
```

---

#### GET /api/v1/charts
**Historical Chart**

Get a historical chart

```bash
curl -X GET "http://localhost:4000/api/v1/charts?category=top+podcasts&chartType=apple&country=us&date=2026-06-09" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/charts/latest (PUBLIC)
**Latest Chart**

Get the latest chart

```bash
curl -X GET "http://localhost:4000/api/v1/charts/latest?category=top+podcasts&chartType=apple&country=us" \
  -H "Content-Type: application/json"
```

---

### Episodes

#### GET /api/v1/episodes/:episodeId/details
**Episode Details**

Get the details of an episode

```bash
curl -X GET "http://localhost:4000/api/v1/episodes/cbd08a7c-b936-4ee8-87d1-12df08da1c9f/details" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/episodes/:episodeId/download/transcript
**Episode Transcript Download**

File download the transcript of an episode

```bash
curl -X GET "http://localhost:4000/api/v1/episodes/cbd08a7c-b936-4ee8-87d1-12df08da1c9f/download/transcript?format=txt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/episodes/:episodeId/transcript-text
**Episode Transcript Text**

Get the transcript text of an episode

```bash
curl -X GET "http://localhost:4000/api/v1/episodes/cbd08a7c-b936-4ee8-87d1-12df08da1c9f/transcript-text" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/episodes/:episodeId/transcript-timestamps
**Episode Transcript Timestamps**

Get the transcript of an episode with word-level timestamps in a structured JSON format

```bash
curl -X GET "http://localhost:4000/api/v1/episodes/cbd08a7c-b936-4ee8-87d1-12df08da1c9f/transcript-timestamps" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/episodes/latest (PUBLIC)
**Latest Episodes**

Get the latest 150 episodes

```bash
curl -X GET "http://localhost:4000/api/v1/episodes/latest?categories=technology%2Cbusiness%2Cnews&hasTranscript=true&language=en" \
  -H "Content-Type: application/json"
```

---

### Guest Profiles

#### POST /api/v1/guest-profiles/:guestProfileId/archive
**Archive Guest Profile**

Archive a guest profile and its associated project. This sets the status to ARCHIVED.

```bash
curl -X POST "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/archive" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### POST /api/v1/guest-profiles
**Create Guest Profile**

Create a new guest profile with basic information. The profile is created in ACTIVE status along with an associated project. Required fields are firstName, lastName, and shortBio. Optional fields include contact details, social links, and bio details. When provided, LinkedIn URLs trigger a profile scrape, website URLs trigger a website crawl, and company names trigger a SERP search — all run asynchronously in the background. A guest appearances search is also triggered automatically.

```bash
curl -X POST "http://localhost:4000/api/v1/guest-profiles" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "firstName": "Jane",
  "lastName": "Doe",
  "shortBio": "Jane Doe is a marketing expert with 10 years of experience in B2B SaaS."
}'
```

---

#### GET /api/v1/guest-profiles/:guestProfileId/download
**Download Guest Profile**

Download a guest profile as a document. Supported formats are HTML, DOCX, and PDF.

```bash
curl -X GET "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/download" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/guest-profiles/:guestProfileIdOrProjectId
**Get Guest Profile Details**

Get detailed information about a specific guest profile including bio, contact details, social media links, and documents

```bash
curl -X GET "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### POST /api/v1/guest-profiles/:guestProfileId/regenerate-bio
**Regenerate Guest Bio**

Use AI to regenerate the guest bio based on all available profile data including documents, LinkedIn data, and website content. Returns the generated bio fields.

```bash
curl -X POST "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/regenerate-bio" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### PUT /api/v1/guest-profiles/:guestProfileId/bio
**Update Guest Profile Bio**

Update the bio fields of a guest profile including short bio, long bio, goals, areas of expertise, topics to discuss, things to avoid, and additional context.

```bash
curl -X PUT "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/bio" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### PUT /api/v1/guest-profiles/:guestProfileId/contact-details
**Update Guest Profile Contact Details**

Update the contact details of a guest profile including name, email, phone, company, website URL, booking URL, LinkedIn, and one-pager URL.

```bash
curl -X PUT "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/contact-details" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### PUT /api/v1/guest-profiles/:guestProfileId/social-media-links
**Update Guest Profile Social Media Links**

Update the social media links associated with a guest profile.

```bash
curl -X PUT "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/social-media-links" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### POST /api/v1/guest-profiles/:guestProfileId/documents
**Upload Guest Profile Documents**

Upload files (PDF, DOCX, TXT, CSV, JPG, JPEG, PNG) to a guest profile. Documents are automatically analyzed in the background. Send files as multipart form data with field name "documents". Maximum 5 files per request.

```bash
curl -X POST "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/documents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

### Podcasts

#### GET /api/v1/podcasts/apple-id/lookup
**Apple ID Comprehensive Lookup**

Comprehensive lookup by Apple ID - checks Podcast, PodcastAppleId, PodcastNewRequest, and scraper database

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/apple-id/lookup?id=315114957" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/latest (PUBLIC)
**Latest Podcasts**

Get the latest podcasts

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/latest?hasTranscripts=true" \
  -H "Content-Type: application/json"
```

---

#### GET /api/v1/podcasts/multiple
**Multiple Podcasts**

Get multiple podcasts by their IDs in a single request

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/multiple?podcastIds=58bb043a-ad45-4844-a6d8-7492d901dc30%2C7b09a744-f2ed-458e-9b04-0c0c48651c2a&details=basic" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/:podcastIdOrSlug/all-details
**Podcast All Details**

This wraps all the other endpoints for a podcast so you can get all the details in a single request.

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/all-details" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/:podcastIdOrSlug/charts
**Podcast Chart Position**

Get the latest positions of a podcast in a chart

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/charts?country=us" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/:podcastIdOrSlug/contacts
**Podcast Contacts**

Get the contacts for a podcast

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/contacts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/:podcastIdOrSlug
**Podcast Details**

Get a podcast by ID or slug

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/:podcastIdOrSlug/episodes
**Podcast Episodes**

Get the episodes for a podcast

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/episodes" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/id/lookup
**Podcast ID Lookup**

Lookup a podcast by ID

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/id/lookup?appleId=315114957" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/:podcastIdOrSlug/related-podcasts
**Podcast Related Podcasts**

Get the related podcasts for a podcast

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/related-podcasts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/:podcastIdOrSlug/reviews
**Podcast Reviews**

Get the reviews for a podcast

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/reviews" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/:podcastIdOrSlug/social-media
**Podcast Social Media**

Get the social media data for a podcast

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/social-media" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/:podcastIdOrSlug/youtube
**Podcast Youtube Details**

Get the youtube data for a podcast

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/youtube" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/:podcastIdOrSlug/refresh
**Refresh Podcast**

Refresh podcast metadata and thumbnail from RSS feed. Rate limited to once per minute per podcast.

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/refresh?updatePodcastThumbnail=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

### Polling

#### GET /api/v1/polling/updates
**Poll for Updates**

Poll for updates across your team. Returns a chronological feed of events (completed requests, new guest appearances, podcasts added to projects, alert matches) since a given timestamp or cursor. Designed for regular polling — use the returned cursor for efficient subsequent calls.

```bash
curl -X GET "http://localhost:4000/api/v1/polling/updates?limit=10" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

### Projects

#### POST /api/v1/projects/:projectSlug/podcasts
**Add Podcast to Project**

Add a single podcast to a project's list

```bash
curl -X POST "http://localhost:4000/api/v1/projects/example-project/podcasts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/projects/:projectSlug/details
**Get Project Details**

Get detailed information about a specific project including metadata and statistics

```bash
curl -X GET "http://localhost:4000/api/v1/projects/example-project/details" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/projects/:projectSlug/strategies
**Get Project Strategies**

Get all strategies associated with a project

```bash
curl -X GET "http://localhost:4000/api/v1/projects/example-project/strategies" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/projects
**Get Projects**

Get a list of projects for the authenticated user

```bash
curl -X GET "http://localhost:4000/api/v1/projects?states=ACTIVE" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### DELETE /api/v1/projects/:projectSlug/podcasts/:listedPodcastId
**Remove Podcast on Project**

Remove a podcast from a project's list

```bash
curl -X DELETE "http://localhost:4000/api/v1/projects/example-project/podcasts/123" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### PATCH /api/v1/projects/:projectSlug/podcasts/:listedPodcastId
**Update Podcast on Project**

Update the details or status of a podcast within a project

```bash
curl -X PATCH "http://localhost:4000/api/v1/projects/example-project/podcasts/123" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### PATCH /api/v1/projects/:projectSlug
**Update Project**

Update an existing project's details

```bash
curl -X PATCH "http://localhost:4000/api/v1/projects/example-project" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

### Search

#### POST /api/v1/search/episodes
**Search Episodes**

Search for episodes by title, description, or transcript text

```bash
curl -X POST "http://localhost:4000/api/v1/search/episodes" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "searchTerms": [
    {
      "searchTargets": [
        "podcast-title"
      ],
      "searchTerm": "This Week In Startups",
      "searchType": "text",
      "searchTermOptions": {
        "phraseMatch": true,
        "matchMode": "must"
      }
    },
    {
      "searchTargets": [
        "transcript"
      ],
      "searchTerm": "podcast",
      "searchType": "text",
      "searchTermOptions": {
        "matchMode": "optional"
      }
    }
  ],
  "languages": [
    "en"
  ],
  "lastEpisodeDateSince": "2026-05-12T22:56:23.652Z",
  "sortOrder": [
    {
      "field": "recentActivity",
      "direction": "desc"
    }
  ]
}'
```

---

#### POST /api/v1/search/podcasts
**Search Podcasts**

Search for podcasts by title, description, or RSS feed URL

```bash
curl -X POST "http://localhost:4000/api/v1/search/podcasts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "searchTerms": [
    {
      "searchTargets": [
        "podcast-title",
        "podcast-title"
      ],
      "searchTerm": "podcast creation",
      "searchType": "text",
      "searchTermOptions": {
        "matchMode": "must",
        "phraseMatch": true,
        "slop": 1
      }
    }
  ],
  "languages": [
    "en"
  ],
  "lastEpisodeDateSince": "2026-05-12",
  "sortOrder": [
    {
      "field": "recentActivity",
      "direction": "desc"
    }
  ]
}'
```

---

### Stats

#### GET /api/v1/rss/stats/public/podcast2 (PUBLIC)
**Podcast 2 Stats**

We track the number of podcasts that have implemented podcast2 rss fields and the number of episodes that have transcripts

```bash
curl -X GET "http://localhost:4000/api/v1/rss/stats/public/podcast2" \
  -H "Content-Type: application/json"
```

---

### Teams

#### PUT /api/v1/teams/podcasts/:podcastId
**Add Podcast to Team**

Add a podcast to your team

```bash
curl -X PUT "http://localhost:4000/api/v1/teams/podcasts/58bb043a-ad45-4844-a6d8-7492d901dc30" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "sync": false,
  "blacklist": false
}'
```

---

#### GET /api/v1/teams/podcasts
**Get Team Podcasts**

Get all podcasts associated with your team

```bash
curl -X GET "http://localhost:4000/api/v1/teams/podcasts?limit=10&offset=0" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### DELETE /api/v1/teams/podcasts/multiple
**Remove Multiple Podcasts from Team**

Remove multiple podcasts from your team by PodEngine IDs or Apple IDs

```bash
curl -X DELETE "http://localhost:4000/api/v1/teams/podcasts/multiple" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### DELETE /api/v1/teams/podcasts/:podcastId
**Remove Podcast from Team**

Remove a podcast from your team

```bash
curl -X DELETE "http://localhost:4000/api/v1/teams/podcasts/58bb043a-ad45-4844-a6d8-7492d901dc30" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/teams/request-history
**Request History**

Get team request history

```bash
curl -X GET "http://localhost:4000/api/v1/teams/request-history?limit=10&skip=0&filterCompleted=false&requestType=transcription" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

### Transcriptions

#### GET /api/v1/episodes/:episodeId/transcription-request
**Request Episode Transcription**

Request an episode to be transcribed. This typically takes 1-2 hours and you can check progress using the Requests History endpoint.

```bash
curl -X GET "http://localhost:4000/api/v1/episodes/cbd08a7c-b936-4ee8-87d1-12df08da1c9f/transcription-request" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/podcasts/:podcastId/transcription-request
**Request Podcast Transcription**

Request multiple episodes for a Podcast to be transcribed and optionally the future Podcast episodes to be transcribed automatically.

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/:podcastId/transcription-request?type=since&requestFutureEpisodes=false" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/teams/transcriptions
**Transcription Requests**

Get transcription request history for your team

```bash
curl -X GET "http://localhost:4000/api/v1/teams/transcriptions?limit=10&filterCompleted=false" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

### Usage

#### GET /api/v1/teams/usage/current
**Current Month Usage**

Get your team's current month API usage and limits for each usage category, along with enabled feature flags and plan information.

```bash
curl -X GET "http://localhost:4000/api/v1/teams/usage/current" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/teams/usage/daily
**Daily Usage Trend**

Get daily usage breakdown for your team over a time window (7, 30, or 90 days), with limit thresholds for comparison.

```bash
curl -X GET "http://localhost:4000/api/v1/teams/usage/daily" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/teams/usage/monthly
**Monthly Usage History**

Get monthly usage history for your team over the past N months.

```bash
curl -X GET "http://localhost:4000/api/v1/teams/usage/monthly" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

#### GET /api/v1/teams/usage/members
**Team Member Usage**

Get usage breakdown by team member over a time window.

```bash
curl -X GET "http://localhost:4000/api/v1/teams/usage/members" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

## Response Format

All responses follow this structure:

```json
{ "status": "OK", "data": { ... } }
```

Errors:
```json
{ "status": "ERROR", "error": { "code": "ERROR_CODE", "message": "..." } }
```

## Error Codes

- `400` Bad request — check params/body
- `401` Unauthorized — invalid or missing API key
- `403` Forbidden — plan does not include this endpoint
- `404` Not found
- `429` Rate limited — back off and retry with exponential backoff
- `500` Server error — contact support@podengine.ai if persistent

## Tips for AI assistants

- All resource IDs are UUIDs
- Dates use ISO 8601 (e.g., `2024-01-15T00:00:00Z`)
- Pagination is via `pageSize` and `page` query params
- Always check `hasTranscript` on an episode before requesting transcript text
- Use the OpenAPI spec at `/api-docs/openapi.json` for full machine-readable schemas
- Use `/api-docs/llms-full.txt` if you want every request/response field inlined