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.
A podcast lives in many places: it’s on Apple Podcasts and Spotify, the host posts to X, the publisher runs a YouTube channel, and there’s a marketing site on its own domain. The external-links endpoint returns every one of those presences in a single, normalized shape — with the platform-native identifier, a ready-to-use web URL, and a list of optional per-platform attributes (subscribers, followers, handle, etc.).
Use this endpoint when you want to:
- Build a “follow this podcast on…” UI without hard-coding per-platform URL templates.
- Compare audience size across platforms (Spotify followers vs. YouTube subscribers vs. Castbox subscribers).
- Pull the publisher’s website and social handles for outreach or research.
- Reconcile a podcast across third-party catalogs (Apple ID ↔ Spotify show ID ↔ Podchaser ID).
List external links for a podcast
curl "https://api.particle.pro/v1/podcasts/hard-fork/external-links" \
-H "X-API-Key: $PARTICLE_API_KEY"
hard-fork, all-in) or a base62-encoded podcast ID — same as every other podcast sub-resource.
{
"data": [
{
"platform": {
"name": "apple",
"display_name": "Apple Podcasts",
"type": "podcast_directory"
},
"identifier": "1528594034",
"url": "https://podcasts.apple.com/podcast/id1528594034"
},
{
"platform": {
"name": "spotify",
"display_name": "Spotify",
"type": "music_service"
},
"identifier": "44fllCS2FTFr2x2kjP9xeT",
"url": "https://open.spotify.com/show/44fllCS2FTFr2x2kjP9xeT",
"attributes": [
{
"name": "followers",
"category": "audience_size",
"value": 3902,
"observed_at": "2026-04-22T11:00:00Z"
}
]
},
{
"platform": {
"name": "youtube",
"display_name": "YouTube",
"type": "video_channel"
},
"identifier": "UCZcR2SVWaGWNlMqPxvQS3vw",
"url": "https://www.youtube.com/channel/UCZcR2SVWaGWNlMqPxvQS3vw",
"attributes": [
{ "name": "handle", "category": "profile", "value": "hardfork" },
{ "name": "subscribers", "category": "audience_size", "value": 245000 },
{ "name": "videos", "category": "content", "value": 200 },
{ "name": "views", "category": "audience_size", "value": 12345678 }
]
},
{
"platform": { "name": "tiktok", "display_name": "TikTok", "type": "social_profile" },
"identifier": "hardfork",
"url": "https://www.tiktok.com/@hardfork"
},
{
"platform": { "name": "twitter", "display_name": "X (Twitter)", "type": "social_profile" },
"identifier": "HardFork",
"url": "https://twitter.com/HardFork"
},
{
"platform": { "name": "website", "display_name": "Website", "type": "website" },
"url": "https://www.nytimes.com/column/hard-fork"
}
// …
],
"has_more": false
}
?limit= and ?cursor= if you specifically want to page through results.
Anatomy of an entry
Every entry has the same shape regardless of platform. Optional fields are omitted when no data is available.
| Field | Description |
|---|
platform.name | Stable machine name (e.g. spotify, youtube). Suitable for filtering, routing, or persistence. |
platform.display_name | Human-readable name suitable for UI display (Apple Podcasts, X (Twitter)). |
platform.type | Broad category. Use this to group presences in a UI rather than enumerating every name. |
identifier | Platform-native value (numeric id, slug, handle, or URL). Omitted entirely for the website platform — the JSON key is absent, not an empty string. |
url | Canonical web URL for this presence. Built from a per-platform template, or passed through for website. |
attributes | Optional per-platform metadata (audience size, profile fields, etc.). May be absent or empty. |
platform.type lets clients render related platforms with a shared treatment without knowing the full list of names:
| Type | What it covers |
|---|
podcast_directory | Apple Podcasts, Spotify-as-podcast-directory replicas, Castbox, Podchaser, Player FM, Podcast Addict, Podbean, Podcast Republic, Goodpods, The Podcast App, TuneIn, iHeartRadio. |
music_service | Spotify, Apple Music–adjacent stores, Audible, Amazon Music — services whose primary brand is audio playback. |
social_profile | X (Twitter), Instagram, Threads, TikTok, Facebook, LinkedIn — handle-based identity. |
video_channel | YouTube channel for the podcast (and any future video-first platforms). |
community | Reddit, Discord, Patreon — where listeners gather around the show. |
website | The publisher’s own marketing site for the podcast. The identifier is omitted; url carries the destination. |
other | Reserved for future platforms that don’t fit the above. Treat as opaque. |
Attributes
Each entry’s attributes is a list of typed records. The set of attribute names that may appear varies per platform — and grows over time as upstream sources expose richer metadata. Clients should treat unknown attribute names additively rather than enumerating them.
| Field | Description |
|---|
name | Platform-native attribute name (subscribers, followers, handle, etc.). |
category | Broad grouping. Use this to render unfamiliar attributes without recognising the exact name. |
value | The attribute value. JSON type matches the category — numbers for audience/content tallies, strings for profile/account fields, booleans for flags. |
observed_at | ISO 8601 timestamp of when the attribute was last observed from the upstream source. Omitted when unavailable. |
Attribute categories
| Category | Typical names | Value type |
|---|
audience_size | subscribers, followers, views | integer |
content | videos | integer |
profile | handle, display_name, thumbnail_url, founded | string (or RFC 3339 timestamp for founded) |
account_status | verified (forthcoming) | boolean |
url field. New platforms may be added without notice; existing platform names are stable.
name | display_name | type | URL pattern |
|---|
amazon_music | Amazon Music | music_service | https://music.amazon.com/podcasts/{id} |
apple | Apple Podcasts | podcast_directory | https://podcasts.apple.com/podcast/id{id} |
audible | Audible | music_service | https://www.audible.com/pd/{id} |
castbox | Castbox | podcast_directory | https://castbox.fm/channel/id{id} |
discord | Discord | community | https://discord.gg/{id} |
facebook | Facebook | social_profile | https://www.facebook.com/{id} |
goodpods | Goodpods | podcast_directory | https://www.goodpods.com/podcasts/{id} |
iheartradio | iHeartRadio | podcast_directory | https://www.iheart.com/podcast/{id}/ |
instagram | Instagram | social_profile | https://www.instagram.com/{id}/ |
itunes | iTunes | podcast_directory | https://podcasts.apple.com/podcast/id{id} |
linkedin | LinkedIn | social_profile | https://www.linkedin.com/company/{id}/ |
patreon | Patreon | community | https://www.patreon.com/{id} |
playerfm | Player FM | podcast_directory | https://player.fm/series/{id} |
podaddict | Podcast Addict | podcast_directory | https://podcastaddict.com/podcast/{id} |
podbean | Podbean | podcast_directory | https://www.podbean.com/podcast-detail/{id} |
podchaser | Podchaser | podcast_directory | https://www.podchaser.com/podcasts/{id} |
podrepublic | Podcast Republic | podcast_directory | https://www.podcastrepublic.net/podcast/{id} |
reddit | Reddit | community | https://www.reddit.com/r/{id}/ |
spotify | Spotify | music_service | https://open.spotify.com/show/{id} |
threads | Threads | social_profile | https://www.threads.net/@{id} |
tiktok | TikTok | social_profile | https://www.tiktok.com/@{id} |
tpa | The Podcast App | podcast_directory | https://thepodcastapp.com/p/{id} |
tunein | TuneIn | podcast_directory | https://tunein.com/podcasts/{id}/ |
twitter | X (Twitter) | social_profile | https://twitter.com/{id} |
website | Website | website | URL only; no separate identifier field |
youtube | YouTube | video_channel | https://www.youtube.com/channel/{id} for channel-ID identifiers (UC + 22 chars), https://www.youtube.com/@{id} for handle identifiers |
YouTube: richer attributes
YouTube is currently the most heavily-enriched platform. A YouTube entry can carry up to four attributes today:
{
"platform": { "name": "youtube", "display_name": "YouTube", "type": "video_channel" },
"identifier": "UCZcR2SVWaGWNlMqPxvQS3vw",
"url": "https://www.youtube.com/channel/UCZcR2SVWaGWNlMqPxvQS3vw",
"attributes": [
{ "name": "handle", "category": "profile", "value": "hardfork" },
{ "name": "subscribers", "category": "audience_size", "value": 245000 },
{ "name": "videos", "category": "content", "value": 200 },
{ "name": "views", "category": "audience_size", "value": 12345678 }
]
}
display_name, thumbnail_url, and founded attributes may also appear when known.
Notes and gotchas
apple and itunes are usually duplicates
Apple Podcasts uses a single numeric ID across both its modern and iTunes-era surfaces. Most podcasts therefore have two entries — apple and itunes — with the same identifier and the same resolved url. This faithfully reflects what upstream catalog sources report; clients that want a single Apple entry can de-duplicate by (type, identifier).
Attributes are forward-compatible
Both attributes[].name and attributes[].category are open enumerations. New names (e.g. a future engagement_rate for Instagram) and new categories will be added without a versioning event. Always render unknown attributes additively — match on category for grouping when the name isn’t recognized.
observed_at is best-effort
Some attributes don’t have a known observation timestamp; the field is then omitted. When present, the timestamp reflects the last time the value was refreshed from the upstream source — not the last time the podcast itself was updated.
The identifier is whatever the platform natively uses. Examples:
| Platform | Sample identifier | Shape |
|---|
apple / itunes | 1528594034 | Numeric Apple Podcasts ID |
spotify | 44fllCS2FTFr2x2kjP9xeT | Spotify show ID |
youtube | UCZcR2SVWaGWNlMqPxvQS3vw | Channel ID (or short handle for some podcasts) |
twitter / tiktok | HardFork / hardfork | Account handle (no @) |
podbean | dir2423160,nrwgx | Podbean-internal pair (don’t try to parse) |
website platform is the exception: there’s no separate identifier — the entry omits identifier entirely and only carries url.
If you need a clickable link, prefer the resolved url over building one yourself; URL templates change.
Choosing the right endpoint
| You want to… | Use this |
|---|
| Show a “find this podcast on …” list of platforms | external-links |
| Compare audience size (followers / subscribers) across platforms | external-links (filter by attributes[].category=audience_size) |
| Get the podcast’s own metadata (title, publisher, description, RSS feed, episode counts) | GET /v1/podcasts/{id} |
| List episodes for a podcast | GET /v1/podcasts/{id}/episodes |
| Sponsor / advertising profile | GET /v1/podcasts/{id}/advertising |
| Political bias analysis | GET /v1/podcasts/{id}/bias |
