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.

A publisher is the organization that produces and distributes a podcast — Goalhanger, iHeartPodcasts, BBC Radio 4, Wondery, NPR. The publisher endpoints let you browse the full set of publishers in the catalog, look one up by a stable slug, and pivot from a publisher to every podcast attributed to it. The same publisher record also appears embedded as a publisher object on the podcast detail response (GET /v1/podcasts/{id}), so you usually don’t need a separate lookup to display a podcast’s publisher — these endpoints exist for browsing and reverse navigation. Use these endpoints when you want to:
  • Build a “browse by publisher” view of the catalog.
  • Resolve a publisher slug from a URL into its podcasts.
  • Rank publishers by catalog size, or list them alphabetically.
  • Cross-reference a podcast’s publisher with the rest of its catalog.

​
Identifying a publisher

Every publisher endpoint that takes an {id} path parameter accepts either form:
  • Slug (recommended): a stable, human-readable identifier — goalhanger, iheartpodcasts, bbc-radio-4. Slugs are populated for the vast majority of publishers and returned on every publisher response.
  • ID: the base62-encoded publisher ID. Always works as a fallback for the small number of publishers whose name doesn’t slugify (e.g. names that aren’t representable as ASCII URL slugs).
Slugs and IDs are interchangeable in the URL — pick whichever you have.

​
List publishers

curl "https://api.particle.pro/v1/podcasts/publishers?sort=podcast_count&limit=10" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    {
      "id": "0RZ7y1ABC",
      "slug": "iheartpodcasts",
      "name": "iHeartPodcasts",
      "podcast_count": 612
    },
    {
      "id": "0RZ7y1DEF",
      "slug": "wondery",
      "name": "Wondery",
      "podcast_count": 184
    },
    {
      "id": "0RZ7y1GHI",
      "slug": "bbc-radio-4",
      "name": "BBC Radio 4",
      "podcast_count": 142
    }
    // …
  ],
  "has_more": true,
  "cursor": "eyJvIjoxMH0="
}

​
Query parameters

ParameterDefaultDescription
sortpodcast_countpodcast_count ranks publishers by catalog size, largest first. name sorts alphabetically.
limit25Page size, 1–100.
cursor—Opaque cursor from the previous response’s cursor field.

​
Get a publisher

curl "https://api.particle.pro/v1/podcasts/publishers/goalhanger" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response
{
  "id": "0RZ7y1XYZ",
  "slug": "goalhanger",
  "name": "Goalhanger",
  "podcast_count": 14
}
Returns 404 when no publisher matches the supplied slug or ID.

​
List podcasts for a publisher

Pivot from a publisher to its full catalog, ordered by popularity: 
curl "https://api.particle.pro/v1/podcasts/publishers/goalhanger/podcasts?limit=5" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    {
      "id": "0RZ7y1AAA",
      "slug": "the-rest-is-history",
      "title": "The Rest Is History",
      "language": "en",
      // …other Podcast fields
    },
    {
      "id": "0RZ7y1BBB",
      "slug": "the-rest-is-politics",
      "title": "The Rest Is Politics",
      "language": "en"
      // …
    }
    // …
  ],
  "has_more": false
}
Returns 404 when no publisher matches the supplied slug or ID. The response contains the same Podcast objects returned by GET /v1/podcasts — see the podcasts overview for the full field reference.

​
Anatomy of a publisher

FieldDescription
idStable base62-encoded publisher identifier. Always present.
slugHuman-readable identifier. Recommended in URLs. Omitted on publishers whose name doesn’t slugify.
namePublisher’s display name.
podcast_countNumber of podcasts in the catalog attributed to this publisher.
The same publisher also appears in compact form (id, slug, name only) as the publisher field on the podcast detail response — you do not need a separate publisher lookup just to display a podcast’s publisher in the UI.

​
Choosing the right endpoint

You want to…Use this
Browse all publishers, ranked by catalog sizeGET /v1/podcasts/publishers?sort=podcast_count
Browse all publishers alphabeticallyGET /v1/podcasts/publishers?sort=name
Resolve a publisher slug from a URLGET /v1/podcasts/publishers/{slug}
List every podcast a publisher producesGET /v1/podcasts/publishers/{id}/podcasts
Get the publisher of a specific podcastThe publisher field on GET /v1/podcasts/{id}
  • Podcasts overview — full Podcast object and other sub-resources.
  • Episodes — drill from a podcast into its individual episodes.
  • External links — third-party platform presences for a podcast.