Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.particle.pro/llms.txt

Use this file to discover all available pages before exploring further.

If you already have a corpus of podcasts identified by their Apple collection ID, Spotify show ID, YouTube channel ID, RSS feed URL, or any other platform-native identifier, the regular catalog endpoints aren’t the right tool to reconcile them with Particle’s catalog:
  • GET /v1/podcasts?q=… is a fuzzy name search. It can’t find a show whose title you’re spelling differently than we do — and there’s no guarantee the top hit is the right podcast even when names look similar.
  • GET /v1/podcasts/{id} only accepts our internal base62 ID or the Particle slug. It does not accept third-party IDs.
The lookup endpoint closes that gap. Send it a platform plus up to 100 platform-native identifiers, and it returns one record per input — each echoing the identifier you sent alongside the matched Particle podcast (or omitting the podcast key when the identifier doesn’t resolve). The same data lives in external links; this endpoint just reverses the index so you can query it that way. Use this endpoint when you want to:
  • Reconcile an existing corpus of podcasts (a CMS export, a chart scrape, a partner feed) with Particle’s catalog by Apple/Spotify/etc. IDs.
  • Map an iTunes ID a third-party feed gave you into our podcast.id before calling any other Particle endpoint.
  • Bulk-resolve a list of identifiers without losing the input → output correlation that a fuzzy filter on /v1/podcasts can’t give you.

​
Look up by Apple Podcasts ID

curl -G "https://api.particle.pro/v1/podcasts/lookup" \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  --data-urlencode "platform=apple" \
  --data-urlencode "identifier=1535809341,1200361736"
Response
{
  "results": [
    {
      "identifier": "1535809341",
      "podcast": {
        "id": "QpMz7GYKfSNuUa6zKXA4Q",
        "title": "All-In with Chamath, Jason, Sacks & Friedberg",
        "slug": "all-in-with-chamath-jason-sacks-friedberg",
        "image_url": "https://cdn.particle.pro/podcasts/all-in.jpg"
      }
    },
    {
      "identifier": "1200361736"
      // no `podcast` key — this Apple ID didn't resolve
    }
  ]
}
That’s the whole shape. Each result echoes the input identifier so you can join the response back to your input list by position or by key — your call. Unresolved identifiers omit the podcast field entirely; clients should test for key presence rather than a null value, matching the convention used elsewhere in the API for nullable nested resources.

​
Look up by RSS feed URL

The rss platform is the odd one out: it doesn’t live in external-links because every podcast already carries its own canonical feed URL on the podcast itself. Pass the URL exactly as it appears on the podcast’s RSS feed: 
curl -G "https://api.particle.pro/v1/podcasts/lookup" \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  --data-urlencode "platform=rss" \
  --data-urlencode "identifier=https://feeds.simplecast.com/54nAGcIl"
Comparison is byte-exact: a ?param suffix, a trailing slash, or http:// vs https:// will not match if our stored URL is the other form. If you don’t have the URL exactly as the publisher serves it, fall back to looking up by Apple/Spotify/YouTube ID instead — those are more forgiving to normalise.

​
Parameters

FieldDescription
platformRequired. Platform slug — any value from the external-links platform reference, plus two in-house aliases: itunes (treated as apple) and rss (match by canonical RSS feed URL — see Look up by RSS feed URL above).
identifierRequired. One or more platform-native identifiers, comma-separated. Up to 100 per call. Duplicates in your input are deduped silently — you’ll get one result per unique input.
A few details worth knowing up front:
  • Order is preserved. Results appear in the request order of their first occurrence. If you send ?identifier=A,B,A, you get two results — A then B — not three.
  • Exact matching only. Identifiers are compared exactly; case differences and prefix mismatches do not resolve. Leading and trailing whitespace is stripped automatically so a copy-pasted ID with stray spaces still works.
  • platform=bogus is a 400. Unknown platform slugs return an error listing every accepted slug — same vocabulary as the external-links responses.

​
Looking up the same podcast across platforms

The endpoint takes one platform at a time. To resolve a multi-platform corpus, fan out one call per platform — each call covers up to 100 identifiers and the responses are independent: 
# Apple
curl -G "https://api.particle.pro/v1/podcasts/lookup" \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  --data-urlencode "platform=apple" \
  --data-urlencode "identifier=1535809341"

