Themes and content economics

Two different things

Sigmora keeps stable themes separate from fast-moving trends.

Personal Finance, Beauty, and Video Gaming are themes: durable classifications describing what content is about.
A bank failed this morning or creators are switching to a new editing format are trends: time-bound clusters of observations.

Mixing the two would make identifiers unstable and historical analytics impossible to compare.

The taxonomy

The canonical backbone is IAB Tech Lab Content Taxonomy 3.1. The API exposes its version and the SHA-256 of the exact upstream TSV frozen into this deployment. YouTube’s videoCategoryId is retained as source evidence and mapped into the canonical taxonomy. It is not itself the theme: YouTube categories are region-aware, provider-specific, and intentionally broad. The supported values can be retrieved from YouTube videoCategories.list.

curl "https://api.sigmora.org/v1/themes?rootOnly=true" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"

Theme ids are namespaced and versioned, for example:

{
  "id": "iab:3.1:391",
  "name": "Personal Finance",
  "rootId": "iab:3.1:391",
  "path": ["Personal Finance"],
  "taxonomyVersion": "3.1"
}

Use the opaque nextCursor to page. Filter children with parentId, or search names and paths with q.

Classification

The free classification endpoint runs the same deterministic baseline used at ingestion:

curl -X POST https://api.sigmora.org/v1/themes/classify \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Three ways founders can extend their runway",
    "description": "Cash flow and business banking for an early-stage SaaS",
    "hashtags": ["startup", "finance"],
    "sourceCategories": [
      { "system": "youtube-video-category", "id": "27", "label": "Education" }
    ]
  }'

Each assignment carries:

canonical themeId and rootThemeId;
confidence;
method (provider-category, keyword-rules, ai, manual, or fallback);
human-readable reasons;
the tagger version and assignment time.

No reliable match returns sigmora:general with needs-review; it never invents a high-confidence category to make the response look complete. The asynchronous analyzer can later add an ai assignment from its cheap niche pass. It preserves other-root evidence, and a manual assignment always wins.

Detect a customer’s niche

The customer’s niche uses the same identifiers as content. It is not a second free-form taxonomy:

curl -X POST https://api.sigmora.org/v1/niches/detect \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Acme Money",
    "businessDescription": "We teach young professionals about investing and credit scores.",
    "products": ["personal finance course"],
    "audience": "first-time investors"
  }'

The same profile is persisted automatically when a channel is created with a niche or description, and recomputed when that context changes. It can filter discovery, rank ideas and select relevant competitors. A weak description returns needs-review; onboarding should let the customer correct it.

Economics is a prior, not a payout prediction

Theme definitions contain qualitative economics:

monetization tier;
commercial intent;
likely monetization routes;
advertiser categories;
compliance and brand-safety risks.

These describe a starting prior. They are explicitly not CPM, RPM, revenue or advertiser-demand forecasts. Actual payment depends on audience geography, platform, format, season, account eligibility, inventory and measured channel performance. Observed customer economics must override the prior during ranking; they must never rewrite the taxonomy. Finance can therefore carry a premium prior and financial-claims risk without Sigmora claiming that a finance video will earn a particular amount.

Viral-content items

Every new viral item is tagged before it is inserted. Old rows are hydrated safely on read and tagged when recollected, so the public item contract never omits theme state.

curl "https://api.sigmora.org/v1/viral-content?themeId=iab%3A3.1%3A391&minScore=70" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"

The item contains the original provider categories and a canonical themes object with the primary theme, ancestors, assignment provenance and joined economics.

Trend signals and real-time honesty

curl "https://api.sigmora.org/v1/trends?themeId=iab%3A3.1%3A391&windowHours=24" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"

GET /v1/trends returns:

theme-momentum aggregates;
recurring title/hashtag topic clusters inside a canonical theme;
explicit controversy-language signals;
recent news-source signals;
the content observations supporting every result;
response freshness (live, recent, aging, or empty);
sampled platform coverage and its limit.

The endpoint describes what Sigmora’s configured collectors observed. It does not claim complete internet coverage, and a news or controversy signal is not independent verification. Use the evidence links and verify factual claims before generating content. Topic clusters report method: lexical-title-hashtag-clustering; they are transparent lexical evidence, not hidden semantic entity resolution. To turn the channel profile into recurring platform watch terms and observable collection runs, continue to Niche discovery. To connect a selected signal to writing, rendering, adaptation, and distribution, see Content autopilot.

Getting started

Core concepts

Themes and content economics

Two different things

The taxonomy

Classification

Detect a customer’s niche

Economics is a prior, not a payout prediction

Viral-content items

Trend signals and real-time honesty

​Two different things

​The taxonomy

​Classification

​Detect a customer’s niche

​Economics is a prior, not a payout prediction

​Viral-content items

​Trend signals and real-time honesty

Two different things

The taxonomy

Classification

Detect a customer’s niche

Economics is a prior, not a payout prediction

Viral-content items

Trend signals and real-time honesty