Setup Wizard REST API

Endpoints used by the setup wizard and migration-related screens. Covers wizard step progression, episode import, migration redirect settings, and Patreon shadow subscriber visibility. All endpoints require manage_options and a valid X-WP-Nonce header unless noted otherwise.

---

Wizard Progression

POST /benecaster/v1/wizard/steps/{id}/complete

Marks a wizard step as complete and records any step-specific data. {id} is the step identifier string (e.g. bridge, tier-mapping, episode-import).

Body: Step-specific data as a JSON object. The accepted fields depend on the step; the wizard UI sends only the relevant fields for each step. Pass an empty object {} for steps with no data to record.

Response:

{
  "step_id": "bridge",
  "completed": true,
  "next_step": "tier-mapping"
}

Errors:

Step definitions are filterable via benecaster_setup_wizard_steps — add-ons can inject additional steps.

---

POST /benecaster/v1/wizard/complete

Marks the entire wizard as complete and fires the benecaster_setup_wizard_completed action.

Body: Empty — no body required.

Response:

{
  "completed": true,
  "show_id": 45
}

show_id is the primary show created or configured during the wizard. Used by the post-wizard redirect to the dashboard.

Errors:

---

Episode Import

POST /benecaster/v1/shows/{id}/import

One-time bulk import of all episodes from a source RSS feed. Distinct from the recurring feed sync — this imports everything, not just new items. Typically used during setup to bring existing episodes from a previous podcast host.

Body:

{
  "source_feed_url": "https://feeds.buzzsprout.com/12345.rss",
  "skip_existing": true
}

skip_existing: true (default) skips episodes whose GUID already exists in WordPress. Set false to force re-import of all episodes — this creates duplicates and should only be used on empty shows.

Response:

{
  "total_in_feed": 84,
  "skipped_existing": 68,
  "drafts_created": 16,
  "draft_ids": [201, 202, 203],
  "log_id": 48
}

For large feeds (50+ episodes), this endpoint may take 10–30 seconds. It is synchronous — it completes before returning.

Errors:

---

GET /benecaster/v1/shows/{id}/import

Returns the last import log for a show.

Response:

{
  "log_id": 48,
  "source_feed_url": "https://feeds.buzzsprout.com/12345.rss",
  "total_in_feed": 84,
  "skipped_existing": 68,
  "drafts_created": 16,
  "status": "complete",
  "started_at": "2026-05-17T09:00:00",
  "completed_at": "2026-05-17T09:00:28"
}

Returns 404 when no import log exists for the show.

---

Migration / Redirect Settings

PUT /benecaster/v1/shows/{id}/migration

Update migration and redirect settings for a show. Used by the setup wizard’s Migration step and the Show Settings → Migration tab.

Body:

{
  "redirect_from_url": "https://feeds.buzzsprout.com/12345.rss",
  "new_feed_url": null,
  "redirect_expires": "2026-08-17"
}

All fields are optional — only provided fields are updated.

Response: Updated show object with migration fields.

Errors:

---

Shadow Subscriber Visibility (Patreon Import)

These endpoints manage the “visibility” scorecard — a platform’s patron or subscriber list uploaded for comparison with Benecaster subscribers before a migration decision.

GET /benecaster/v1/shows/{id}/visibility

Returns the current shadow subscriber state for a show — one entry per uploaded platform.

Response:

{
  "items": [
    {
      "platform": "patreon",
      "patron_count": 89,
      "uploaded_at": "2026-04-17T09:00:00",
      "expires_at": "2026-07-16T09:00:00",
      "expired": false
    }
  ]
}

Errors:

---

POST /benecaster/v1/shows/{id}/visibility/csv

Upload a patron export CSV to populate the shadow subscriber scorecard.

Body: multipart/form-data with a file field containing the CSV.

Response:

{
  "platform": "patreon",
  "patrons_imported": 89,
  "patrons_already_subscribed": 12,
  "expires_at": "2026-07-16T09:00:00"
}

The platform (e.g. patreon) is auto-detected from the CSV structure. Re-uploading for the same platform resets the uploaded_at and expires_at clocks and replaces all previous records.

Errors:

---

POST /benecaster/v1/shows/{id}/visibility/count

Register a manual patron count without uploading a CSV. For platforms that don’t support CSV export or when only an aggregate number is available.

Body:

{
  "platform": "patreon",
  "count": 47
}

Response:

{
  "platform": "patreon",
  "patron_count": 47,
  "uploaded_at": "2026-05-17T09:00:00",
  "expires_at": "2026-08-15T09:00:00"
}

Manual count entries are not deduplicable (no individual records) and expire at the same 90-day schedule as CSV uploads.

---

DELETE /benecaster/v1/shows/{id}/visibility/{platform}

Removes all shadow subscriber data for a specific platform from a show. Equivalent to the “Clear” button in the Settings → Visibility UI.

Response: 204 No Content

Errors: