Partner API documentation

Authentication

All requests require an Authorization: Bearer <api_key> header. Your API key is provided during partner onboarding.

All partner APIs are strictly scoped to the authenticated partner. A partner can only read/update/create data for podcasts whose partner matches the authenticated partner key.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  ...

Bulk create sites

Creates up to 50 podcast websites in a single request. Each item uses the same fields as Create site. Results are returned per-item; individual failures do not block other items.

Required fields

• sites — An array of site objects (max 50), each containing rss_feed_url and partner_podcast_id plus any optional fields from Create site

Example request

curl -X POST https://www.podpage.com/api/partners/create/bulk/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sites": [{"rss_feed_url": "https://example.com/feed1.xml", "partner_podcast_id": "show-1"}, {"rss_feed_url": "https://example.com/feed2.xml", "partner_podcast_id": "show-2"}]}'

Example response (200)

{
  "results": [
    {"partner_podcast_id": "show-1", "slug": "show-1", "website_url": "https://websites.partner.com/show-1/", "rss_feed_url": "https://example.com/feed1.xml", "claimed": false, "plan": "free", "primary_color": null, "dark_mode": false},
    {"partner_podcast_id": "show-2", "slug": "show-2", "website_url": "https://websites.partner.com/show-2/", "rss_feed_url": "https://example.com/feed2.xml", "claimed": false, "plan": "free", "primary_color": null, "dark_mode": false}
  ]
}

Errors: 400 (invalid JSON, empty or oversized array), 401 (invalid API key), 429 (rate limit). Per-item errors appear inline in the results array.

Site detail

Fetches the current partner site summary for one podcast.

Path params

• partner_podcast_id

Example request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.podpage.com/api/partners/sites/abc123/

Response (200)

{
  "partner_podcast_id": "abc123",
  "slug": "my-podcast",
  "website_url": "https://websites.partner.com/my-podcast/",
  "rss_feed_url": "https://feeds.example.com/my-podcast",
  "claimed": true,
  "plan": "free",
  "primary_color": "#112233",
  "dark_mode": true
}

Errors: 401 (invalid API key), 404 (no matching site).

Update site

If a user wants to fully customize their website, they should go through the claim process. However, if they just want to make some simple changes, we provide a limited update endpoint.

Path params

• partner_podcast_id (string) — Your podcast ID in your system. Always send as a string. Lookups are case-insensitive.

Optional fields

• slug — New website slug. Maximum 128 characters; we recommend keeping slugs under 20 characters. The value is lowercased and special characters are replaced with hyphens. Reserved slugs (for example: episodes, blog, about) are rejected. No profanity filter is applied. Must be unique across all Podpage sites. If the slug is already taken, the API returns a 409 error with "field": "slug" instead of silently renaming.
• primary_color
• dark_mode — true/false

Example request

curl -X POST https://www.podpage.com/api/partners/sites/abc123/update/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-new-slug", "primary_color": "#112233", "dark_mode": true}'

Example response (200)

{
  "status": "updated",
  "partner_podcast_id": "abc123",
  "slug": "my-new-slug",
  "website_url": "https://websites.partner.com/my-new-slug/",
  "rss_feed_url": "https://feeds.example.com/my-podcast",
  "claimed": true,
  "plan": "free",
  "primary_color": "#112233",
  "dark_mode": true
}

Response always includes the full canonical site object plus "status": "updated", regardless of which fields you sent.

Slug errors

• 400 — "Slug cannot be empty."
• 400 — "The slug '...' is reserved and cannot be used." (e.g. episodes, blog, about)
• 409 — "The slug '...' is already taken."

All slug errors include "field": "slug" in the JSON response.

Errors: 400 (missing fields/invalid payload/reserved slug), 401 (invalid API key), 404 (no matching site), 409 (slug already taken), 429 (rate limit).

Reset site

Wipes and re-imports a site from its RSS feed. All episodes are deleted, the podcast name and description are replaced with the current values from the feed, and a full episode re-sync is queued immediately. Use this when a feed has been rebuilt on your side (for example after a migration or a GUID rewrite) and the site should be brought back in line with it.

Unclaimed sites only. Once a user has claimed a site, their episodes and settings belong to them, so the API returns a 409 for claimed sites. Users who need to re-import episodes on a claimed site can do it themselves in the Podpage dashboard under Episodes → All Episodes → Troubleshoot.

Path params

• partner_podcast_id

Example request

curl -X POST https://www.podpage.com/api/partners/sites/abc123/reset/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response (200)

{
  "status": "reset",
  "episodes_deleted": 42,
  "sync_queued": true,
  "partner_podcast_id": "abc123",
  "slug": "my-podcast",
  "website_url": "https://websites.partner.com/my-podcast/",
  "rss_feed_url": "https://feeds.example.com/my-podcast",
  "claimed": false,
  "plan": "free",
  "primary_color": "#112233",
  "dark_mode": true
}

sync_queued is false when an episode sync for this site is already queued or running; episodes will still be re-imported by that sync or the next scheduled one. Episodes re-import in the background, so the site may show no episodes for a short time after the reset.

Errors: 400 (no RSS feed on the site, or the feed could not be parsed — nothing is deleted in that case), 401 (invalid API key), 404 (no matching site), 409 (site is claimed), 429 (rate limit).

Detach site

Removes the partner association from a site. Unclaimed sites are deleted immediately. Claimed sites are unlinked from the partner and remain in place.

Claimed users receive an email explaining that their partnership has ended and that they can still manage the site by signing in to Podpage.

Path params

• partner_podcast_id

Example request

curl -X POST https://www.podpage.com/api/partners/sites/abc123/detach/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response (200)

{"partner_podcast_id": "abc123", "status": "detached", "action": "unlinked"}

Errors: 401 (invalid API key), 404 (no matching site for this partner), 429 (rate limit).

List all sites

Returns a paginated list of all sites belonging to the requesting partner.

Query params

• page — Page number (default: 1)
• page_size — Results per page, 1–100 (default: 50)

Example request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.podpage.com/api/partners/sites/list/?page=1&page_size=50"

Example response (200)

{
  "sites": [
    {"partner_podcast_id": "abc123", "slug": "my-podcast", "website_url": "https://websites.partner.com/my-podcast/", "rss_feed_url": "https://feeds.example.com/my-podcast", "claimed": true, "plan": "free", "primary_color": "#112233", "dark_mode": true},
    {"partner_podcast_id": "def456", "slug": "other-show", "website_url": "https://websites.partner.com/other-show/", "rss_feed_url": "https://feeds.example.com/other-show", "claimed": false, "plan": "free", "primary_color": null, "dark_mode": false}
  ],
  "total": 42,
  "page": 1,
  "page_size": 50
}

Errors: 401 (invalid API key), 429 (rate limit).