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.

The per-podcast brand suitability assessment is the unit of measurement; the publisher rollups described here are the unit of decision. Advertisers don’t buy a single show — they buy across a publisher’s catalog. A buying decision needs a per-publisher composition view, a way to rank publishers against each other, and a way to pivot on the categories that matter for a specific brand. These endpoints expose four views over the same underlying assessments:
  1. GET /v1/podcasts/publishers/{id}/suitability — the composite profile for one publisher. Tier composition, per-category exposure, top concerns. The headline endpoint.
  2. GET /v1/podcasts/publishers/{id}/suitability/podcasts — drill down into a publisher to see which specific podcasts are concerning, filterable by tier, category, prevalence, and treatment.
  3. GET /v1/podcasts/suitability/publishers/leaderboard — cross-publisher ranking by safest, riskiest, most-placeable, or most-analyzed.
  4. GET /v1/podcasts/suitability/categories/{code}/publishers — pivot on a single GARM category and rank publishers by exposure. The killer view for regulated brands (alcohol, gambling, cannabis, family).
Per-podcast endpoints — GET /v1/podcasts/{id}/suitability and the embedded suitability_tier on GET /v1/podcasts/{id} — remain the source of truth for an individual show. The publisher endpoints aggregate from those same assessments.

​
Coverage caveat

Suitability analyses are still being backfilled across the catalog. At time of writing, ~10% of the catalog has been assessed, biased toward more popular shows. Every aggregate response surfaces a coverage.analyzed_coverage (0..1 share) and a coverage.quality enum (LOW < 0.3, MEDIUM 0.3–0.7, HIGH ≥ 0.7) so callers can weight the rollup against the underlying sample. Cross-publisher rankings additionally accept a min_analyzed_podcasts parameter (default 5) so a publisher with one or two analyzed shows cannot dominate share-based rankings.

​
Identifying a publisher

The publisher-scoped endpoints (/v1/podcasts/publishers/{id}/...) accept the same publisher identifier as the rest of the publisher endpoints: a slug (recommended — iheartpodcasts, bbc-radio-4, bloomberg) or the base62-encoded publisher ID.

​
Publisher profile

The composite profile is the one-call summary an advertiser asks for first: “is this publisher’s catalog broadly placeable?” 
curl "https://api.particle.pro/v1/podcasts/publishers/bloomberg/suitability" \
  -H "X-API-Key: $PARTICLE_API_KEY"
The response carries the full picture in one round-trip:
  • tier_breakdown — counts and shares of SAFE, LIMITED, SENSITIVE, UNSAFE across the publisher’s analyzed catalog, plus a placeable_share (SAFE + LIMITED) — the “broadly buyable” slice.
  • category_breakdown — one entry per GARM category, always 12 entries even when prevalence is NONE, with prevalence counts, advertiser-relevant treatment counts (PROMOTIONAL, GLAMORIZING), and a high_risk_count (FREQUENT/PERVASIVE or GLAMORIZING).
  • top_concerns — up to three categories ranked by high_risk_count. Surfaced separately so callers can scan a publisher’s worst dimensions without traversing the full breakdown.
  • confidence_breakdown — LOW / MEDIUM / HIGH counts of the agent verdicts that produced this rollup.
  • coverage.analyzed_coverage + coverage.quality — context for the composition above.

​
Drill down to specific podcasts

When the profile shows concerning composition, drill into the specific shows. The drill-down endpoint returns a paginated list of the publisher’s analyzed podcasts with their tier, confidence, and flagged categories. 
# Most-risky shows in the iHeart catalog
curl "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/suitability/podcasts?sort=risk_desc&limit=10" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# iHeart shows where 'illegal_drugs_alcohol_tobacco' content is at least OCCASIONAL
curl "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/suitability/podcasts?category=illegal_drugs_alcohol_tobacco&min_prevalence=OCCASIONAL" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# iHeart shows that GLAMORIZE 'crime_harmful_acts' content
curl "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/suitability/podcasts?category=crime_harmful_acts&treatment=GLAMORIZING" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Each entry surfaces only enough per-category context to make the row scan-able (code, prevalence, treatment, derived risk_level). Per-category reasoning and evidence excerpts are intentionally not surfaced here — fetch GET /v1/podcasts/{id}/suitability for full per-category detail on a specific show. Sort options:
  • risk_desc (default) — UNSAFE first, then SENSITIVE, LIMITED, SAFE.
  • risk_asc — SAFE first.
  • recently_evaluated — most-recent assessment first; useful when you want to surface shows whose verdicts were just refreshed.

​
Cross-publisher leaderboard

Rank publishers against each other on one of four metrics:
MetricSorted by
safestSAFE share of the analyzed catalog (desc)
riskiestUNSAFE share of the analyzed catalog (desc)
most_placeablecombined SAFE + LIMITED share (desc)
most_analyzedabsolute analyzed_podcasts count (desc)
# Top 25 publishers with at least 5 analyzed shows, ranked safest first
curl "https://api.particle.pro/v1/podcasts/suitability/publishers/leaderboard?metric=safest&min_analyzed_podcasts=5&limit=25" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# Publishers most exposed to UNSAFE-tier shows
curl "https://api.particle.pro/v1/podcasts/suitability/publishers/leaderboard?metric=riskiest" \
  -H "X-API-Key: $PARTICLE_API_KEY"
The leaderboard reflects each publisher’s current tier composition (sourced from the denormalized tier on each podcast). It does not accept a historical date window — paginate the audit history per show via GET /v1/podcasts/{id}/suitability?include=history if you need point-in-time analysis.
Each row carries the publisher’s tier_breakdown, coverage.analyzed_podcasts, coverage.analyzed_coverage + coverage.quality, and metric_value (the actual sort key — a share [0, 1] for safest / riskiest / most_placeable, an absolute count for most_analyzed).

​
Category pivot — the regulated-brand view

The most differentiated view in this surface. For one of the 12 GARM categories, rank publishers by exposure across their catalog. An alcohol advertiser pivots on illegal_drugs_alcohol_tobacco and immediately sees which publishers carry the highest catalog-level exposure (and at what prevalence + treatment); a family brand pivots on adult_sexual or hate_speech_aggression to build an exclusion list. 
# Publishers most exposed to illegal_drugs_alcohol_tobacco content
curl "https://api.particle.pro/v1/podcasts/suitability/categories/illegal_drugs_alcohol_tobacco/publishers" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# Same, but only count PROMOTIONAL exposures (sponsored CBD, alcohol endorsements)
curl "https://api.particle.pro/v1/podcasts/suitability/categories/illegal_drugs_alcohol_tobacco/publishers?treatment=PROMOTIONAL" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# Publishers where 'debated_social_issues' content is at least OCCASIONAL
curl "https://api.particle.pro/v1/podcasts/suitability/categories/debated_social_issues/publishers?min_prevalence=OCCASIONAL" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# Reverse view — publishers *least* exposed to a category
curl "https://api.particle.pro/v1/podcasts/suitability/categories/adult_sexual/publishers?direction=least_exposed" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Each row in the response surfaces:
  • exposure_share — share of the publisher’s analyzed catalog with any non-NONE prevalence in the category (or above min_prevalence when set, restricted to treatment when set).
  • high_risk_count — FREQUENT/PERVASIVE or GLAMORIZING podcasts in the category.
  • prevalence_breakdown and treatment_breakdown — the full distribution of exposures in this category across the publisher’s catalog.
  • example_podcasts — up to three example podcasts from the publisher’s catalog that exhibit the highest exposure (ranked PERVASIVE → INCIDENTAL, GLAMORIZING → DOCUMENTARY, then by ID for determinism) so the abstract shares anchor to concrete shows you recognize.

​
Tier classification recap

The publisher rollups use the same four-tier verdict as the per-podcast assessment:
TierFramework risk levelAdvertiser fit
SAFELow RiskSuitable for all advertisers, including kid-directed and family brands.
LIMITEDMedium RiskSuitable for most advertisers; family brands may apply caution.
SENSITIVEHigh RiskMany brands skip; suitable for general-audience and adult-product advertisers.
UNSAFEBrand Safety FloorNo monetization — content violates the Brand Safety Floor for at least one category.
See the per-podcast suitability docs for the full GARM category set, the prevalence + treatment axes, and the risk-derivation rules.