> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sigmora.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Themes and content economics

> How Sigmora classifies every viral-content item with stable, explainable themes without pretending a theme is a revenue forecast.

## 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](https://iabtechlab.com/standards/content-taxonomy/).
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`](https://developers.google.com/youtube/v3/docs/videoCategories/list).

```bash theme={null}
curl "https://api.sigmora.org/v1/themes?rootOnly=true" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"
```

Theme ids are namespaced and versioned, for example:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
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](/discovery). To connect a selected
signal to writing, rendering, adaptation, and distribution, see
[Content autopilot](/autopilot).