Taxonomies and verdicts

Labels in the API come from three sources: IAB Tech Lab taxonomies (content, audience, ad product), the GARM brand-safety categories, and a handful of fixed vocabularies defined by Pyler (genre, music mood, weather, human activity). Brand-safety verdicts are a separate, deterministic decision computed from GARM hits and your policy rules.

Label set	Where it appears	Level
IAB Content	iab_content_leaf; filter iab_t1 on search and video list	Video
IAB Audience (interest, purchase intent)	iab_audience_interest_leaf, iab_audience_purchase_intent_leaf	Video
IAB Ad Product	iab_ad_product_leaf	Video
GARM	garm_categories (scene), garm_level (scene marker), garm_video (video), garm (ad screening)	Scene and video
Genre	genre	Video
Music mood, weather, human activity	music_mood, weather, human_activity	Scene

Label strings are enforced as exact enums in the pipeline. Compare them verbatim, including case, spacing and punctuation.

IAB Content Taxonomy

The IAB Tech Lab Content Taxonomy is a "common language" for describing content; its typical uses are contextual targeting and brand safety. The pipeline works from the Tier-1 / Tier-2 hierarchy of the taxonomy and returns leaf labels.

How videos get labels. IAB categories are not predicted per scene. The summarizer reads all scene captions, transcripts and entities together and assigns up to five iab_content_leaf labels describing what the video is about. A scene object therefore has no IAB field; look at its parent video.

Filtering. iab_t1 on POST /api/v1/search and GET /api/v1/videos takes Tier-1 content category names (for example Food & Drink) and narrows results to videos in those branches.

IAB Audience Taxonomy

The Audience Taxonomy gives the industry a common nomenclature for audience segments. Its Tier-1 split is Demographic, Interest (segments based on user interests in particular topics or activities) and Purchase Intent (segments based on indicated intent to purchase particular products or services).

The API infers the two content-derivable branches and omits Demographic, which cannot be inferred from content alone:

Field	Reading
iab_audience_interest_leaf	Interests of the viewers this video suits.
iab_audience_purchase_intent_leaf	Product or service categories those viewers are likely in market for.

IAB Ad Product Taxonomy

The Ad Product Taxonomy standardizes how the product or service being advertised is described, giving publishers control over the kinds of ads delivered through automated channels.

The API uses it in the reverse direction: iab_ad_product_leaf lists the ad product categories that fit next to this content (a cooking video might yield restaurant or food-delivery categories). Ad matching uses these labels. GET /api/v1/ads/{ad_id}/analysis returns the same IAB and GARM fields for a registered ad creative.

GARM brand-safety categories

The GARM Brand Safety Floor, a framework published by the World Federation of Advertisers' Global Alliance for Responsible Media initiative, lists the categories the industry uses to keep ads away from harmful content. The API applies that framework as implemented by Pyler. Two closely related vocabularies are in use.

Indexing and search (12 categories, three levels)

Used by scene garm_categories, scene-marker garm_level, video garm_video, and the garm_min_level filter.

Slug
adult
weapons
crime
death_conflict
piracy
hate
profanity
substances
spam_harmful
terrorism
sensitive_social
misinformation

Severity levels are high, medium, low. Scene markers add none for a scene with no flag.

Scene flags vs video assessment. Scene-level garm_categories record anything genuinely depicted in a single clip and are intentionally sensitive: fairy tales, parody, sports highlights and scripted drama over-trigger. The summarizer then reviews each flagged category against the whole video and keeps only the ones that are truly present. garm_video therefore contains only confirmed entries, each as:

{ "category": "substances", "level": "medium",
  "reasoning": "Bar scene with repeated on-screen drinking.", "time_ranges": [] }

Filtering. garm_min_level (low | medium | high) on search and the video list is a floor: "only matches at this level or higher".

Ad screening (11 categories)

POST /api/v1/ad-blocking and POST /api/v1.1/ad-blocking evaluate an ad creative against the GARM Brand Safety Floor. Slugs are stable and safe to switch on.

Slug	GARM title
adult_and_explicit_sexual_content	Adult & Explicit Sexual Content
arms_and_ammunition	Arms & Ammunition
crime_human_rights_violations	Crime & Harmful Acts, Human Rights Violations
death_injury_or_military_conflict	Death, Injury, or Military Conflict
online_piracy	Online Piracy
hate_speech_and_acts_of_aggression	Hate Speech & Acts of Aggression
obscenity_and_profanity	Obscenity & Profanity
illegal_drugs_alcohol_tobacco_vaping	Illegal Drugs / Tobacco / E-cigarettes / Vaping / Alcohol
spam_or_harmful_content	Spam or Harmful Content
terrorism	Terrorism
debated_sensitive_social_issue	Debated Sensitive Social Issue

Screening results report fired categories without a severity level: each garm[] item is { category, reasoning }.

Pyler vocabularies

Besides IAB and GARM, a few fields use fixed vocabularies defined by Pyler.

Field	Vocabulary
genre (video)	28 film-and-TV genre labels; one to three per video, dominant first.
music_mood (scene)	calm, energetic, dramatic, playful, melancholic, tense, none.
weather (scene)	20 observed weather / sky states, including Indoor and Unknown / Not visible.
human_activity (scene)	AVA-80 activity labels, derived from the free-form action slugs.

The verdict model

Brand-safety screening returns a single deterministic verdict in block_decision.

block_decision	When
block	At least one GARM category fired or at least one policy rule matched.
allow	Nothing fired and no rule matched.

There is no intermediate "review" state in the API. The model supplies the evidence; the verdict is computed in code from that evidence, so the verdict always agrees with the garm and blocklist.hits it ships with. The evidence itself is model output and can be wrong; treat block as "hold for review", not as a legal or policy determination. See Data handling.

garmobject[]

GARM categories that fired, each { category, reasoning }. Empty when clean. Always evaluated, even with no rules.

blocklistobject

{ rules, hits }. rules is every policy line evaluated (your team's saved blocklist plus the request's ad-hoc rules). hits is [{ rule, matched, evidence }]; items with matched: true are the rules that fired.

explanationstring | null

One-sentence human-readable reasoning prefixed with the triggering categories and rules. For display only; branch on garm and blocklist.hits instead.

screening_failedboolean

true when the screening itself errored. The verdict is then a precautionary block (fail-closed), not a content judgement. Retry, and never surface it to end users as a real block.

warning

A real block and a failed screening both produce block_decision: "block" and an explanation that starts with BLOCKED. Branch on screening_failed, not on the text.

Policy rules

Policy rules are natural-language lines ("no on-screen consumption of alcohol"). Two sources are merged on every screening:

• Your team's saved blocklist, managed in the dashboard's Ad Blocking tab.
• Ad-hoc rules sent with the request, comma- or newline-separated.

Each rule is judged independently and reported in blocklist.hits. Rules are additional policy on top of GARM; GARM categories are always evaluated. The API does not define custom categories beyond these rules.

Where verdicts come from

Endpoint	Input	Notes
POST /api/v1/ad-blocking	Multipart file + optional title, rules	Synchronous, a few seconds. Creatives capped at about 120 s. Result has ad_id: null.
POST /api/v1.1/ad-blocking	JSON ad_id (+ rules)	Screens a registered creative; 409 if it is not ready.
GET /api/v1.1/ad-blocking	ad_id filter	Stored results, newest first. Use it to recover a verdict lost to a client timeout instead of re-submitting.

See the Brand safety guide for an end-to-end recipe.