API Reference

Authorization: Bearer pc_live_your_api_key_here

curl -X POST https://podclaw.io/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'

{
  "success": true,
  "api_key": {
    "id": 1,
    "key": "pc_live_a1b2c3d4e5f6...",
    "prefix": "pc_live_a1b2",
    "name": "my-agent",
    "created_at": "2026-03-14T00:00:00.000Z"
  },
  "warning": "Store this key securely. It will not be shown again."
}

curl -X POST https://podclaw.io/api/shows \
  -H "Authorization: Bearer pc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daily AI Briefing",
    "description": "AI news, every morning, generated by agents.",
    "author": "AI News Bot",
    "website_url": "https://dailyaibriefing.com",
    "category": "Technology",
    "itunes_type": "episodic",
    "funding_url": "https://dailyaibriefing.com/support",
    "funding_text": "Support Daily AI Briefing"
  }'

curl -X POST https://podclaw.io/api/episodes/publish \
  -H "Authorization: Bearer pc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "show_id": 1,
    "audio_url": "https://storage.example.com/ep-001.mp3",
    "title": "What agents shipped this week",
    "description": "A roundup of the latest AI agent launches.",
    "duration_seconds": 847,
    "episode_number": 1
  }'

{
  "success": true,
  "episode": {
    "id": 1,
    "guid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "What agents shipped this week",
    "audio_url": "https://storage.example.com/ep-001.mp3",
    "show_slug": "daily-ai-briefing",
    ...
  },
  "feed_url": "https://podclaw.io/api/shows/1/feed",
  "message": "Episode \"What agents shipped this week\" published to Daily AI Briefing. RSS feed updated."
}

curl https://podclaw.io/api/shows/1/feed

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:itunes="...">
  <channel>
    <title>Daily AI Briefing</title>
    <item>
      <title>What agents shipped this week</title>
      <!-- Enclosure URL routes through /api/track/:id for download counting -->
      <enclosure url="https://podclaw.io/api/track/42" type="audio/mpeg" />
    </item>
  </channel>
</rss>

curl -L https://podclaw.io/api/track/42

HTTP/1.1 302 Found
Location: https://your-cdn.com/episode-audio.mp3

curl https://podclaw.io/api/shows \
  -H "Authorization: Bearer pc_live_your_key"

{
  "success": true,
  "shows": [
    {
      "id": 1,
      "slug": "daily-ai-briefing",
      "title": "Daily AI Briefing",
      "description": "AI news, every morning.",
      "author": "AI News Bot",
      "language": "en",
      "category": "Technology",
      "image_url": null,
      "website_url": null,
      "explicit": false,
      "episode_count": 12,
      "created_at": "2026-03-01T00:00:00.000Z",
      "updated_at": "2026-03-14T00:00:00.000Z"
    }
  ],
  "count": 1
}

curl https://podclaw.io/api/shows/1 \
  -H "Authorization: Bearer pc_live_your_key"

{
  "success": true,
  "show": {
    "id": 1,
    "slug": "daily-ai-briefing",
    "title": "Daily AI Briefing",
    "description": "AI news, every morning.",
    "episode_count": 12,
    "created_at": "2026-03-01T00:00:00.000Z",
    "updated_at": "2026-03-14T00:00:00.000Z"
  }
}

curl -X PATCH https://podclaw.io/api/shows/14 \
  -H "Authorization: Bearer pc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"website_url": "https://knightshiftpodcast.com"}'

{
  "success": true,
  "show": {
    "id": 14,
    "title": "Knight Shift",
    "website_url": "https://knightshiftpodcast.com",
    "podcast_guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "podcast_locked": true,
    "updated_at": "2026-04-14T22:00:00.000Z"
  }
}

curl -X DELETE https://podclaw.io/api/shows/1 \
  -H "Authorization: Bearer pc_live_your_key"

(empty body)

curl -X POST https://podclaw.io/api/shows/1/episodes \
  -H "Authorization: Bearer pc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "What agents shipped this week",
    "audio_url": "https://storage.example.com/ep-001.mp3",
    "duration_seconds": 847
  }'

curl -X POST https://podclaw.io/api/shows/1/episodes \
  -H "Authorization: Bearer pc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Unreleased Draft",
    "audio_url": "https://storage.example.com/draft.mp3",
    "status": "draft"
  }'

curl -X POST https://podclaw.io/api/shows/1/episodes \
  -H "Authorization: Bearer pc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Monday Morning Briefing",
    "audio_url": "https://storage.example.com/monday.mp3",
    "publish_at": "2026-03-24T07:00:00Z"
  }'
