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

# Content intelligence

> Search hooks, analyze a reference video, track proven hits and your own channel's performance, and turn evidence into an original production brief.

Content intelligence answers "what works, and why?" with evidence you can check:
openings that held attention, breakdowns of reference videos, accounts whose
posts beat their usual reach, and how your own uploads are doing. Then it turns
that evidence into a brief for something original.

## Find a reference

`GET /v1/hooks` searches a bounded recent corpus plus your own saved video analyses.
Filter by `q`, `platform`, `niche`, `language`, `hookType`, `visualHookType` and
`evidence` (`observed`, `metadata` or `all`). Page with `limit` and `offset`;
`nextOffset` is `null` at the end of the sample. The sample changes as new
content arrives, so treat it as a search, not a stable export.
`GET /v1/hooks/stats` reports counts over the same filtered sample.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl "https://api.sigmora.org/v1/hooks?q=budget&platform=tiktok&evidence=observed&limit=20" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"
```

Observed entries carry speech or timestamped visual evidence. Metadata entries
are suggestions inferred from titles and descriptions — **not verbatim opening
lines**. Hook classifications are heuristics, not proof of why something
performed. Items with an unknown platform, category or language are left out
when you filter on that field.

## Analyze a video independently

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST https://api.sigmora.org/v1/video/analyze \
    -H "Authorization: Bearer $SIGMORA_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: reference-breakfast-001" \
    --max-time 600 \
    -d '{"projectId": "prj_9x2a4c", "videoUrl": "https://www.youtube.com/shorts/YOUR_VIDEO_ID"}'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import os
  import requests

  session = requests.Session()
  session.headers["Authorization"] = f"Bearer {os.environ['SIGMORA_API_KEY']}"

  analysis = session.post(
      "https://api.sigmora.org/v1/video/analyze",
      headers={"Idempotency-Key": "reference-breakfast-001"},
      json={"projectId": "prj_9x2a4c", "videoUrl": "https://www.youtube.com/shorts/YOUR_VIDEO_ID"},
      timeout=600,
  ).json()["analysis"]
  print(analysis["id"], analysis["hook"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const headers = {
    Authorization: `Bearer ${process.env.SIGMORA_API_KEY}`,
    "Content-Type": "application/json",
  };

  const { analysis } = await fetch("https://api.sigmora.org/v1/video/analyze", {
    method: "POST",
    headers: { ...headers, "Idempotency-Key": "reference-breakfast-001" },
    body: JSON.stringify({ projectId: "prj_9x2a4c", videoUrl: "https://www.youtube.com/shorts/YOUR_VIDEO_ID" }),
    signal: AbortSignal.timeout(600_000),
  }).then((r) => r.json());
  console.log(analysis.id, analysis.hook);
  ```
</CodeGroup>

The call is synchronous and can take several minutes. It accepts public videos
up to **180 seconds** long, checked against the downloaded media before any
analysis. It is a paid capability — `GET /v1/capabilities` has the live price —
and failures are not charged. After a connection failure, retry with the same
idempotency key.

The response contains `analysis.id`, `hook`, `scenes`, `transcript`, `ctas`,
`pacing`, `lowConfidenceFields`, `analyzedAt`, and the original source URL.
Speech that starts in the first six seconds forms the spoken opening, even if a
segment runs past six seconds. Scene boundaries are approximate, not
frame-perfect. Call-to-action matching recognizes English phrases. Pacing
describes the scenes observed, not a count of every cut.

`GET /v1/video/analyses/{analysisId}` reads a saved analysis for free. Analyses
are private to you and your workspace; analyzing a URL never adds it to shared
research data.

## Turn evidence into production

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -X POST https://api.sigmora.org/v1/research/briefs \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "analysisId": "YOUR_ANALYSIS_ID",
    "topic": "Breakfast on a budget",
    "audience": "Busy parents",
    "targetPlatform": "shorts"
  }'
