API reference

Base URL https://partners.yourbrandontime.com · auth headerX-API-Key. The authoritative list of fields, dimensions and metrics is always live at /v1/schema.

Indices

siv_business_ideas — brand/product mentions from spoken transcripts (sentiment, brands, components/ingredients, topics, opportunities). The main analytics index.

siv_content_creator — creator profiles: audience size, engagement, niche, and aggregate audience demographics.

siv_info — video catalogue metadata (title, channel, platform, views, likes, duration, tags).

GET /v1/schema

Returns indices, filterable fields, group-by dimensions, numeric metrics and limits. No body.

curl -s https://partners.yourbrandontime.com/v1/schema -H "X-API-Key: YOUR_API_KEY"

POST /v1/aggregate

Group by a dimension, rank by a metric. The main analytics endpoint.

Body fields: index (required), group_by (required, a whitelisted dimension), metric (required, {type, field?}), filters (optional, exact-match map), order (desc|asc), size (buckets, max 50).

metric.type: count · sum · avg · min · max. Non-count requires metric.field (a numeric field, e.g. sentiment_score, views, subscriber_count).

curl -s -X POST https://partners.yourbrandontime.com/v1/aggregate \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"index":"siv_business_ideas","filters":{"category":"Beauty"},
       "group_by":"brand_name","metric":{"type":"avg","field":"sentiment_score"},
       "order":"desc","size":10}'

Response: { status, result:[{ data:{ index, group_by, matched_documents, buckets:[{key,count,metric?}] } }] }

POST /v1/search

Example documents with allowlisted fields only (no personal data). Body: index, filters (exact-match), q (optional full-text, only on siv_info), size (capped — 10 for aggregate keys, up to 50 for raw), sort_field/sort_order (optional, numeric/date fields).

curl -s -X POST https://partners.yourbrandontime.com/v1/search \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"index":"siv_info","filters":{"platform":"youtube"},"q":"nike","size":5}'

POST /v1/creators

Rank/search creators (siv_content_creator) with metrics and aggregate demographics. Body: filters, sort_field (default subscriber_count), sort_order, size.

curl -s -X POST https://partners.yourbrandontime.com/v1/creators \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"filters":{"dominant_country":"ES"},"sort_field":"subscriber_count","size":10}'

POST /v1/co-mentions

Find the videos or channels that mention all of N values together — e.g. two brands, or a brand + an ingredient. Returns only IDs + counts (it is an aggregation, never raw documents), so it is available to every key.

Body: index (default siv_business_ideas), field (a term field, default brand_name), values (required, list of 2–5), group_by (video_id for same-video, or channel_name/channel_uid for same-creator), size (max 50).

curl -s -X POST https://partners.yourbrandontime.com/v1/co-mentions \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"index":"siv_business_ideas","field":"brand_name",
       "values":["Nike","Adidas"],"group_by":"video_id","size":10}'

Response: { result:[{ data:{ field, values, group_by, results:[{key, total_mentions, matched_values}] } }] }. An empty results means no entity mentions all values together — a valid answer. Resolve a returned video_id to a title with /v1/search on siv_info.

Errors & limits

401 missing key · 403 invalid/revoked/insufficient scope · 429 rate limit exceeded · 400 bad request (unknown index/field, or a limit violation) · 503 data backend unavailable.

Two throttles return 429: a per-minute burst cap (anti-abuse) and your plan's monthly call quota (resets each calendar month — shared across all your keys). Both are shown on your Profile › API keys page; upgrade your plan for a higher monthly quota.

Hard caps: size ≤ 50 results, aggregation buckets ≤ 50, query timeout 5s. Personal data (creator real names, exact quotes, individual-level fields) is always redacted; demographics are aggregate distributions only.