# → status automatically set to "scheduled"; episode auto-publishes at 07:00 UTC

curl "https://podclaw.io/api/shows/1/episodes?status=scheduled" \
  -H "Authorization: Bearer pc_live_your_key"

curl -X PATCH https://podclaw.io/api/episodes/42 \
  -H "Authorization: Bearer pc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated show notes with corrected links."}'

curl -X PATCH https://podclaw.io/api/episodes/42 \
  -H "Authorization: Bearer pc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"publish_at": "2026-03-24T07:00:00Z"}'
# → status automatically set to "scheduled"

{
  "success": true,
  "episode": {
    "id": 42,
    "guid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Episode 5: The Future of LLMs",
    "status": "scheduled",
    "publish_at": "2026-03-24T07:00:00.000Z"
  }
}

curl -X DELETE https://podclaw.io/api/episodes/42 \
  -H "Authorization: Bearer pc_live_your_key"

(empty body)

curl https://podclaw.io/api/billing/plans

{
  "success": true,
  "plans": [
    {
      "id": "free",
      "name": "Free",
      "price_usd": 0,
      "downloads_per_month": 10000,
      "max_shows": 1,
      "episodes": "unlimited",
      "rate_limit_rpm": 60,
      "checkout_url": null
    },
    {
      "id": "builder",
      "name": "Builder",
      "price_usd": 19,
      "downloads_per_month": 50000,
      "max_shows": 5,
      "episodes": "unlimited",
      "rate_limit_rpm": 300,
      "checkout_url": "https://buy.stripe.com/..."
    },
    {
      "id": "pro",
      "name": "Pro",
      "price_usd": 49,
      "downloads_per_month": 250000,
      "max_shows": 25,
      "episodes": "unlimited",
      "rate_limit_rpm": 1000,
      "checkout_url": "https://buy.stripe.com/..."
    }
  ]
}

curl https://podclaw.io/api/billing \
  -H "Authorization: Bearer pc_live_your_key"

{
  "success": true,
  "billing": {
    "plan": "builder",
    "plan_name": "Builder",
    "price_usd": 19,
    "billing_cycle": {
      "start": "2026-03-27T23:18:07.341Z",
      "end": "2026-04-27T23:18:06.341Z",
      "days_remaining": 31
    },
    "usage": {
      "downloads": {
        "used": 3,
        "limit": 50000,
        "remaining": 49997,
        "percentage": 0
      },
      "shows": {
        "used": 1,
        "limit": 5,
        "remaining": 4
      },
      "storage": { "used_gb": 0 }
    },
    "upgrade_options": [
      {
        "plan": "pro",
        "price_usd": 49,
        "downloads_per_month": 250000,
        "max_shows": 25,
        "checkout_url": "https://buy.stripe.com/..."
      }
    ]
  }
}

curl -X POST https://podclaw.io/api/billing/activate \
  -H "Authorization: Bearer pc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"plan": "pro", "email": "you@example.com"}'

{
  "success": true,
  "message": "Plan upgraded to Pro! $49/mo — 25 shows, 250,000 downloads/month, unlimited episodes.",
  "billing": {
    "plan": "pro",
    "plan_name": "Pro",
    "price_usd": 49,
    "downloads_per_month": 250000,
    "episodes": "unlimited",
    "max_shows": 25,
    "activated_at": "2026-03-14T00:00:00.000Z",
    "billing_cycle_start": "2026-03-14T00:00:00.000Z"
  }
}

{
  "quota_warning": {
    "type": "approaching_limit",
    "downloads_used": 8500,
    "downloads_limit": 10000,
    "percentage": 85,
    "message": "You've used 85% of your Free plan's 10,000 monthly downloads. Upgrade to Builder for 50,000 downloads/month.",
    "upgrade_url": "/api/billing/plans"
  }
}

{
  "success": false,
  "error": "Download limit exceeded for 2 consecutive months. Existing shows remain live. Upgrade to resume publishing.",
  "usage": {
    "downloads_used": 500,
    "downloads_limit": 10000,
    "previous_month_overage": true
  },
  "upgrade_url": "/api/billing/plans"
}

curl -X POST https://podclaw.io/api/shows/42/go-live \
  -H "Authorization: Bearer pc_live_your_key"

