> ## 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.

# Niche discovery

> Compile a channel's business profile into platform watch terms, run collectors, inspect freshness, and prove what each trend is based on.

## From business description to a watch plan

Creating or updating a channel with a niche or description stores a canonical
theme profile. Discovery compiles that profile into a bounded query plan for
YouTube Shorts, Instagram Reels, TikTok, X, Reddit, and news.

```bash theme={null}
curl -X PUT "https://api.sigmora.org/v1/discovery/configs/$CHANNEL_ID" \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "platforms": ["youtube_shorts", "reddit", "news"],
    "regionCode": "US",
    "discoveryIntervalMinutes": 360,
    "refreshIntervalMinutes": 60
  }'
```

The stored `queryPlan` includes:

* the canonical primary and supporting theme ids;
* seed terms derived from the channel niche, description, and taxonomy path;
* platform-specific terms;
* the signal intents each query is looking for: momentum, news,
  controversies, audience questions, or competitors;
* its compiler version and timestamp.

The plan is stored rather than regenerated invisibly during every run. That
makes a result reproducible and lets an operator see exactly what Sigmora was
watching.

## Source health

```bash theme={null}
curl "https://api.sigmora.org/v1/discovery/configs/$CHANNEL_ID/health" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"
```

Health distinguishes a collector that is ready from one missing a provider
credential. Reddit and news can be invoked without a customer credential;
YouTube, X, TikTok, and Instagram depend on the deployment's configured
providers.

Each source reports `queryMode`. YouTube, X, TikTok, and Instagram use
`provider-query`, meaning the compiled channel terms reach the provider
collector. Reddit and news report `broad-ingest-theme-filter`: Sigmora ingests
the configured broad sources and applies the canonical theme layer afterward.

`ready` means Sigmora can invoke the source. It does not promise provider
uptime, quota, or complete internet coverage.

## Run now

```bash theme={null}
curl -X POST https://api.sigmora.org/v1/discovery/runs \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelId": "'"$CHANNEL_ID"'", "kind": "discover" }'
```

Use `kind: "refresh"` to re-poll metrics. Current metric refresh is strongest
for YouTube, where every upsert appends a timestamped snapshot and preserves the
historical peak. Trend evidence can therefore report view velocity when at
least two observations exist.

A multi-source run can finish as `partial`: successful source results remain
available and source errors are retained. A provider failure never erases the
evidence collected elsewhere.

List or inspect runs:

```text theme={null}
GET /v1/discovery/runs?channelId=...
GET /v1/discovery/runs/{runId}
```

Enabled plans are processed by the same internal scheduled tick as the legacy
viral collector. `lastDiscoveryAt` and `lastRefreshAt` show whether that
automation is actually moving.