Commercial intelligence

​

When to use

• You sell sponsorships or negotiate them. Pull a channel’s recurring advertisers before a negotiation: “who already sponsors TBPN, at what cadence, since when?” Never go into a sponsorship negotiation blind.
• You model competitor spend. Row-level ad reads carry verbatim quotes, promo codes, and offers: “every Ramp ad read across business podcasts this year, with the codes they ran.”
• You find organic champions. Endorsements are unpaid recommendations from hosts and guests: “which shows organically endorsed Figma after the IPO?”
• You build advertiser dashboards. Re-expose the classification, confidence, and dispute machinery in your own product.

​

The two universes

​

Classification

​

Recommendations: row-level evidence

GET /v1/recommendations
GET /v1/entities/{id}/recommendations

const res = await fetch(
  'https://api.arcmira.com/v1/recommendations?entity_id=ent_14&mention_class=ad_read&limit=25',
  { headers: { Authorization: `Bearer ${process.env.ARCMIRA_API_KEY}` } },
);
const { data, has_more, next_cursor } = await res.json();

import os, httpx

r = httpx.get(
    'https://api.arcmira.com/v1/recommendations',
    params={'entity_id': 'ent_14', 'mention_class': 'ad_read', 'limit': 25},
    headers={'Authorization': f"Bearer {os.environ['ARCMIRA_API_KEY']}"},
)
body = r.json()

curl 'https://api.arcmira.com/v1/recommendations?entity_id=ent_14&mention_class=ad_read&limit=25' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

{
  "id": "com_119682",
  "recommendation_id": 119682,
  "mention_class": "ad_read",
  "entity": { "id": "ent_124261", "name": "Bezel", "type": "organization" },
  "media": {
    "video_id": "DRZatti6mVM",
    "title": "...",
    "published_at": "2025-12-17",
    "channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg",
    "source_channel": { "id": "ent_6", "name": "TBPN" }
  },
  "start_timestamp": "12:34",
  "end_timestamp": "13:02",
  "start_seconds": 754,
  "end_seconds": 782,
  "verbatim_quote": "...",
  "promo_code": "BEZEL20",
  "offer": null,
  "sentiment": 0.8,
  "sentiment_score": 0.8,
  "confidence": 0.95,
  "speaker_role": "host",
  "conflict_status": null,
  "resolution": null
}

• id is the public com_* form: pass it to Community Review to dispute a row.
• Read start_seconds/end_seconds (integer seconds; 0 means the full episode). The start_timestamp/end_timestamp MM:SS strings are deprecated and will be removed after a changelog-announced sunset.
• sentiment_score is the raw [-1, 1] number, matching mention rows. The sentiment field carries the same number and is deprecated; read sentiment_score.
• promo_code and offer are nullable, populated when the extractor found explicit codes or offers in the quote.
• speaker_role distinguishes host reads from guest recommendations.
• conflict_status/resolution surface cross-pass classification conflicts; disputed rows are excluded by default.

​

Channel sponsors: the rollup

GET /v1/channels/{channel_id}/sponsors

{
  "channel": { "id": "ent_6", "youtube_channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg", "name": "TBPN" },
  "sponsors": [
    {
      "entity": { "id": "ent_14", "name": "Ramp", "type": "organization" },
      "ad_reads": 227,
      "videos": 197,
      "first_seen": "2025-02-01",
      "last_seen": "2026-04-24",
      "sponsor_status": { "status": "active", "ad_count": 80, "first_ad_date": "2025-02-01", "last_ad_date": "2026-04-24" }
    }
  ],
  "meta": { "min_ad_reads": 3, "count": 40 }
}

• channel.id is null when there is no canonical entity for the channel; youtube_channel_id is always present.
• sponsor_status is null for entities not in the known-advertiser registry; when present, status is active, lapsed, ended, or uncertain.
• meta.count is the returned page size, not a global total.

curl 'https://api.arcmira.com/v1/recommendations?entity_id=ent_14&channel_id=UC-DRzaGnL_vtBUpCFH5M0tg&mention_class=ad_read&limit=25' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

​

Discovery and teasers

• GET /v1/entities/search?has_recommendations_data=true restricts discovery to entities with commercial signal (free).
• Entity reads on organization/product entities include a recommendations_summary aggregate for entitled callers (totals, unique shows, first/last seen, channels_as_sponsor). Zero rows.
• Channel reads include a teaser under recommendations_summary: recommendations_summary.sponsor_count is visible to every caller (a discoverability signal); recommendations_summary.top_sponsors appears only with Pro+ and recommendations:read.

​

Billing

​

Community Review

curl -X POST 'https://api.arcmira.com/v1/feedback?type=recommendations' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "query": { "entity_id": "ent_124261", "mention_class": "ad_read" },
    "corrections": [{
      "id": "com_119682",
      "mention_class": "mention",
      "reason": "false_positive_ad_read",
      "notes": "Host was discussing the product organically. No sponsor language, no code."
    }]
  }'

​

Errors

​

Next

• Try it in the playground
• Search: the free evidence layer these rows enrich.
• Community Review: the correction contract for every commercial surface.