```

Brief creation is free and deterministic. It returns suggested original beats,
timestamped references, a `productionPrompt`, and an `adaptationRequest`.
Suggestions are labeled separately from reference observations.

1. Add your `projectId` to `brief.adaptationRequest` and send it to
   `POST /v1/text/adapt` with a new idempotency key.
2. Review the returned script.
3. Send it as `story` to `POST /v1/video/render` with `videoType: "social"`,
   `aspect: "vertical"`, and your `projectId`. Use another idempotency key.
4. Poll `GET /v1/jobs/{jobId}` and collect `artifacts.download` only when
   `status` is `done`.

Adaptation and rendering are charged at their normal prices. The dashboard's
**Research → Content intelligence** tab runs the same flow.

## Preview, save, and run discovery

`POST /v1/discovery/preview` accepts `intent`, `keywords`, `excludeKeywords`, and
`platforms`. It returns a deterministic quality check and a `configPatch`.
It does not run a model, collect content, create a resource, or spend credits.
Without explicit keywords it uses phrases from the intent; provide several
specific phrases for better coverage.

Send the patch to `PUT /v1/discovery/configs/{brandId}`. Use `enabled: false` for
manual research, then `POST /v1/discovery/runs` with `contentBrandId` and
`kind: "discover"`. To schedule daily research set `enabled: true` and
`discoveryIntervalMinutes: 1440`.

`GET /v1/discovery/configs/{brandId}/results` reads the plan's results, applying
its platforms and its exclusions (matched case-insensitively against titles,
descriptions and hashtags). Matching is by theme and phrase — it does not
guarantee that every result matches your intent, or that every platform is fully
covered. Source health and partial runs are reported as in
[Niche discovery](/discovery).

## Creator breakouts

`GET /v1/creators/{creatorId}/outliers?platform=youtube_shorts`, where
`creatorId` is the creator's username or id, returns
observed posts compared with the median views of up to 20 earlier observed
posts from that same creator and platform. Five baseline posts and a positive
median are required; otherwise `outlierRatio` is null. A ratio of three or more
is labeled a breakout.

The response includes the baseline sample size, publication window and when the
metrics were observed. Collected posts skew toward successful ones and lifetime
views are not adjusted for age, so treat this as a research signal, not a full
channel audit.

## Watched accounts and their proven hits

`GET /v1/competitors` and `GET /v1/competitors/{competitorId}` return each
watched account with `performance`: the median views (or likes) of its posts
older than 72 hours, how many posts that median covers, and up to 12 `hits`
that beat it, each with its `outlierRatio`. A hit needs a ratio of two or more
over at least eight mature posts; with fewer, `status` is
`insufficient-history` rather than a guessed ratio. `reason` says why there are
no numbers (no data key for the platform, out of credits).

Accounts are measured when added and refreshed weekly. To measure one now:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -X POST https://api.sigmora.org/v1/competitors/$COMPETITOR_ID/measure \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Idempotency-Key: measure-acme-001" \
  -H "Content-Type: application/json" \
  -d '{}'
```

It is charged like **Measure now** in the dashboard: one collection at the data
provider's measured cost when a paid source is needed for the account (YouTube
is free). A measurement under an hour old is returned as is, with
`measured: false`, and is not charged again.

## Your channel's performance, and fixing a live video

`GET /v1/performance/channels` reads your connected YouTube channels' measured
uploads, each against its own channel's medians, with a `diagnosis`:

| Diagnosis | Meaning | The fix |
| - | - | - |
| `winner` | Well above the usual | Make variations of the format |
| `packaging` | Low CTR, normal retention | A new title or thumbnail |
| `hook` | Viewers leave early | Recut the opening |
| `under` · `steady` | Below or around the usual | Keep iterating |
| `too-new` · `unmeasured` | Not enough data yet | Wait |

It also lists `recentEdits` — live changes already made, with the numbers from
before them. Reading it is free.

To change a live video, propose the edit:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -X POST https://api.sigmora.org/v1/performance/video-edits \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Idempotency-Key: retitle-dQw4w9WgXcQ-001" \
  -H "Content-Type: application/json" \
  -d '{"videoRef":"dQw4w9WgXcQ","title":"A sharper title","reason":"packaging"}'
```

Nothing changes yet. The answer is the same approval a Sigma turn proposes:
`approval.summary` says exactly what will change and `approval.approval` is a
signed reference. Send it to `POST /v1/sigma/approvals` to apply the change
through the channel's YouTube connection. The change is recorded with what it
replaced and the video's numbers from before it, so a later
`GET /v1/performance/channels` shows whether it worked. A free edit can run
under the workspace's approval setting without the extra call; the answer then
carries `approval.autoApproved`. Pass `projectId` to keep the conversation in a
project.

## MCP

Use `video_analyze`, `video_analysis_get`, `hooks_search`, `hooks_stats`,
`discovery_preview`, `creator_outliers`, and `research_brief`. Paid calls require
`projectId` and `idempotencyKey`. Continue with `text_adapt`, `video_render`,
and `jobs_get` for production.

Watched accounts are `competitors_list`, `competitors_get` and
`competitors_measure`; your own channels are `performance_channels_get` and
`performance_video_edits_propose`, applied with `sigma_approve`; the niche
corpus is `discovery_corpus_get`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.