Request a podcast we don't index

Asks us to index a show: pass its Apple Podcasts, Spotify or YouTube link, or its RSS feed URL. Free. Returns 202 with a new request in state requested. Returns 200 when you have asked for the show before (your existing request), or when we already index it (no request is created; podcast names the show). Within a minute or two, automatic screening decides an English-language show from Apple Podcasts or an RSS feed: it is added (state indexed, with the podcast; its last two weeks of episodes arrive over the following hours) or rejected (state rejected, with a reason) when it is content we do not index, such as audiobooks, guided meditation, children’s story time, language lessons or machine-generated shows. A show screening cannot decide, such as a Spotify or YouTube link or a show not in English, goes to our team (state in_review). Poll GET /v1/podcasts/requests/ for the outcome. Organizations asking for the same show share one request. An organization may request 50 new shows in any 24 hours; past that, 429 rate_limit_exceeded with Retry-After and the time you can request more. 422 when the value is not a show link. A retry is safe without an Idempotency-Key: asking again for a show returns your existing request and does not count toward the limit.

POST /v1/podcasts/requests

cURL

cURL

curl -X POST \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://podcasts.apple.com/us/podcast/hard-fork/id1528594034"
}' \
  "https://api.particle.pro/v1/podcasts/requests"

200

{
  "platform": "apple",
  "platform_id": "<string>",
  "state": "requested",
  "url": "<string>",
  "detail": "<string>",
  "id": "<string>",
  "indexed_at": "2023-11-07T05:31:56Z",
  "podcast": {
    "id": "<string>",
    "title": "<string>",
    "best_rank": {
      "captured_at": "2023-11-07T05:31:56Z",
      "chart_type": "top_podcasts",
      "rank": 123,
      "source": "apple",
      "category_slug": "<string>",
      "country": "<string>"
    },
    "image_url": "<string>",
    "popularity": 123,
    "publisher": {
      "id": "<string>",
      "name": "<string>",
      "slug": "<string>"
    },
    "slug": "<string>"
  },
  "reason": "<string>",
  "requested_at": "2023-11-07T05:31:56Z",
  "title": "<string>"
}

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

Pass your API key in the X-API-Key header (recommended).

Body

application/json

url · string · required

A link to the show: its Apple Podcasts, Spotify or YouTube page (an Apple episode link names its show too), a spotify:show: URI, or its RSS feed URL.

Required string length: 1 - 2048

Response

200

application/json

Nothing new to request: your existing request for the show, or the show we already index.

platform · enum<string> · required

Where the link points: an Apple Podcasts, Spotify or YouTube show, or (rss) any other URL, taken as the show's feed.

Available options: apple, spotify, youtube, rss

platform_id · string · required

The show's identifier on that platform: the Apple Podcasts id, Spotify show id, YouTube channel id or handle, or the feed URL.

state · enum<string> · required

requested: waiting for automatic screening, which usually takes a minute or two. in_review: the show did not qualify for automatic screening (no RSS feed in the link, not in English, ...) and our team will add or reject it; reason says why. indexed: the show is in the catalogue; podcast names it. rejected: we will not index it; reason says why.

Available options: requested, in_review, indexed, rejected

url · string · required

The show link as you sent it.

detail · string

The reason in a sentence, for people.

id · string

The request's ID, for GET /v1/podcasts/requests/{id}. Organizations asking for the same show share it. Absent when no request was needed because we already index the show: podcast is then set.

indexed_at · string<date-time>

When the show was indexed.

podcast · object

The show, once it is indexed. Its slug works with every podcast endpoint.

Show child attributes

reason · string

Why a request is in review or rejected, as a stable code. In review: no_feed, not_english, not_found_in_podcast_index, dead_feed, previously_removed, podcast_guid_collision, ai_generated_suspected, screening_failed, radio_rebroadcast, content_type_uncertain. Rejected: audiobook, guided_audio, non_speech_ambient, subliminal, language_instruction, kids_story, sermon_worship, low_value_publisher, ai_generated, content_farm, syndication_spam, brand_impersonation, removed.

requested_at · string<date-time>

When you asked for the show.

title · string

The show's title, when we can read it from the link before indexing it.