Skip to content
Developers · API v1 and MCP

Read the desk from your own tools.

Four operations, prepaid credits, one key. The same four are exposed as MCP tools so an agent can ask "is this channel's audience real?" and get the certificate's numbers back. Every payload is aggregate: no chatter identities, no transcripts, no other channel named in a reason.

openapi.jsonllms.txtself-describing index

Authentication and credits

Send the key as X-API-Key: sk_… (or Authorization: Bearer sk_…). Keys are minted from the desk under Plan → API on the Pro and Agency plans and are shown once. Each call deducts its cost from the key's prepaid balance; 402 means the balance is empty. Credits are granted by the desk at present — write to the desk to top up.

curl -H "X-API-Key: sk_…" https://provenaudience.com/api/v1/channel/roshtein

MCP

A stateless Streamable-HTTP MCP server at POST https://provenaudience.com/mcp. Same key, same costs; tools get_channel, leaderboard, brands, usage. Claude Code:

claude mcp add --transport http provenaudience https://provenaudience.com/mcp --header "X-API-Key: sk_…"

GET /api/v1/channel/{slug}

One channel: latest live audience verification, 7-day watch time, category ranks, sponsor history. 1 credit · MCP tool get_channel

slug (path) — Kick channel name

{
  "channel": {
    "slug": "example",
    "language": "es",
    "last_sponsor": "stake"
  },
  "week": {
    "hours_watched": 120340,
    "peak_viewers": 9800,
    "live_hours": 41.5
  },
  "verification": {
    "verdict": "green",
    "score": 88,
    "confidence": "high",
    "checked_at": "2026-09-01 20:05:41",
    "sample_minutes": 10,
    "avg_viewers": 2410.5,
    "unique_chatters": 131,
    "chatters_per_100": 5.4,
    "msgs_per_min": 38.2,
    "reasons": [
      "…"
    ],
    "chat_metrics": {
      "chatterBuckets": {},
      "langMix": {},
      "kickActive": {}
    }
  },
  "ranks": {
    "of": 1808,
    "hours_watched": {
      "rank": 14,
      "value": 120340
    }
  },
  "sponsors": [
    {
      "sponsor": "stake",
      "first_seen": "2026-07-22 09:07:01",
      "last_seen": "2026-09-01 19:37:01"
    }
  ],
  "credits_left": 99
}

GET /api/v1/leaderboard

Category leaderboard by hours watched over the trailing window, with verdicts. 5 credits · MCP tool leaderboard

days (query) — 1–90, default 7

{
  "days": 7,
  "rows": [
    {
      "slug": "example",
      "hours_watched": 736150.2,
      "live_hours": 43.2,
      "avg_viewers": 16382,
      "peak_viewers": 128110,
      "language": "es",
      "sponsor": "stake",
      "verdict": "green",
      "score": 100
    }
  ],
  "credits_left": 94
}

GET /api/v1/brands

Sponsor brands: 7-day sponsored hours watched, channel count, share of voice. 2 credits · MCP tool brands

{
  "brands": [
    {
      "sponsor": "stake",
      "sponsor_type": "crypto",
      "hours_watched_7d": 2552431,
      "channels_7d": 39,
      "share_of_voice_7d": 0.136
    }
  ],
  "credits_left": 92
}

GET /api/v1/usage

Remaining credits, per-call costs, 30-day call count. 0 credits · MCP tool usage

{
  "credits_left": 92,
  "costs": {
    "channel": 1,
    "leaderboard": 5,
    "brands": 2,
    "usage": 0
  },
  "calls_30d": 3
}

Verdict vocabulary: green = PROVEN, yellow = UNCLEAR, red = FAKE; a low-confidence sample is provisional. Hours watched is concurrent viewers integrated over live time, sampled every thirty minutes. The method behind a verdict is on the how it works page.