# Spotify
curl -G "https://api.particle.pro/v1/podcasts/lookup" \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  --data-urlencode "platform=spotify" \
  --data-urlencode "identifier=5BiqcD1FSCwlgZTcljpAYi"

# YouTube
curl -G "https://api.particle.pro/v1/podcasts/lookup" \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  --data-urlencode "platform=youtube" \
  --data-urlencode "identifier=UCESLZhusAkFfsNsApnjF_Cg"

# RSS feed URL (matches against the canonical podcast feed URL)
curl -G "https://api.particle.pro/v1/podcasts/lookup" \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  --data-urlencode "platform=rss" \
  --data-urlencode "identifier=https://feeds.simplecast.com/54nAGcIl"
Once you have the resolved podcast.id for each input, hit GET /v1/podcasts/{id}/external-links to see every other platform that podcast also lives on. That’s the natural follow-up when you want to enrich rather than reconcile.

​
Behavior and edge cases

​
Apple Podcasts and iTunes share IDs

Apple Podcasts uses a single numeric collection ID across both its modern and iTunes-era surfaces. The lookup endpoint reflects that: platform=apple and platform=itunes are aliases. Both consult the legacy podcasts.itunes_id column on our podcasts table and the generic external_links reverse index, so either query form will find a match if we have one in either place.

​
Misses omit the podcast field

Unmatched identifiers come back as {"identifier": "…"} with no podcast key. This is intentional — OpenAPI clients now see an accurate schema where podcast is optional, and absence is a single sentinel for “no match” without the ambiguity of explicit null. 
// Matched
{ "identifier": "1535809341", "podcast": { "id": "…", "title": "…", "slug": "…", "image_url": "…" } }

// Unmatched
{ "identifier": "9999999999" }

​
Duplicates collapse

If your input list contains duplicates, the response contains one entry per unique identifier — in the order each one first appeared. We do this silently rather than echoing duplicates back, so your client doesn’t have to dedupe twice.

​
Compact response only

The matched podcast is returned in the compact shape (id, title, slug, image_url) — enough to pivot to any other endpoint, but without the fuller metadata that GET /v1/podcasts/{id} returns. For each identifier you actually care about, follow up with the detail endpoint using the returned id (or slug).

​
Ambiguous identifiers resolve to the highest-charting podcast

A few platform identifiers in the wild are claimed by more than one podcast — most often when a publisher exposes the same YouTube channel as the video presence for several shows (e.g. the parent New York Times YouTube channel is listed under The Daily, Serial, The Headlines, Matter of Opinion, The Book Review, and others). When that happens, the lookup returns the podcast with the highest current Apple Podcasts / Spotify chart ranking, so the same input always resolves to the same output across calls. If you need to find every podcast a shared identifier belongs to, that’s an external-links question, not a lookup one — start from each candidate podcast and inspect its external-link rows.

​
100-identifier cap

Calls with more than 100 identifiers are rejected with a 400. The cap is generous enough that most reconciliations fit in a single round-trip; if you need more, fan out in chunks of 100. (The cap is per platform — you can do multiple platform calls in parallel.)

​
Choosing the right endpoint

You want to…Use this
Resolve a known Apple / Spotify / YouTube / … ID to a Particle podcastGET /v1/podcasts/lookup (this page)
Resolve a RSS feed URL to a Particle podcastGET /v1/podcasts/lookup?platform=rss (this page)
Search by podcast name (fuzzy text match)GET /v1/podcasts?q=…
Get the full podcast detail object (publisher, language, episode count, bias, suitability tier)GET /v1/podcasts/{id}
Enumerate every platform a Particle podcast lives onGET /v1/podcasts/{id}/external-links
Search dialogue inside episodes (not podcasts)GET /v1/podcasts/search
  • External links — the forward index; given a Particle podcast, list every third-party platform identifier we have for it. This endpoint is the reverse.
  • Podcasts overview — full Podcast object and all sub-resources.
  • Concepts — pagination, pricing weights, and authentication.