The clipping-campaign radar, over REST

Create a key on the Developer console (shown once, stored hashed), then:

curl "https://clipradar.co/api/v1/campaigns?target_platform=tiktok&sort=rate&limit=5" \
  -H "Authorization: Bearer cr_live_YOUR_KEY"

Success envelope: { data, meta? } · errors: { error: { code, message, details? } } · the x-api-key header works as an alias. Reads are GET; writes use POST/PATCH/PUT/DELETE, validate strictly and accept an Idempotency-Key. All JSON, all CORS-open.

Metered per request, funded from three pools and spent in this order — monthly quota first, prepaid credits after:

Quotas reset on the 1st (UTC). Tiers stack with the membership allowance. Buy on Billing → API plans — crypto or card.

~85 operations across the campaign radar, your own data and webhooks. This table renders from the same endpoint registry the API enforces, so it can’t drift; every path also appears in GET /api/v1 (the free discovery index) and the OpenAPI spec. The scope column is the one scope each route needs — see Scopes below.

/campaigns query parameters

All optional; invalid values fall back to defaults rather than erroring. platform, category, target_platform, tag, language and content_type accept comma-separated multi-values (match any).

A key carries scopes chosen at creation; each route needs one, and a call whose scope the key lacks returns 403 insufficient_scope before anything is metered. write never implies read. Keys issued before scopes existed keep only the public reads they already had (campaigns:read, market:read, account:read) — widening is an explicit re-scope, never automatic.

Costs are per-operation now (most reads 1, an analysis 25) — every metered response reports what it debited and where you stand:

X-Request-Cost                                                  # requests THIS call debited
X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset   # per minute, per key
X-Quota-Limit / X-Quota-Remaining / X-Quota-Reset               # calendar month, UTC
X-Credits-Remaining                                             # prepaid wallet

Only successful responses consume budget — our 5xx and your 401/403/429 (and validation 400s) are free. Writes validate strictly and support an Idempotency-Key; two operations (alert-rule create, analysis run) also spend the main app’s usage credits.

Push instead of poll. Register an https endpoint and subscribe it to campaign.created, campaign.budget_low, campaign.expired or campaign.enriched — ClipRadar POSTs the campaign payload, signed with an HMAC-SHA256 signature you verify on receipt. Up to 10 per account, with retries, auto-disable after repeated failures, and a delivery log for debugging.

curl -X POST "https://clipradar.co/api/v1/me/webhooks" \
  -H "Authorization: Bearer cr_live_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/clipradar","events":["campaign.created"]}'

Full event catalog, the signature-verification recipe (Node & Python), the retry schedule, and the GET /api/v1/events polling alternative for receivers that can’t accept inbound HTTP live in the OpenAPI spec and the repo’s webhooks guide. Requires the webhooks:write scope.

ClipRadar speaks MCP. Drop the server into Claude Desktop, Claude Code or Cursor and ask in plain language — “what TikTok campaigns are paying over $2 per 1K right now, and which still have budget?”

claude mcp add clipradar --env CLIPRADAR_API_KEY=cr_live_YOUR_KEY -- npx -y clipradar-mcp

For Claude Desktop or Cursor, put the same command in the client’s JSON config — full setup in the package README. Six read-only tools (list_campaigns, get_campaign, list_platforms, list_categories, get_market_stats, check_api_usage), your existing key, the same meter — and zero dependencies, so you can read the whole server before you hand it a key.

Every result ends with the budget you have left, and errors arrive as instructions rather than status codes — a 429 comes back as “wait 30 seconds” — so the model paces itself instead of burning your quota in a loop.

Not on an MCP client — ChatGPT, your own agent stack, a script? Two files carry everything a model needs:

Give the agent its own key and tell it, at minimum:

Use the ClipRadar API per https://clipradar.co/skill.md
API key: set in env as CLIPRADAR_API_KEY — send as "Authorization: Bearer <key>".
Check GET /api/v1/usage (free) before batch work; stop on 429.

The free /usage endpoint exists precisely so agents can budget themselves — total_remaining is the number to watch. An llms.txt index is also served at the site root.