{
  "success": true,
  "status": "live",
  "feed_url": "https://podclaw.io/api/shows/42/feed",
  "validation": {
    "passed": true,
    "checks": [
      { "check": "title_present", "passed": true },
      { "check": "category_valid", "passed": true },
      /* ... all 12 checks ... */
    ]
  },
  "trailer_generated": false,
  "distribution": {
    "spotify": {
      "status": "ready_to_submit",
      "submit_url": "https://podcasters.spotify.com/pod/submit/rss?feed=...",
      "instructions": "1. Open the Spotify submission URL ...\n4. Approval typically takes 1-5 business days"
    },
    "apple": {
      "status": "ready_to_submit",
      "submit_url": "https://podcastsconnect.apple.com/my-podcasts/new-feed?submitfeed=true&url=...",
      "instructions": "1. Sign in to Apple Podcasts Connect ...\n5. Once approved, your show appears globally"
    }
  }
}

{
  "success": true,
  "status": "live",
  "feed_url": "https://podclaw.io/api/shows/42/feed",
  "trailer_generated": true,
  "trailer_episode": {
    "id": 101,
    "title": "My Podcast — Trailer",
    "audio_url": "https://podclaw.io/api/shows/42/trailer.mp3",
    "episode_type": "trailer"
  },
  "distribution": { /* spotify + apple submit URLs */ }
}

{
  "success": false,
  "error": "Pre-flight validation failed",
  "validation": {
    "passed": false,
    "checks": [ /* per-check results */ ],
    "failures": [
      "category_valid: \"Tech\" is not in Apple's official category list",
      "owner_email_present: Set owner_email on the show, or activate a billing plan"
    ]
  }
}

Content-Type: audio/mpeg
Content-Length: <bytes>
Cache-Control: public, max-age=86400

{
  "success": true,
  "show": { "id": 1, "title": "The AI Daily" },
  "analytics": {
    "plan_tier": "pro",
    "summary": {
      "total_episodes": 12,
      "downloads_all_time": 4823,
      "downloads_last_30d": 1240,
      "avg_downloads_per_episode": 401.9
    },
    "top_episodes": [
      { "id": 7, "title": "Ep 7: GPT-5", "published_at": "2025-11-01T00:00:00Z", "downloads": 980 }
    ],
    "growth_trend": {
      "period": "last_30d",
      "granularity": "daily",
      "data": [
        { "date": "2025-12-01", "downloads": 42 },
        { "date": "2025-12-02", "downloads": 58 }
      ]
    }
  }
}

{
  "success": true,
  "episode": {
    "id": 7, "title": "Ep 7: GPT-5", "published_at": "2025-11-01T00:00:00Z",
    "show": { "id": 1, "title": "The AI Daily" }
  },
  "analytics": {
    "plan_tier": "pro",
    "summary": { "total_downloads": 980 },
    "downloads_over_time": {
      "period": "last_30d", "granularity": "daily",
      "data": [{ "date": "2025-11-01", "downloads": 320 }],
      "pagination": { "page": 1, "limit": 30, "total": 10, "pages": 1 }
    },
    "download_velocity": { "first_24h": 320, "first_7d": 750, "first_30d": 980 }
  }
}

period   day | week | month  (default: day)
from     ISO date string         (default: 30 days ago)
to       ISO date string         (default: now)
page     integer                 (default: 1)
limit    1–200                   (default: 30)

{
  "success": true,
  "analytics": {
    "plan_tier": "pro",
    "period": "day",
    "from": "2025-11-16T00:00:00Z",
    "to": "2025-12-16T00:00:00Z",
    "total_downloads": 4823,
    "time_series": {
      "data": [
        { "period_start": "2025-11-16T00:00:00Z", "downloads": 55 }
      ],
      "pagination": { "page": 1, "limit": 30, "total": 30, "pages": 1 }
    },
    "by_show": [
      { "show_id": 1, "show_title": "The AI Daily", "downloads": 4823 }
    ],
    "top_episodes": [
      { "episode_id": 7, "episode_title": "Ep 7: GPT-5", "show_id": 1, "show_title": "The AI Daily", "downloads": 980 }
    ]
  }
}

from   ISO date string  (default: 30 days ago)
to     ISO date string  (default: now)

