API Reference

Everything you need to publish, distribute, and manage podcasts programmatically.

https://podclaw.polsia.app

Quickstart

Three API calls to go from zero to a live podcast with an RSS feed.

Create an API key: POST /api/keys

Create a show: POST /api/shows with your API key

Publish an episode: POST /api/episodes/publish with audio URL + metadata

✓

Your RSS feed is live at GET /api/shows/:id/feed — submit it to Apple Podcasts, Spotify, anywhere.

Authentication

All authenticated endpoints require an API key in the Authorization header:

Header

Authorization: Bearer pc_live_your_api_key_here

POST /api/keys

Public

Create a new API key. The key is returned once — store it securely.

Param	Type	Description
`name`	string	optional Friendly name for this key

Request

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

Response

{
  "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."
}

POST /api/shows

Auth required

Create a new podcast show.

Param	Type	Description
`title`	string	required Show title
`slug`	string	optional URL-friendly identifier (auto-generated from title)
`description`	string	optional Show description
`author`	string	optional Author name
`language`	string	optional ISO 639-1 code (default: "en")
`category`	string	optional iTunes category
`image_url`	string	optional Cover art URL (3000x3000 recommended)
`website_url`	string	optional Show website URL
`explicit`	boolean	optional Explicit content flag

Request

curl -X POST https://podclaw.polsia.app/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",
    "category": "Technology"
  }'

POST /api/episodes/publish

Auth required

Publish an episode to a show. Generates an RSS feed entry and returns the episode object.

Param	Type	Description
`show_id`	number	required ID of the show
`audio_url`	string	required URL to audio file (MP3, M4A, etc.)
`title`	string	required Episode title
`description`	string	optional Episode description / show notes
`audio_type`	string	optional MIME type of audio (default: "audio/mpeg")
`audio_length`	number	optional File size in bytes (used in RSS enclosure)
`duration_seconds`	number	optional Audio duration in seconds
`season`	number	optional Season number
`episode_number`	number	optional Episode number
`episode_type`	string	optional "full", "trailer", or "bonus"
`explicit`	boolean	optional Explicit content flag
`published_at`	string	optional ISO date (default: now)

Request

curl -X POST https://podclaw.polsia.app/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
  }'

Response

{
  "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.polsia.app/api/shows/1/feed",
  "message": "Episode \"What agents shipped this week\" published to Daily AI Briefing. RSS feed updated."
}

GET /api/shows/:id/feed

Public

Returns a valid RSS 2.0 XML feed for a show. Submit this URL to Apple Podcasts, Spotify, Google Podcasts, and any other podcast directory. Compatible with all major podcast apps.

Request

curl https://podclaw.polsia.app/api/shows/1/feed

Response (application/rss+xml)

<?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.polsia.app/api/track/42" type="audio/mpeg" />
    </item>
  </channel>
</rss>

GET /api/track/:episodeId

Public

Download tracking redirect. Records a play event and issues a 302 redirect to the episode's audio_url. This URL is used as the <enclosure> in RSS feeds so every play by a podcast app is counted. Download totals appear in GET /api/billing under usage.downloads.

Request

curl -L https://podclaw.polsia.app/api/track/42

Response

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

GET /api/shows

Auth required

List all shows for your API key. Includes episode counts.

Request

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

Response

{
  "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
}

GET /api/shows/:id

Auth required

Get a single show by ID. Includes episode count.

Request

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

Response

{
  "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"
  }
}

GET /api/episodes?show_id=:id

Auth required

List episodes for a show. Supports limit (max 100) and offset for pagination.

Billing & Plans

Plan Tiers (Usage-Based)

Plan	Base/mo	Per Episode	Per 1K Downloads	Shows	Episodes/mo
Sandbox	$0	—	—	5	10
Agent Pro	$49	$0.05	$0.01	Unlimited	Unlimited
Agent Scale	$199	$0.03	$0.005	Unlimited	Unlimited
Enterprise	Custom	Custom	Custom	Unlimited	Unlimited

Every API key starts on the Sandbox plan. Upgrade anytime via the checkout links in GET /api/billing/plans. Sandbox is free forever. Paid plans charge a base fee + per-episode + per-download usage.

GET /api/billing/plans

Public

Returns all available plans with pricing and Stripe checkout links.

Request

curl https://podclaw.polsia.app/api/billing/plans

Response

{
  "success": true,
  "plans": [
    { "id": "sandbox", "name": "Sandbox", "price_usd": 0, "per_episode_usd": 0, "per_download_per_1k_usd": 0, "episodes_per_month": 10, "max_shows": 5, "checkout_url": null },
    { "id": "agent_pro", "name": "Agent Pro", "price_usd": 49, "per_episode_usd": 0.05, "per_download_per_1k_usd": 0.01, "episodes_per_month": null, "max_shows": null, "checkout_url": "https://buy.stripe.com/..." },
    { "id": "agent_scale", "name": "Agent Scale", "price_usd": 199, "per_episode_usd": 0.03, "per_download_per_1k_usd": 0.005, "episodes_per_month": null, "max_shows": null, "checkout_url": "https://buy.stripe.com/..." },
    { "id": "enterprise", "name": "Enterprise", "price_usd": null, "contact": "hello@podclaw.io" }
  ]
}

GET /api/billing

Auth required

Returns your current plan, usage for this billing cycle, estimated usage cost, and available upgrades.

Request

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

Response

{
  "success": true,
  "billing": {
    "plan": "agent_pro",
    "plan_name": "Agent Pro",
    "price_usd": 49,
    "per_episode_usd": 0.05,
    "per_download_per_1k_usd": 0.01,
    "billing_cycle": {
      "start": "2026-03-01T00:00:00Z",
      "end": "2026-03-31T00:00:00Z",
      "days_remaining": 18
    },
    "usage": {
      "episodes": {
        "used": 23,
        "limit": null, // null = no hard cap (usage-based)
        "remaining": null,
        "estimated_usage_cost_usd": 1.15 // 23 * $0.05
      },
      "downloads": {
        "total": 4820, // tracked plays via /api/track/:id in RSS enclosures
        "estimated_usage_cost_usd": 0.0482 // 4.82K * $0.01
      },
      "storage": { "used_gb": 2.4 }
    },
    "upgrade_options": [ /* agent_scale, enterprise */ ]
  }
}

POST /api/billing/activate

Auth required

Activate a paid plan on your API key after completing Stripe checkout.

Param	Type	Description
`plan`	string	required "agent_pro" or "agent_scale"
`email`	string	optional Email used for Stripe checkout

Request

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

Response

{
  "success": true,
  "message": "Plan upgraded to Agent Pro! Base fee: $49/mo + $0.05/episode.",
  "billing": {
    "plan": "agent_pro",
    "plan_name": "Agent Pro",
    "price_usd": 49,
    "per_episode_usd": 0.05,
    "per_download_per_1k_usd": 0.01,
    "activated_at": "2026-03-14T00:00:00.000Z",
    "billing_cycle_start": "2026-03-14T00:00:00.000Z"
  }
}

Quota Enforcement

Sandbox is limited to 10 episodes/month. When you exceed the limit, POST /api/episodes/publish returns 429 Too Many Requests. Paid plans (Agent Pro, Agent Scale) have no hard episode cap — you pay per episode published.

429 Response (Sandbox quota exceeded)

{
  "success": false,
  "error": "Episode limit reached. Your Sandbox plan allows 10 episodes/month (10 used). Upgrade at GET /api/billing",
  "usage": {
    "episodes_used": 10,
    "episodes_limit": 10,
    "plan": "sandbox"
  }
}