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", "site_url": "https://websites.partner.com/show-1/"},
    {"partner_podcast_id": "show-2", "site_url": "https://websites.partner.com/show-2/"}
  ]
}

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",
  "website_url": "https://websites.partner.com/my-podcast/",
  "claimed": true,
  "plan": "free"
}

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. When the slug is updated successfully, the response includes the new slug and site_url.
• primary_color
• text_color
• background_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)

{
  "partner_podcast_id": "abc123",
  "status": "updated",
  "slug": "my-new-slug",
  "site_url": "https://websites.partner.com/my-new-slug/",
  "primary_color": "#112233",
  "text_color": null,
  "background_color": null,
  "dark_mode": true
}

slug and site_url are only included when the slug was actually changed. The four appearance fields are always returned.

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).

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", "site_url": "https://websites.partner.com/my-podcast/", "claimed": true},
    {"partner_podcast_id": "def456", "site_url": "https://websites.partner.com/other-show/", "claimed": false}
  ],
  "total": 42,
  "page": 1,
  "page_size": 50
}

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