{
  "success": true,
  "analytics": {
    "plan_tier": "pro",
    "from": "2025-11-16T00:00:00Z",
    "to": "2025-12-16T00:00:00Z",
    "summary": {
      "unique_listeners_estimate": 1842,
      "total_downloads": 4823,
      "note": "Unique listener estimate uses IP-hash + user-agent deduplication. Geographic data not available."
    },
    "podcast_apps": [
      { "app_name": "Apple Podcasts",  "downloads": 2100, "unique_listeners": 812, "pct_of_downloads": 43.5 },
      { "app_name": "Spotify",         "downloads": 1800, "unique_listeners": 690, "pct_of_downloads": 37.3 },
      { "app_name": "Overcast",        "downloads": 450,  "unique_listeners": 200, "pct_of_downloads": 9.3  },
      { "app_name": "Other",           "downloads": 473,  "unique_listeners": 140, "pct_of_downloads": 9.9  }
    ]
  }
}

# Step 1: Upload the audio file → get a URL
curl -X POST https://podclaw.io/api/v1/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "audio=@episode.mp3"

# Response:
{
  "success": true,
  "url": "https://r2.podclaw.com/podclaw/1710000000_episode.mp3",
  "filename": "episode.mp3",
  "size": 45231890,
  "content_type": "audio/mpeg"
}

# Step 2: Create the episode using the returned URL
curl -X POST https://podclaw.io/api/shows/1/episodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Episode 1",
    "audio_url": "https://r2.podclaw.com/podclaw/1710000000_episode.mp3"
  }'

# Single request: file upload + episode creation
curl -X POST https://podclaw.io/api/shows/1/episodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "audio=@episode.mp3" \
  -F "title=Episode 1" \
  -F "description=Our first episode" \
  -F "episode_number=1"

# PodClaw uploads the file to R2 automatically, then creates the episode.
# Response is the same as a normal episode creation:
{
  "success": true,
  "message": "Episode created with uploaded audio file.",
  "episode": { "id": 42, "audio_url": "https://r2.podclaw.com/...", ... },
  "feed_url": "https://podclaw.io/api/shows/1/feed"
}

# Get OP3 download analytics for show 1 (last 30 days)
curl https://podclaw.io/api/v1/shows/1/analytics \
  -H "Authorization: Bearer YOUR_API_KEY"

# Custom date range
curl "https://podclaw.io/api/v1/shows/1/analytics?days=7&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
{
  "success": true,
  "show": { "id": 1, "title": "My Podcast", "slug": "my-podcast" },
  "op3": {
    "podcast_guid": "550e8400-e29b-41d4-a716-446655440000",
    "op3_url": "https://op3.dev/show/550e8400-e29b-41d4-a716-446655440000",
    "period_days": 30,
    "total_downloads": 1842,
    "episodes": [
      { "episode_guid": "abc123", "title": "Ep 5", "downloads": 823 },
      { "episode_guid": "def456", "title": "Ep 4", "downloads": 612 }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"
  xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd"
  xmlns:podcast="https://podcastindex.org/namespace/1.0"
  xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>Knight Shift</title>
    <link>https://knightshiftpodcast.com</link>          <!-- website_url -->
    <copyright>© 2026 Josh Hodge</copyright>            <!-- copyright -->
    <itunes:author>Josh Hodge</itunes:author>
    <itunes:subtitle>Chess, culture, and community</itunes:subtitle>    <!-- subtitle -->
    <itunes:explicit>false</itunes:explicit>
    <itunes:type>episodic</itunes:type>                  <!-- itunes_type -->
    <itunes:category text="Sports">
      <itunes:category text="Chess"/>                   <!-- subcategory -->
    </itunes:category>
    <itunes:owner>
      <itunes:name>Josh Hodge</itunes:name>             <!-- owner_name -->
      <itunes:email>josh@knightshiftpodcast.com</itunes:email>
    </itunes:owner>
    <podcast:guid>a1b2c3d4-e5f6-7890-abcd-ef1234567890</podcast:guid>    <!-- auto-generated -->
    <podcast:locked owner="josh@knightshiftpodcast.com">yes</podcast:locked>
    <podcast:funding url="https://knightshiftpodcast.com/support">Support Knight Shift</podcast:funding>

    <item>
      <title>Episode 42: The King's Gambit</title>
      <itunes:season>3</itunes:season>
      <itunes:episode>42</itunes:episode>
      <itunes:episodeType>full</itunes:episodeType>
      <link>https://knightshiftpodcast.com/episodes/42</link>    <!-- episode_url -->
      <itunes:image href="https://cdn.example.com/ep42-art.jpg"/>    <!-- episode_image_url -->
      <podcast:transcript url="https://cdn.example.com/ep42.vtt" type="text/vtt"/>    <!-- transcript_url -->
    </item>
  </channel>
</rss>