Authenticated API

This endpoint requires a valid JWT Bearer token with content_creator roles. Accessible via the API gateway.

Podcast Distribution API

Podcast creation, multi-platform distribution, RSS feed management, and episode analytics.

Overview

Attribute	Value
Base Path	`/api/v1/creator/podcast`
Authentication	Bearer Token
Required Roles	`creator`, `content_manager`, `podcast_host`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Supported Platforms

Platform	Distribution	Features
Spotify	Automatic	Analytics, Cross-promo
Apple Podcasts	Automatic	Reviews, Categories
YouTube Music	Automatic	Search integration
Amazon Music	Automatic	Alexa integration
YouTube	Video upload	Community, Monetization
Pocket Casts	Automatic	Clips
Overcast	Automatic	Smart Speed stats

Shows

List Shows

GET /api/v1/creator/podcast/shows

Response

{
  "shows": [
    {
      "id": "show_001",
      "title": "The AI Restaurant Podcast",
      "description": "Weekly insights on technology in the food service industry",
      "author": "Olympus Cloud",
      "email": "podcast@example.com",
      "language": "en",
      "category": "Business/Technology",
      "explicit": false,
      "artwork": {
        "url": "https://cdn.example.com/podcast/artwork.jpg",
        "width": 3000,
        "height": 3000
      },
      "rss_feed": "https://feeds.example.com/ai-restaurant-podcast",
      "status": "active",
      "episode_count": 52,
      "total_downloads": 125000,
      "platforms": [
        {
          "platform": "spotify",
          "status": "connected",
          "url": "https://open.spotify.com/show/..."
        },
        {
          "platform": "apple_podcasts",
          "status": "connected",
          "url": "https://podcasts.apple.com/podcast/..."
        }
      ],
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Create Show

POST /api/v1/creator/podcast/shows

Request Body

{
  "title": "Restaurant Tech Weekly",
  "description": "Your weekly dose of restaurant technology news and insights",
  "author": "Chef Tech",
  "email": "tech@restaurant.com",
  "website": "https://restaurant.com/podcast",
  "language": "en",
  "category": {
    "primary": "Business",
    "subcategories": ["Entrepreneurship", "Technology"]
  },
  "explicit": false,
  "copyright": "2026 Restaurant Corp",
  "owner": {
    "name": "Restaurant Corp",
    "email": "podcast@restaurant.com"
  },
  "distribution": {
    "platforms": ["spotify", "apple_podcasts", "google_podcasts", "amazon_music"],
    "auto_distribute": true
  }
}

Response

{
  "id": "show_002",
  "title": "Restaurant Tech Weekly",
  "rss_feed": "https://feeds.example.com/restaurant-tech-weekly",
  "status": "pending_artwork",
  "next_steps": [
    {
      "step": "upload_artwork",
      "required": true,
      "specs": "3000x3000 JPEG or PNG"
    },
    {
      "step": "submit_to_directories",
      "required": false,
      "note": "Auto-submission after first episode"
    }
  ],
  "created_at": "2026-01-24T19:30:00Z"
}

Get Show

GET /api/v1/creator/podcast/shows/{show_id}

Update Show

PUT /api/v1/creator/podcast/shows/{show_id}

Upload Artwork

POST /api/v1/creator/podcast/shows/{show_id}/artwork

Request (multipart/form-data)

file: podcast_artwork.jpg

Episodes

List Episodes

GET /api/v1/creator/podcast/shows/{show_id}/episodes

Query Parameters

Parameter	Type	Description
`status`	string	`draft`, `scheduled`, `published`
`season`	integer	Filter by season
`limit`	integer	Results per page

Response

{
  "episodes": [
    {
      "id": "ep_052",
      "show_id": "show_001",
      "title": "The Future of Voice AI in Drive-Thrus",
      "description": "We explore how voice AI is transforming the drive-thru experience...",
      "season": 2,
      "episode_number": 12,
      "episode_type": "full",
      "duration_seconds": 2340,
      "explicit": false,
      "audio": {
        "url": "https://cdn.example.com/podcast/ep052.mp3",
        "size_bytes": 37500000,
        "format": "mp3",
        "bitrate": 128
      },
      "artwork": {
        "url": "https://cdn.example.com/podcast/ep052_art.jpg"
      },
      "status": "published",
      "published_at": "2026-01-22T06:00:00Z",
      "downloads": 2450,
      "platforms": [
        {"platform": "spotify", "status": "live", "url": "https://..."},
        {"platform": "apple_podcasts", "status": "live", "url": "https://..."}
      ]
    }
  ],
  "total": 52
}

Create Episode

POST /api/v1/creator/podcast/shows/{show_id}/episodes

Request Body

{
  "title": "AI-Powered Menu Optimization",
  "description": "In this episode, we discuss how restaurants are using AI to optimize their menus for profitability and customer satisfaction.\n\n## Topics Covered\n- Menu engineering basics\n- AI price optimization\n- Customer preference analysis",
  "season": 2,
  "episode_number": 13,
  "episode_type": "full",
  "explicit": false,
  "publish_at": "2026-01-29T06:00:00Z",
  "chapters": [
    {"start_seconds": 0, "title": "Introduction"},
    {"start_seconds": 120, "title": "Menu Engineering Basics"},
    {"start_seconds": 900, "title": "AI Price Optimization"},
    {"start_seconds": 1800, "title": "Customer Insights"},
    {"start_seconds": 2400, "title": "Wrap-up"}
  ],
  "guests": [
    {
      "name": "Dr. Jane Smith",
      "title": "Menu Science Expert",
      "url": "https://twitter.com/drjanesmith"
    }
  ],
  "links": [
    {
      "title": "Menu Engineering Guide",
      "url": "https://example.com/resources/menu-engineering"
    }
  ],
  "transcript_enabled": true
}

Response

{
  "id": "ep_053",
  "status": "draft",
  "next_steps": [
    {
      "step": "upload_audio",
      "required": true
    }
  ],
  "created_at": "2026-01-24T19:30:00Z"
}

Episode Types

Type	Description
`full`	Regular full episode
`trailer`	Show trailer
`bonus`	Bonus content

Upload Episode Audio

POST /api/v1/creator/podcast/episodes/{episode_id}/audio

Request (multipart/form-data)

file: episode_053.mp3
options: {"normalize": true, "enhance": true}

Response

{
  "episode_id": "ep_053",
  "audio": {
    "status": "processing",
    "processing_steps": [
      {"step": "upload", "status": "complete"},
      {"step": "normalize", "status": "processing"},
      {"step": "enhance", "status": "pending"},
      {"step": "transcode", "status": "pending"}
    ],
    "estimated_completion": "2026-01-24T19:35:00Z"
  }
}

Get Episode

GET /api/v1/creator/podcast/episodes/{episode_id}

Update Episode

PUT /api/v1/creator/podcast/episodes/{episode_id}

Publish Episode

POST /api/v1/creator/podcast/episodes/{episode_id}/publish

Request Body

{
  "publish_now": false,
  "publish_at": "2026-01-29T06:00:00Z",
  "platforms": ["spotify", "apple_podcasts", "google_podcasts"]
}

Generate Transcript

POST /api/v1/creator/podcast/episodes/{episode_id}/transcript

Response

{
  "episode_id": "ep_053",
  "transcript": {
    "status": "processing",
    "estimated_completion": "2026-01-24T19:40:00Z"
  }
}

Get Transcript

GET /api/v1/creator/podcast/episodes/{episode_id}/transcript

Response

{
  "episode_id": "ep_053",
  "transcript": {
    "format": "srt",
    "segments": [
      {
        "start": 0.0,
        "end": 5.2,
        "speaker": "Host",
        "text": "Welcome to another episode of the AI Restaurant Podcast."
      },
      {
        "start": 5.5,
        "end": 12.8,
        "speaker": "Host",
        "text": "Today we're talking about AI-powered menu optimization."
      }
    ],
    "full_text": "Welcome to another episode of the AI Restaurant Podcast. Today we're talking about...",
    "word_count": 3500,
    "generated_at": "2026-01-24T19:40:00Z"
  }
}

Distribution

Get Distribution Status

GET /api/v1/creator/podcast/episodes/{episode_id}/distribution

Response

{
  "episode_id": "ep_052",
  "distribution": [
    {
      "platform": "spotify",
      "status": "live",
      "url": "https://open.spotify.com/episode/...",
      "distributed_at": "2026-01-22T06:05:00Z"
    },
    {
      "platform": "apple_podcasts",
      "status": "live",
      "url": "https://podcasts.apple.com/episode/...",
      "distributed_at": "2026-01-22T06:15:00Z"
    },
    {
      "platform": "google_podcasts",
      "status": "live",
      "url": "https://podcasts.google.com/episode/...",
      "distributed_at": "2026-01-22T06:20:00Z"
    },
    {
      "platform": "youtube",
      "status": "pending",
      "message": "Video rendering in progress"
    }
  ]
}

Submit to Directory

POST /api/v1/creator/podcast/shows/{show_id}/submit

Request Body

{
  "platform": "apple_podcasts",
  "category": "Business/Technology"
}

RSS Feed

Get RSS Feed

GET /api/v1/creator/podcast/shows/{show_id}/rss

Response

Returns RSS XML feed.

Customize RSS Feed

PUT /api/v1/creator/podcast/shows/{show_id}/rss/settings

Request Body

{
  "episodes_in_feed": 100,
  "include_full_description": true,
  "include_chapters": true,
  "include_transcript": true,
  "custom_namespace": {
    "prefix": "podcast",
    "uri": "https://example.com/podcast-ns"
  }
}

Analytics

Get Show Analytics

GET /api/v1/creator/podcast/shows/{show_id}/analytics

Query Parameters

Parameter	Type	Description
`start_date`	date	Period start
`end_date`	date	Period end
`granularity`	string	`day`, `week`, `month`

Response

{
  "show_id": "show_001",
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "summary": {
    "total_downloads": 45000,
    "unique_listeners": 12500,
    "avg_completion_rate": 0.72,
    "subscriber_growth": 850,
    "total_subscribers": 8500
  },
  "downloads_by_day": [
    {"date": "2026-01-22", "downloads": 2450},
    {"date": "2026-01-23", "downloads": 1850},
    {"date": "2026-01-24", "downloads": 980}
  ],
  "top_episodes": [
    {
      "episode_id": "ep_052",
      "title": "Voice AI in Drive-Thrus",
      "downloads": 2450,
      "completion_rate": 0.78
    }
  ],
  "audience": {
    "by_platform": [
      {"platform": "spotify", "percent": 45},
      {"platform": "apple_podcasts", "percent": 35},
      {"platform": "other", "percent": 20}
    ],
    "by_country": [
      {"country": "US", "percent": 65},
      {"country": "UK", "percent": 12},
      {"country": "CA", "percent": 8}
    ],
    "by_device": [
      {"device": "mobile", "percent": 68},
      {"device": "desktop", "percent": 22},
      {"device": "smart_speaker", "percent": 10}
    ]
  },
  "engagement": {
    "avg_listen_duration_minutes": 28,
    "skip_rate": 0.15,
    "replay_rate": 0.08
  }
}

Get Episode Analytics

GET /api/v1/creator/podcast/episodes/{episode_id}/analytics

Response

{
  "episode_id": "ep_052",
  "title": "Voice AI in Drive-Thrus",
  "summary": {
    "total_downloads": 2450,
    "unique_listeners": 1850,
    "avg_completion_rate": 0.78,
    "avg_listen_duration": 30.5
  },
  "retention": {
    "drop_off_points": [
      {"timestamp_seconds": 300, "retention": 0.92},
      {"timestamp_seconds": 600, "retention": 0.85},
      {"timestamp_seconds": 1200, "retention": 0.78},
      {"timestamp_seconds": 1800, "retention": 0.72},
      {"timestamp_seconds": 2340, "retention": 0.65}
    ],
    "chapters_engagement": [
      {"chapter": "Introduction", "completion": 0.95},
      {"chapter": "Main Discussion", "completion": 0.82},
      {"chapter": "Q&A", "completion": 0.68}
    ]
  },
  "downloads_timeline": [
    {"hour": 0, "downloads": 450},
    {"hour": 24, "downloads": 850},
    {"hour": 48, "downloads": 1200}
  ]
}

Monetization

Get Monetization Status

GET /api/v1/creator/podcast/shows/{show_id}/monetization

Response

{
  "show_id": "show_001",
  "monetization": {
    "enabled": true,
    "methods": [
      {
        "type": "dynamic_ads",
        "status": "active",
        "provider": "spotify_ads",
        "revenue_share": 0.70
      },
      {
        "type": "premium_subscription",
        "status": "active",
        "subscribers": 250,
        "monthly_revenue": 1250.00
      }
    ]
  },
  "earnings": {
    "this_month": 2850.00,
    "last_month": 2650.00,
    "ytd": 8500.00
  },
  "ad_inventory": {
    "pre_roll_available": true,
    "mid_roll_available": true,
    "post_roll_available": true
  }
}

Configure Ad Slots

PUT /api/v1/creator/podcast/shows/{show_id}/monetization/ads

Request Body

{
  "pre_roll": {
    "enabled": true,
    "max_duration_seconds": 30
  },
  "mid_roll": {
    "enabled": true,
    "positions": ["auto"],
    "max_per_episode": 2,
    "max_duration_seconds": 60
  },
  "post_roll": {
    "enabled": false
  }
}

Webhooks

Event	Description
`podcast.episode_published`	Episode published
`podcast.distribution_complete`	Distributed to platform
`podcast.download_milestone`	Download milestone reached
`podcast.review_received`	New review received
`podcast.transcript_ready`	Transcript generation complete

Error Responses

Status	Code	Description
400	`invalid_audio`	Audio format not supported
400	`artwork_invalid`	Artwork doesn't meet specs
404	`show_not_found`	Show ID not found
404	`episode_not_found`	Episode ID not found
409	`already_published`	Episode already published
422	`distribution_failed`	Platform distribution failed

Social Publishing API - Social distribution
Content Management - Content creation
Creator Guide - Platform overview

Overview​

Supported Platforms​

Shows​

List Shows​

Create Show​

Get Show​

Update Show​

Upload Artwork​

Episodes​

List Episodes​

Create Episode​

Episode Types​

Upload Episode Audio​

Get Episode​

Update Episode​

Publish Episode​

Generate Transcript​

Get Transcript​

Distribution​

Get Distribution Status​

Submit to Directory​

RSS Feed​

Get RSS Feed​

Customize RSS Feed​

Analytics​

Get Show Analytics​

Get Episode Analytics​

Monetization​

Get Monetization Status​

Configure Ad Slots​

Webhooks​

Error Responses​

Related Documentation​

Overview

Supported Platforms

Shows

List Shows

Create Show

Get Show

Update Show

Upload Artwork

Episodes

List Episodes

Create Episode

Episode Types

Upload Episode Audio

Get Episode

Update Episode

Publish Episode

Generate Transcript

Get Transcript

Distribution

Get Distribution Status

Submit to Directory

RSS Feed

Get RSS Feed

Customize RSS Feed

Analytics

Get Show Analytics

Get Episode Analytics

Monetization

Get Monetization Status

Configure Ad Slots

Webhooks

Error Responses

Related Documentation