{"openapi":"3.1.0","info":{"title":"ClipRadar API","version":"1.1.0","description":"Live pay-per-view clipping campaigns from Whop, ContentRewards and a dozen more platforms — one radar, over REST.\n\nRelease 1.1.0 (additive): the API grew from the public campaign read surface to the full account — saved/hidden campaigns, filter presets, alert rules and channels, the earnings journal and its auto-tracking, connected social accounts, per-account analyses and personalized feeds, the public profile, affiliate earnings and payouts, and outbound webhooks (plus a polling /events feed). Everything from 1.0 behaves identically. Two things every client should know about the new surface: (1) SCOPES — keys now carry scopes and a call can fail 403 insufficient_scope; the fix is to re-scope or reissue the key, not retry. A key issued before scopes existed resolves to the public reads only (campaigns:read, market:read, account:read), NOT the new private-data scopes. (2) COST WEIGHTING — read the X-Request-Cost header: most calls cost 1, but a bulk read or timeseries is 2, a social verify 5, a profit sync 10, and an account analysis 25. Some writes (creating an alert rule, running an analysis) ALSO spend main-app usage credits, a separate meter.\n\nMetered per request. Funding, spent in this order: an active ClipRadar membership includes 500 requests/mo; API subscription tiers add a monthly quota (Dev $9/mo → 6,000 requests/mo @ 60/min; Builder $29/mo → 30,000 requests/mo @ 120/min; Scale $99/mo → 250,000 requests/mo @ 300/min); one-time pay-as-you-go packs add prepaid requests that never expire (Starter $3.5 → 2,000 requests; Growth $12 → 8,000 requests; Bulk $40 → 35,000 requests).\n\nBudget etiquette for clients and AI agents: read the X-Quota-Remaining / X-Credits-Remaining / X-Request-Cost headers on every response, call the free /api/v1/usage to check standing without spending, poll /api/v1/campaigns with `since` (or tail /api/v1/events) instead of re-reading full pages, and back off on 429 per Retry-After. Writes are idempotent when you send an Idempotency-Key. Keys, usage and purchases: https://clipradar.co/dashboard/developer and https://clipradar.co/dashboard/billing#api-plans. Human docs: https://clipradar.co/developers · AI skill file: https://clipradar.co/skill.md"},"servers":[{"url":"https://clipradar.co"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer cr_live_… (create keys at /dashboard/developer). Keys carry SCOPES: each operation states its required scope in its description and an x-required-scope extension, and a key lacking it is rejected 403 insufficient_scope BEFORE any request is metered. This is enforced by ClipRadar, not by an OAuth flow. A key issued before scopes existed resolves to campaigns:read, market:read and account:read only."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"curl-friendly alias for the same key. Same scope enforcement as bearerAuth."}},"x-scopes":[{"id":"campaigns:read","group":"public","label":"Read the campaign feed, detail, facets and exports"},{"id":"market:read","group":"public","label":"Read market stats, trends and radar freshness"},{"id":"leaderboard:read","group":"public","label":"Read the public earnings leaderboard and creator profiles"},{"id":"account:read","group":"public","label":"Read the key's own plan, quota and credit balance"},{"id":"bookmarks:read","group":"account","label":"Read saved and hidden campaigns"},{"id":"presets:read","group":"account","label":"Read saved filter presets"},{"id":"alerts:read","group":"account","label":"Read alert rules, channels and delivery history"},{"id":"profit:read","group":"account","label":"Read the earnings journal, goals and tracked videos"},{"id":"social:read","group":"account","label":"Read connected social accounts"},{"id":"analysis:read","group":"account","label":"Read account analyses and daily picks"},{"id":"profile:read","group":"account","label":"Read the public profile"},{"id":"affiliate:read","group":"account","label":"Read affiliate earnings, referrals and payouts"},{"id":"webhooks:read","group":"account","label":"Read webhook endpoints and delivery history"},{"id":"bookmarks:write","group":"write","label":"Save, hide and unhide campaigns"},{"id":"presets:write","group":"write","label":"Create, rename and delete filter presets"},{"id":"alerts:write","group":"write","label":"Create, edit, delete and test alert rules and channels"},{"id":"profit:write","group":"write","label":"Write earnings entries, goals, video matches and trigger syncs"},{"id":"social:write","group":"write","label":"Connect, verify, update and disconnect social accounts"},{"id":"analysis:write","group":"write","label":"Run account analyses (spends usage credits)"},{"id":"profile:write","group":"write","label":"Update the public profile"},{"id":"affiliate:write","group":"write","label":"Change the affiliate code and request payouts"},{"id":"webhooks:write","group":"write","label":"Create, edit, delete and test webhook endpoints"}],"schemas":{"Campaign":{"type":"object","description":"One clipping campaign as aggregated from its source platform, plus LLM enrichment (category, summary, scores) where available.","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","description":"Source platform slug (see /api/v1/platforms)."},"name":{"type":"string"},"url":{"type":"string","format":"uri","description":"Claim page on the source platform."},"status":{"type":"string","enum":["live","expired"]},"rate_per_1k":{"type":["number","null"],"description":"USD paid per 1,000 views."},"budget_total":{"type":["number","null"],"description":"Total campaign budget in USD, when published."},"budget_remaining_pct":{"type":["number","null"],"description":"Budget remaining, 0–100, when published."},"description":{"type":["string","null"]},"content_types":{"type":["array","null"],"items":{"type":"string"}},"target_platforms":{"type":["array","null"],"items":{"type":"string"},"description":"Where clips must be posted (tiktok, youtube, instagram, x, …)."},"category":{"type":["string","null"],"description":"Primary enriched category (see /api/v1/categories)."},"categories":{"type":["array","null"],"items":{"type":"string"},"description":"All applicable categories, most specific first."},"tags":{"type":["array","null"],"items":{"type":"string"},"description":"Free-form lowercase tags."},"language":{"type":["string","null"],"description":"ISO 639-1 content language, or \"multi\"."},"summary":{"type":["string","null"],"description":"One-line LLM summary."},"opportunity_score":{"type":["number","null"],"description":"0–100 overall opportunity."},"viral_score":{"type":["number","null"],"description":"0–100 viral / clip potential of the campaign's subject."},"viral_reason":{"type":["string","null"],"description":"One-line justification for viral_score."},"requirements":{"type":["object","null"],"description":"Versioned campaign requirements with per-field provenance, conflicts, and deterministic completeness. Legacy rows include honest normalized fallbacks from existing campaign columns.","additionalProperties":true},"ends_at":{"type":["string","null"],"format":"date-time"},"first_seen_at":{"type":"string","format":"date-time","description":"When the radar first saw this campaign — the `since` filter compares against this."},"last_seen_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["missing_key","invalid_key","insufficient_scope","no_active_plan","payment_required","rate_limited","quota_exhausted","invalid_id","validation_failed","invalid_body","body_too_large","method_not_allowed","not_found","conflict","limit_reached","not_a_member","no_signals","idempotency_conflict","request_in_flight","not_configured","internal_error"]},"message":{"type":"string","description":"Human-readable, safe to show a user."},"details":{"description":"Present on validation failures (an array of { field, message }) and on a few richer errors (an object — e.g. { reason } on a social verify, { required, granted } on insufficient_scope). Absent otherwise.","oneOf":[{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}},"required":["field","message"]}},{"type":"object","additionalProperties":true}]}},"required":["code","message"]}},"required":["error"]},"PlatformFacet":{"type":"object","properties":{"platform":{"type":"string"},"campaigns":{"type":"integer"},"top_rate_per_1k":{"type":["number","null"]},"top_rates_per_1k":{"type":"array","items":{"type":"number"},"description":"The highest advertised rates in this slice, descending, at most three. Quote a trimmed figure from these rather than top_rate_per_1k when the number is shown to an end user: a lone maximum can be a single campaign with a tiny budget."},"avg_rate_per_1k":{"type":["number","null"]}}},"CategoryFacet":{"type":"object","properties":{"category":{"type":"string"},"campaigns":{"type":"integer"},"top_rate_per_1k":{"type":["number","null"]},"top_rates_per_1k":{"type":"array","items":{"type":"number"},"description":"The highest advertised rates in this slice, descending, at most three. Quote a trimmed figure from these rather than top_rate_per_1k when the number is shown to an end user: a lone maximum can be a single campaign with a tiny budget."},"avg_rate_per_1k":{"type":["number","null"]}}},"TagFacet":{"type":"object","properties":{"tag":{"type":"string"},"campaigns":{"type":"integer"},"top_rate_per_1k":{"type":["number","null"]},"top_rates_per_1k":{"type":"array","items":{"type":"number"},"description":"The highest advertised rates in this slice, descending, at most three. Quote a trimmed figure from these rather than top_rate_per_1k when the number is shown to an end user: a lone maximum can be a single campaign with a tiny budget."},"avg_rate_per_1k":{"type":["number","null"]}}},"LanguageFacet":{"type":"object","properties":{"language":{"type":"string"},"campaigns":{"type":"integer"},"top_rate_per_1k":{"type":["number","null"]},"top_rates_per_1k":{"type":"array","items":{"type":"number"},"description":"The highest advertised rates in this slice, descending, at most three. Quote a trimmed figure from these rather than top_rate_per_1k when the number is shown to an end user: a lone maximum can be a single campaign with a tiny budget."},"avg_rate_per_1k":{"type":["number","null"]}}},"ContentTypeFacet":{"type":"object","properties":{"content_type":{"type":"string"},"campaigns":{"type":"integer"},"top_rate_per_1k":{"type":["number","null"]},"top_rates_per_1k":{"type":"array","items":{"type":"number"},"description":"The highest advertised rates in this slice, descending, at most three. Quote a trimmed figure from these rather than top_rate_per_1k when the number is shown to an end user: a lone maximum can be a single campaign with a tiny budget."},"avg_rate_per_1k":{"type":["number","null"]}}},"TargetPlatformFacet":{"type":"object","properties":{"target_platform":{"type":"string"},"campaigns":{"type":"integer"},"top_rate_per_1k":{"type":["number","null"]},"top_rates_per_1k":{"type":"array","items":{"type":"number"},"description":"The highest advertised rates in this slice, descending, at most three. Quote a trimmed figure from these rather than top_rate_per_1k when the number is shown to an end user: a lone maximum can be a single campaign with a tiny budget."},"avg_rate_per_1k":{"type":["number","null"]}}},"SimilarCampaign":{"allOf":[{"$ref":"#/components/schemas/Campaign"},{"type":"object","properties":{"similarity":{"type":"number","description":"0–1, 2dp — how close to the reference this campaign is."},"matched":{"type":"object","description":"Exactly which fields overlapped, so the ranking is explainable.","properties":{"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"target_platforms":{"type":"array","items":{"type":"string"}},"rate":{"type":"boolean","description":"True when the two rates are within $0.50/1k."}}}}}]},"Timeseries":{"type":"object","properties":{"range":{"type":"string","enum":["7d","30d","90d"]},"bucket":{"type":"string","enum":["day","week"]},"from":{"type":"string","description":"First day the series covers (YYYY-MM-DD, inclusive)."},"to":{"type":"string","description":"Last day the series covers (YYYY-MM-DD, inclusive)."},"points":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string","description":"Bucket start — the day, or the Monday of the week (YYYY-MM-DD)."},"new_campaigns":{"type":"integer"},"avg_rate_per_1k":{"type":["number","null"]},"top_rate_per_1k":{"type":["number","null"]},"top_rates_per_1k":{"type":"array","items":{"type":"number"},"description":"The highest advertised rates in this slice, descending, at most three. Quote a trimmed figure from these rather than top_rate_per_1k when the number is shown to an end user: a lone maximum can be a single campaign with a tiny budget."},"expired_campaigns":{"type":"integer"}}}},"totals":{"type":"object","properties":{"new_campaigns":{"type":"integer"},"previous_new_campaigns":{"type":["integer","null"],"description":"Same-length window immediately before this one; null when there's no baseline."},"pct_change":{"type":["number","null"],"description":"Signed % change vs the previous window; null when no baseline."}}},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"campaigns":{"type":"integer"},"avg_rate_per_1k":{"type":["number","null"]}}}}}},"RadarStatus":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when no source is stale."},"stale_after_hours":{"type":"integer"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"ok":{"type":"boolean","description":"Whether the latest run succeeded."},"found":{"type":["integer","null"]},"upserted":{"type":["integer","null"]},"duration_ms":{"type":["integer","null"]},"last_run_at":{"type":"string","format":"date-time"},"stale":{"type":"boolean","description":"No SUCCESSFUL run inside the freshness window."}}}},"totals":{"type":"object","properties":{"live_campaigns":{"type":"integer"},"new_last_24h":{"type":"integer"},"awaiting_enrichment":{"type":"integer"}}},"checked_at":{"type":"string","format":"date-time"}}},"Estimate":{"type":"object","properties":{"views":{"type":"number","description":"The view count the payout was projected for."},"campaign_id":{"type":["string","null"],"description":"The campaign the inputs came from (campaign style), else null."},"inputs":{"type":"object","properties":{"rate_per_1k":{"type":["number","null"]},"budget_total":{"type":["number","null"]},"budget_remaining_pct":{"type":["number","null"]},"max_payout":{"type":["number","null"]},"per_clip_cap":{"type":["number","null"]},"remaining_budget":{"type":["number","null"],"description":"Remaining budget in USD the estimate is capped at, when derivable."}}},"payout":{"type":"number","description":"Final payout in USD after any cap."},"raw_payout":{"type":"number","description":"Uncapped payout (views/1000 × rate) — what a cap trimmed, if any."},"capped_by":{"type":["string","null"],"enum":["budget","max-payout","per-clip",null],"description":"The binding cap, or null."},"unknown_rate":{"type":"boolean","description":"True when no rate was available, so the payout is 0 and not meaningful."}}},"Usage":{"type":"object","description":"The free /usage snapshot — never metered.","properties":{"plan":{"type":"object","properties":{"tier":{"type":["string","null"],"enum":["dev","builder","scale",null]},"tier_name":{"type":["string","null"]},"member_allowance_active":{"type":"boolean"}}},"month":{"type":"object","properties":{"quota":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"resets_at":{"type":"string","format":"date-time"}}},"credits":{"type":"object","properties":{"remaining":{"type":"integer"}}},"rate_limit_per_minute":{"type":"integer"},"total_remaining":{"type":"integer"},"scopes":{"type":"array","items":{"type":"string"},"description":"The scopes this key carries — so a holder can discover what it may do without probing endpoints and eating 403s."}}},"Me":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"},"scopes":{"type":"array","items":{"type":"string"}}}},"plan":{"type":"object","properties":{"member_active":{"type":"boolean"},"tier":{"type":["string","null"]},"tier_name":{"type":["string","null"]},"current_period_end":{"type":["string","null"],"format":"date-time"}}},"month":{"type":"object","properties":{"quota":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"resets_at":{"type":"string","format":"date-time"}}},"credits_remaining":{"type":"integer"},"rate_limit_per_minute":{"type":"integer"},"usage_by_day":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"YYYY-MM-DD (UTC)."},"requests":{"type":"integer"}}}}}},"SavedCampaign":{"allOf":[{"$ref":"#/components/schemas/Campaign"},{"type":"object","properties":{"saved_at":{"type":"string","format":"date-time"}}}]},"HiddenRef":{"type":"object","properties":{"campaign_id":{"type":"string","format":"uuid"},"hidden_at":{"type":"string","format":"date-time"}}},"Preset":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"state":{"type":"object","description":"An atomic { filters, sort } blob — a PATCH replacing it must send BOTH halves.","properties":{"filters":{"$ref":"#/components/schemas/FeedFilters"},"sort":{"type":"string","enum":["rate","score","viral","newest","budget"]}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"FeedFilters":{"type":"object","description":"The dashboard feed's filter shape (used by presets and webhook subscriptions). Unknown keys are dropped by the sanitizer.","properties":{"query":{"type":"string"},"exclude":{"type":"string","description":"Comma-separated terms to hide."},"minRate":{"type":"number"},"minBudget":{"type":"number"},"minScore":{"type":"number"},"minViral":{"type":"number"},"minBudgetLeftPct":{"type":"number"},"endingWithinH":{"type":"number"},"sources":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}},"targets":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"showExpired":{"type":"boolean"},"newToday":{"type":"boolean"},"hasBudget":{"type":"boolean"}}},"AlertFilters":{"type":"object","description":"The alert engine's filter superset (NOT the dashboard's FeedFilters). Out-of-range/wrong-typed fields are coerced rather than rejected.","properties":{"minRate":{"type":"number","description":"Minimum $/1K; 0 = any."},"minScore":{"type":"number","description":"Minimum opportunity score; 0 = any."},"minViral":{"type":"number","description":"Minimum viral score, 0–100; 0 = any."},"keywords":{"type":"array","items":{"type":"string"},"description":"Substrings matched against name + description + tags (OR)."},"excludeKeywords":{"type":"array","items":{"type":"string"},"description":"Substrings that must NOT appear (any match rejects)."},"sources":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}},"targets":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"budgetThresholdPct":{"type":"number","description":"budget_low fires when budget_remaining_pct drops to or below this."}}},"AlertRule":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"enabled":{"type":"boolean"},"events":{"type":"array","items":{"type":"string","enum":["new_campaign","budget_low","campaign_expired"]}},"filters":{"$ref":"#/components/schemas/AlertFilters"},"channel_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"frequency":{"type":"string","enum":["instant","daily"]},"digest_hour":{"type":"integer","minimum":0,"maximum":23},"cooldown_minutes":{"type":"integer","minimum":0,"maximum":1440},"max_per_day":{"type":"integer","minimum":1,"maximum":100},"quiet_hours":{"type":["object","null"],"properties":{"start":{"type":"integer"},"end":{"type":"integer"}}},"template":{"type":["string","null"]},"tone":{"type":"string","enum":["clean","serious","fun","hype"]},"last_sent_at":{"type":["string","null"],"format":"date-time"},"last_digest_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AlertChannel":{"type":"object","description":"A delivery channel. A webhook channel's signing `secret` is NEVER returned — `has_secret` reports whether one is set.","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["telegram","discord","slack","webhook","email"]},"name":{"type":"string"},"config":{"type":"object","description":"Per-type addressing (chat_id / webhook_url / url / address). The webhook `secret` is redacted out.","additionalProperties":true},"has_secret":{"type":"boolean"},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AlertDelivery":{"type":"object","properties":{"id":{"type":"integer"},"rule_id":{"type":["string","null"],"format":"uuid"},"channel_id":{"type":["string","null"],"format":"uuid"},"rule_name":{"type":["string","null"]},"channel_label":{"type":["string","null"]},"event":{"type":"string","enum":["new_campaign","budget_low","campaign_expired","digest","test"]},"subject":{"type":"string"},"ok":{"type":"boolean"},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"AlertPreview":{"type":"object","properties":{"live_total":{"type":"integer","description":"Live campaigns in the pool the preview ran against."},"match_count":{"type":"integer","description":"How many of them the filters match right now."},"sample":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}},"events":{"type":"array","items":{"type":"string"}}}},"ProfitEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"entry_date":{"type":"string","description":"YYYY-MM-DD."},"amount":{"type":"number","description":"USD, 2dp."},"campaign_name":{"type":"string"},"platform":{"type":"string","enum":["tiktok","instagram","youtube","x","other"]},"views":{"type":["integer","null"]},"notes":{"type":["string","null"]},"source":{"type":"string","enum":["manual","auto"],"description":"Only 'manual' rows may be created or edited over the API."},"campaign_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProfitSummary":{"type":"object","description":"The monthly rollup (from lib/profit/summary) plus goal progress. `goal_cents` is whole cents by design.","properties":{"month":{"type":"string","description":"YYYY-MM."},"total":{"type":"number"},"entries":{"type":"integer"},"best_day":{"type":"object","additionalProperties":true},"streak":{"type":"integer"},"prev_month_total":{"type":"number"},"goal_cents":{"type":["integer","null"]},"goal_progress":{"type":["number","null"],"description":"total / goal, clamped to [0,1]; null when no goal."},"goal_reached":{"type":"boolean"}},"additionalProperties":true},"ProfitGoal":{"type":"object","properties":{"month":{"type":"string","description":"First day of the target month, YYYY-MM-01."},"amount_cents":{"type":"integer","description":"Whole cents (> 0). Named for its unit — do not treat as dollars."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"TrackedVideo":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string"},"handle":{"type":"string"},"external_id":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"posted_at":{"type":["string","null"],"format":"date-time"},"views":{"type":"integer"},"likes":{"type":["integer","null"]},"views_credited":{"type":"integer"},"campaign_id":{"type":["string","null"],"format":"uuid"},"match_status":{"type":"string","enum":["pending","matched","unmatched","ignored"]},"match_confidence":{"type":["number","null"]},"match_reason":{"type":["string","null"]},"suggested_campaign_id":{"type":["string","null"],"format":"uuid"},"suggested_confidence":{"type":["number","null"]},"matched_at":{"type":["string","null"],"format":"date-time"},"last_synced_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProfitSyncState":{"type":"object","properties":{"settings":{"type":"object","properties":{"enabled":{"type":"boolean"},"interval_hours":{"type":"integer","enum":[24,12,6,3],"description":"Hours between scheduled checks. Faster uses proportionally more tracking capacity per account (each check re-reads every tracked account)."},"last_synced_at":{"type":["string","null"],"format":"date-time"},"last_manual_sync_at":{"type":["string","null"],"format":"date-time","description":"Historical: manual syncing was removed and nothing writes this any more."}}},"recent_runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"initiated_by":{"type":"string","enum":["cron","manual"]},"ok":{"type":"boolean"},"accounts_checked":{"type":["integer","null"]},"videos_seen":{"type":["integer","null"]},"videos_matched":{"type":["integer","null"]},"entries_written":{"type":["integer","null"]},"amount_added":{"type":["number","null"]},"error":{"type":["string","null"]},"match_error":{"type":["string","null"]},"duration_ms":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"}}}},"tracking":{"type":"object","properties":{"ready":{"type":"boolean"},"capacity":{"type":"integer"},"accounts_funded":{"type":"integer"},"accounts_total":{"type":"integer"}}}}},"SocialAccount":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["youtube","tiktok","instagram","x"]},"handle":{"type":"string"},"status":{"type":"string","enum":["pending","verified"]},"verified_at":{"type":["string","null"],"format":"date-time"},"is_primary":{"type":"boolean"},"niches":{"type":"array","items":{"type":"string"}},"autotrack_enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Analysis":{"type":"object","properties":{"social_account_id":{"type":"string","format":"uuid"},"platform":{"type":"string"},"handle":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"keywords":{"type":"array","items":{"type":"string"}},"confidence":{"type":["number","null"]},"headline":{"type":["string","null"]},"audience":{"type":["string","null"]},"advice":{"type":["string","null"]},"model":{"type":["string","null"]},"analysis_version":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"Pick":{"type":"object","properties":{"social_account_id":{"type":"string","format":"uuid"},"rank":{"type":"integer"},"score":{"type":"number"},"reason":{"type":["string","null"]},"source":{"type":"string","enum":["analysis","declared"]},"campaign":{"$ref":"#/components/schemas/Campaign"}}},"ForYouItem":{"type":"object","properties":{"campaign":{"$ref":"#/components/schemas/Campaign"},"score":{"type":"number","description":"Blended 0–100."},"match_score":{"type":["number","null"]},"account_id":{"type":["string","null"],"format":"uuid"},"account_handle":{"type":["string","null"]},"reason":{"type":["string","null"]},"parts":{"type":"object","properties":{"match":{"type":"number"},"viral":{"type":"number"},"rate":{"type":"number"},"budget_left":{"type":"number"}}}}},"RecommendationItem":{"type":"object","properties":{"campaign":{"$ref":"#/components/schemas/Campaign"},"score":{"type":"number"},"reason":{"type":"string"},"matched_categories":{"type":"array","items":{"type":"string"}},"matched_keywords":{"type":"array","items":{"type":"string"}}}},"MyProfile":{"type":"object","properties":{"username":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"pnl_public":{"type":"boolean","description":"Whether earnings show WITH identity on the leaderboard and public profile."},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"LeaderboardRow":{"type":"object","description":"One board row — NO user id. Anonymized rows carry is_public:false and null identity.","properties":{"rank":{"type":"integer"},"is_public":{"type":"boolean"},"is_me":{"type":"boolean","description":"The caller's own row — lets a client say \"you\" without any id leaving."},"username":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"total":{"type":"number"},"days":{"type":"integer"},"entries":{"type":"integer"},"top_platform":{"type":["string","null"]}}},"MyRank":{"type":"object","properties":{"rank":{"type":"integer"},"total":{"type":"number"},"days":{"type":"integer"},"entries":{"type":"integer"},"participants":{"type":"integer"},"top_percent":{"type":["number","null"]},"per_day_average":{"type":"number"}}},"RisingStar":{"type":"object","description":"A climber — always a PUBLIC member, never a user id.","properties":{"is_me":{"type":"boolean"},"username":{"type":"string"},"avatar_url":{"type":["string","null"]},"current":{"type":"number"},"previous":{"type":"number"},"delta":{"type":"number"},"growth_pct":{"type":["number","null"]},"top_platform":{"type":["string","null"]}}},"ProfileStats":{"type":"object","properties":{"username":{"type":"string"},"avatar_url":{"type":["string","null"]},"member_since":{"type":"string","format":"date-time"},"total_all":{"type":"number"},"total_30d":{"type":"number"},"total_7d":{"type":"number"},"days":{"type":"integer"},"entries":{"type":"integer"},"top_platform":{"type":["string","null"]},"best_day":{"type":"number"},"rank_30d":{"type":["integer","null"]}}},"AffiliateSummary":{"type":"object","properties":{"code":{"type":["string","null"],"description":"The shareable /r/<code> slug."},"clicks":{"type":"integer"},"referral_count":{"type":"integer"},"paying_referral_count":{"type":"integer"},"commission_rate":{"type":"number","description":"Current commission rate as a fraction (0.14 / 0.17 / 0.24)."},"tier":{"type":"object","properties":{"tier":{"type":"integer"},"name":{"type":"string"},"label":{"type":"string"}}},"commissions":{"type":"object","properties":{"lifetime":{"type":"number"},"pending":{"type":"number"},"reversed":{"type":"number"},"available":{"type":"number"},"available_cents":{"type":"integer"}}},"referrals":{"type":"array","description":"Anonymized: signup month + a converted flag only. No user id or email.","items":{"type":"object","properties":{"signup_month":{"type":"string","description":"YYYY-MM."},"converted":{"type":"boolean"}}}}}},"PayoutRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount_cents":{"type":"integer"},"method":{"type":"string","enum":["usdt_trc20","usdt_erc20","btc","eth"]},"address":{"type":"string","description":"Redacted to its last 4 characters (\"…abcd\") — the full address never leaves a read."},"status":{"type":"string"},"admin_note":{"type":["string","null"]},"requested_at":{"type":"string","format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"}}},"Webhook":{"type":"object","description":"A webhook endpoint. The signing `secret` is redacted to `secret_hint` in lists; the full `secret` is returned only on create and on the single-webhook GET.","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string","enum":["campaign.created","campaign.expired","campaign.budget_low","campaign.enriched"]}},"filters":{"$ref":"#/components/schemas/FeedFilters"},"enabled":{"type":"boolean"},"secret_hint":{"type":"string","description":"`whsec_…abcd` — enough to disambiguate, useless for signing."},"consecutive_failures":{"type":"integer"},"disabled_reason":{"type":["string","null"]},"last_delivered_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WebhookWithSecret":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","description":"The full HMAC signing secret — shown only here (create) and on GET /me/webhooks/{id}. Store it."}}}]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"webhook_id":{"type":"string","format":"uuid"},"event":{"type":"string"},"event_id":{"type":["integer","null"]},"status":{"type":"string","enum":["pending","delivered","failed"]},"attempts":{"type":"integer"},"response_status":{"type":["integer","null"]},"last_error":{"type":["string","null"]},"next_attempt_at":{"type":"string","format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"ApiEvent":{"type":"object","properties":{"id":{"type":"integer","description":"The resume cursor — pass the page's last id as ?since_id=."},"event":{"type":"string","enum":["campaign.created","campaign.expired","campaign.budget_low","campaign.enriched"]},"campaign_id":{"type":["string","null"],"format":"uuid"},"payload":{"$ref":"#/components/schemas/Campaign"},"created_at":{"type":"string","format":"date-time"}}},"DiscoveryIndex":{"type":"object","description":"The self-describing catalog served at GET /api/v1 — every endpoint, scope and price, rendered from the enforcing constants.","properties":{"name":{"type":"string"},"version":{"type":"string"},"docs_url":{"type":"string","format":"uri"},"openapi_url":{"type":"string","format":"uri"},"skill_url":{"type":"string","format":"uri"},"endpoints":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"},"scope":{"type":["string","null"]},"cost":{"type":"integer"},"summary":{"type":"string"},"spends_usage_credits":{"type":"boolean"}}}},"endpoint_groups":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string"},"endpoints":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"scopes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"group":{"type":"string"},"label":{"type":"string"}}}},"auth":{"type":"object","properties":{"header":{"type":"string"},"alternate_header":{"type":"string"},"key_format":{"type":"string"}}},"meters":{"type":"object","properties":{"headers":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}},"pricing":{"type":"object","properties":{"member_allowance":{"type":"integer"},"tiers":{"type":"array","items":{"type":"object","additionalProperties":true}},"packs":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}},"paths":{"/api/v1":{"get":{"operationId":"getIndex","summary":"Endpoint catalog, scope list and cost table.","description":"The first call an integrator or an agent holding a key makes: every endpoint with its scope and cost, the scope catalog, how to authenticate, the meter headers to watch, and the price list. Free, unauthenticated, cacheable.\n\nFree — this call is never metered.","security":[],"x-request-cost":0,"responses":{"200":{"description":"The self-describing catalog.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DiscoveryIndex"}},"required":["data"]}}}}}}},"/api/v1/ping":{"get":{"operationId":"ping","summary":"Connectivity and clock check.","description":"Free — this call is never metered.","security":[],"x-request-cost":0,"responses":{"200":{"description":"The API is up.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"},"name":{"type":"string"},"version":{"type":"string"},"time":{"type":"string","format":"date-time"}}}},"required":["data"]}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApi","summary":"OpenAPI 3.1 description of this API.","description":"This document. Free, no key.\n\nFree — this call is never metered.","security":[],"x-request-cost":0,"responses":{"200":{"description":"The OpenAPI 3.1 description.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}},"required":["data"]}}}}}}},"/api/v1/usage":{"get":{"operationId":"getUsage","summary":"Plan, quota, credits and rate limit — never metered.","description":"Never consumes a request. Check before batch jobs; alert when total_remaining runs low. Reports the key's `scopes` too.\n\nFree — this call is never metered.","x-request-cost":0,"responses":{"200":{"description":"Current standing across both funding pools, plus this key's scopes.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Usage"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns":{"get":{"operationId":"listCampaigns","summary":"Search, filter and sort the campaign feed.","description":"The multi-select dimensions (platform, category, target_platform, tag, language, content_type) accept a comma-separated list — OR within a group, AND across groups. `since` is the polling primitive. `cursor` keyset-pages sort=newest|oldest only.\n\nCosts 1 request from your plan.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":1,"parameters":[{"name":"status","in":"query","required":false,"description":"Campaign state.","schema":{"type":"string","enum":["live","expired","all"],"default":"live"}},{"name":"platform","in":"query","required":false,"description":"Source platform slug(s) — comma-separated for OR. Discover values via /api/v1/platforms.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Enriched category/ies — comma-separated for OR. Discover values via /api/v1/categories.","schema":{"type":"string"}},{"name":"target_platform","in":"query","required":false,"description":"Where clips must be posted (tiktok, youtube, …) — comma-separated for OR.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Enrichment tag(s) — comma-separated for OR.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Content language(s) (ISO 639-1, or \"multi\") — comma-separated for OR.","schema":{"type":"string"}},{"name":"content_type","in":"query","required":false,"description":"Accepted content type(s) — comma-separated for OR.","schema":{"type":"string"}},{"name":"min_rate","in":"query","required":false,"description":"Only campaigns paying at/above this $/1K.","schema":{"type":"number"}},{"name":"max_rate","in":"query","required":false,"description":"Only campaigns paying at/below this $/1K.","schema":{"type":"number"}},{"name":"min_score","in":"query","required":false,"description":"Only campaigns with opportunity_score at/above this (0–100).","schema":{"type":"number"}},{"name":"min_viral","in":"query","required":false,"description":"Only campaigns with viral_score at/above this (0–100).","schema":{"type":"number"}},{"name":"min_budget","in":"query","required":false,"description":"Only campaigns with a total budget at/above this (USD).","schema":{"type":"number"}},{"name":"min_budget_left_pct","in":"query","required":false,"description":"Only campaigns with budget_remaining_pct at/above this (0–100).","schema":{"type":"number"}},{"name":"ending_within_h","in":"query","required":false,"description":"Only campaigns whose end date falls within this many hours from now.","schema":{"type":"number"}},{"name":"has_budget","in":"query","required":false,"description":"Only campaigns that publish a total budget.","schema":{"type":"boolean"}},{"name":"new_today","in":"query","required":false,"description":"Only campaigns first seen in the last 24 hours.","schema":{"type":"boolean"}},{"name":"since","in":"query","required":false,"description":"Only campaigns first seen at/after this instant (ISO 8601) — the polling primitive.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"Only campaigns first seen at/before this instant (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"q","in":"query","required":false,"description":"Case-insensitive name search.","schema":{"type":"string"}},{"name":"exclude","in":"query","required":false,"description":"Comma-separated terms; a campaign mentioning any of them in its name/summary/description is dropped.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated subset of the public campaign columns to return; `id` is always included and unknown names are dropped.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Order of results.","schema":{"type":"string","enum":["newest","oldest","rate","budget","viral","score","ends_soon"],"default":"newest"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"Page start.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"cursor","in":"query","required":false,"description":"Opaque keyset page token from a previous response's meta.next_cursor. Supported ONLY for sort=newest|oldest — any other sort with a cursor is 400 validation_failed. A malformed cursor is ignored (falls back to page one); a cursor wins over offset when both are sent.","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching campaigns.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Total matches across all pages."},"limit":{"type":"integer"},"offset":{"type":"integer"},"returned":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Keyset token for the next page under this sort, or null when exhausted / the sort doesn't support cursors."}}}},"required":["data"]}}}},"400":{"description":"validation_failed — a cursor was sent with a sort other than newest/oldest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/bulk":{"get":{"operationId":"getCampaignsBulk","summary":"Fetch up to 100 campaigns by id in one call.","description":"Strict read: the caller named exact ids, so a malformed or oversized id list is a 400 rather than a silent drop. Ids that simply don't exist come back in meta.missing.\n\nCosts 50 requests from your plan.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":50,"parameters":[{"name":"ids","in":"query","required":false,"description":"1..100 comma-separated campaign UUIDs (required).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated subset of the public campaign columns to return; `id` is always included and unknown names are dropped.","schema":{"type":"string"}}],"responses":{"200":{"description":"The resolved campaigns.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}},"meta":{"type":"object","properties":{"requested":{"type":"integer"},"returned":{"type":"integer"},"missing":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ids that matched no row."}}}},"required":["data"]}}}},"400":{"description":"validation_failed — no ids, too many ids, or a non-UUID in the list (error.details.invalid lists them).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/export":{"get":{"operationId":"exportCampaigns","summary":"Export the filtered feed as CSV (up to 5,000 rows).","description":"The same filters and sort as GET /api/v1/campaigns, as a CSV download (up to 5,000 rows; limit/offset/cursor are ignored). `fields` selects and orders the columns.\n\nMetered per row: 1 request per campaign returned, plus 0.5 per campaign for each filter applied, with a floor of 5 — so a 5,000-row unfiltered export costs 5,000, and the same export under 3 filters costs 12,500. The cost is settled before the response is produced, so an unaffordable call is refused with 429 quota_exhausted rather than partially billed; X-Request-Cost carries the exact debit.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":5,"x-request-cost-dynamic":"per row","x-request-cost-minimum":5,"parameters":[{"name":"status","in":"query","required":false,"description":"Campaign state.","schema":{"type":"string","enum":["live","expired","all"],"default":"live"}},{"name":"platform","in":"query","required":false,"description":"Source platform slug(s) — comma-separated for OR. Discover values via /api/v1/platforms.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Enriched category/ies — comma-separated for OR. Discover values via /api/v1/categories.","schema":{"type":"string"}},{"name":"target_platform","in":"query","required":false,"description":"Where clips must be posted (tiktok, youtube, …) — comma-separated for OR.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Enrichment tag(s) — comma-separated for OR.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Content language(s) (ISO 639-1, or \"multi\") — comma-separated for OR.","schema":{"type":"string"}},{"name":"content_type","in":"query","required":false,"description":"Accepted content type(s) — comma-separated for OR.","schema":{"type":"string"}},{"name":"min_rate","in":"query","required":false,"description":"Only campaigns paying at/above this $/1K.","schema":{"type":"number"}},{"name":"max_rate","in":"query","required":false,"description":"Only campaigns paying at/below this $/1K.","schema":{"type":"number"}},{"name":"min_score","in":"query","required":false,"description":"Only campaigns with opportunity_score at/above this (0–100).","schema":{"type":"number"}},{"name":"min_viral","in":"query","required":false,"description":"Only campaigns with viral_score at/above this (0–100).","schema":{"type":"number"}},{"name":"min_budget","in":"query","required":false,"description":"Only campaigns with a total budget at/above this (USD).","schema":{"type":"number"}},{"name":"min_budget_left_pct","in":"query","required":false,"description":"Only campaigns with budget_remaining_pct at/above this (0–100).","schema":{"type":"number"}},{"name":"ending_within_h","in":"query","required":false,"description":"Only campaigns whose end date falls within this many hours from now.","schema":{"type":"number"}},{"name":"has_budget","in":"query","required":false,"description":"Only campaigns that publish a total budget.","schema":{"type":"boolean"}},{"name":"new_today","in":"query","required":false,"description":"Only campaigns first seen in the last 24 hours.","schema":{"type":"boolean"}},{"name":"since","in":"query","required":false,"description":"Only campaigns first seen at/after this instant (ISO 8601) — the polling primitive.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"Only campaigns first seen at/before this instant (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"q","in":"query","required":false,"description":"Case-insensitive name search.","schema":{"type":"string"}},{"name":"exclude","in":"query","required":false,"description":"Comma-separated terms; a campaign mentioning any of them in its name/summary/description is dropped.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated subset of the public campaign columns to return; `id` is always included and unknown names are dropped.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Order of results.","schema":{"type":"string","enum":["newest","oldest","rate","budget","viral","score","ends_soon"],"default":"newest"}}],"responses":{"200":{"description":"A text/csv attachment (clipradar-campaigns-<ISO date>.csv).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}":{"get":{"operationId":"getCampaign","summary":"One campaign by id.","description":"Costs 3 requests from your plan.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":3,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated subset of the public campaign columns to return; `id` is always included and unknown names are dropped.","schema":{"type":"string"}}],"responses":{"200":{"description":"The campaign.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Campaign"}},"required":["data"]}}}},"400":{"description":"invalid_id — not a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no campaign with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/similar":{"get":{"operationId":"getSimilarCampaigns","summary":"Campaigns most like this one, ranked.","description":"A deterministic blend of shared categories (highest weight), tags, target platforms and rate proximity. Each result carries `similarity` and a `matched` object. The reference and non-live campaigns are excluded.\n\nCosts 2 requests from your plan.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":2,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"1..50 (default 10).","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"fields","in":"query","required":false,"description":"Comma-separated subset of the public campaign columns to return; `id` is always included and unknown names are dropped.","schema":{"type":"string"}}],"responses":{"200":{"description":"Similar campaigns, best first.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SimilarCampaign"}},"meta":{"type":"object","properties":{"returned":{"type":"integer"}}}},"required":["data"]}}}},"400":{"description":"invalid_id — not a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no campaign with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/platforms":{"get":{"operationId":"listPlatforms","summary":"Source platforms with counts and rate stats.","description":"Costs 1 request from your plan.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":1,"responses":{"200":{"description":"Platforms by live campaign count.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlatformFacet"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","summary":"Enriched categories with counts and rate stats.","description":"Costs 1 request from your plan.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":1,"responses":{"200":{"description":"Categories by live campaign count.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CategoryFacet"}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tags":{"get":{"operationId":"listTags","summary":"Enrichment tags with counts and rate stats.","description":"Costs 1 request from your plan.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":1,"responses":{"200":{"description":"Tags by live campaign count.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TagFacet"}},"meta":{"type":"object","properties":{"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/languages":{"get":{"operationId":"listLanguages","summary":"Content languages with counts and rate stats.","description":"Costs 1 request from your plan.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":1,"responses":{"200":{"description":"Languages by live campaign count.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LanguageFacet"}},"meta":{"type":"object","properties":{"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/content-types":{"get":{"operationId":"listContentTypes","summary":"Accepted content types with counts and rate stats.","description":"Costs 1 request from your plan.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":1,"responses":{"200":{"description":"Content types by live campaign count.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContentTypeFacet"}},"meta":{"type":"object","properties":{"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/target-platforms":{"get":{"operationId":"listTargetPlatforms","summary":"Where clips may be posted, with counts and rate stats.","description":"Costs 1 request from your plan.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":1,"responses":{"200":{"description":"Target platforms by live campaign count (folded, hidden ones removed).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TargetPlatformFacet"}},"meta":{"type":"object","properties":{"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stats":{"get":{"operationId":"getStats","summary":"Market aggregates across the live radar.","description":"Costs 1 request from your plan.\n\nRequired scope: `market:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"market:read","x-request-cost":1,"responses":{"200":{"description":"Market-level numbers (same as the landing page).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"live_campaigns":{"type":"integer"},"platforms":{"type":"integer"},"new_drops_24h":{"type":"integer","description":"Campaigns first seen in the last 24 hours (rolling window)."},"new_drops_today":{"type":"integer","deprecated":true,"description":"Deprecated alias for new_drops_24h. Was a UTC calendar day; now the same rolling 24-hour count."},"top_rate_per_1k":{"type":["number","null"]},"top_rates_per_1k":{"type":"array","items":{"type":"number"},"description":"The highest advertised rates in this slice, descending, at most three. Quote a trimmed figure from these rather than top_rate_per_1k when the number is shown to an end user: a lone maximum can be a single campaign with a tiny budget."},"headline_rate_per_1k":{"type":["number","null"]},"live_platforms":{"type":"array","items":{"type":"string"}}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stats/timeseries":{"get":{"operationId":"getStatsTimeseries","summary":"New drops, rate trend and category mix over time.","description":"New drops, the rate curve and the category mix across a window, plus the change vs the previous window of equal length.\n\nCosts 2 requests from your plan.\n\nRequired scope: `market:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"market:read","x-request-cost":2,"parameters":[{"name":"range","in":"query","required":false,"description":"Window.","schema":{"type":"string","enum":["7d","30d","90d"],"default":"7d"}},{"name":"bucket","in":"query","required":false,"description":"Bucket grain (default: day for 7d/30d, week for 90d).","schema":{"type":"string","enum":["day","week"]}}],"responses":{"200":{"description":"The market over time.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Timeseries"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/status":{"get":{"operationId":"getStatus","summary":"Radar freshness — last successful ingest per source.","description":"Tells 'no new campaigns' apart from 'the scraper is down': the most recent ingest per source with a `stale` flag, plus live/new/unenriched totals.\n\nCosts 1 request from your plan.\n\nRequired scope: `market:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"market:read","x-request-cost":1,"responses":{"200":{"description":"Radar freshness.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RadarStatus"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/events":{"get":{"operationId":"listEvents","summary":"Recent campaign events — poll instead of using webhooks.","description":"The polling alternative to webhooks — returns only the deltas. Events come back OLDEST-LAST so since_id paging is natural: take meta.last_event_id and pass it as ?since_id=.\n\nCosts 1 request from your plan.\n\nRequired scope: `market:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"market:read","x-request-cost":1,"parameters":[{"name":"since_id","in":"query","required":false,"description":"Only events with a higher id — the resume cursor (preferred).","schema":{"type":"integer"}},{"name":"since","in":"query","required":false,"description":"Only events at/after this instant (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"event","in":"query","required":false,"description":"Restrict to one type.","schema":{"type":"string","enum":["campaign.created","campaign.expired","campaign.budget_low","campaign.enriched"]}},{"name":"limit","in":"query","required":false,"description":"1..100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Recent events, oldest-last.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiEvent"}},"meta":{"type":"object","properties":{"returned":{"type":"integer"},"limit":{"type":"integer"},"last_event_id":{"type":"integer","description":"The resume cursor; 0 when the page is empty."}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/estimate":{"get":{"operationId":"getEstimate","summary":"Projected payout for a view count, budget-capped.","description":"Two calling styles: ?campaign_id=<uuid>&views=… loads the campaign and derives rate/budget; or ?rate_per_1k=…&views=… (with optional budget_total, budget_remaining_pct, max_payout, per_clip_cap caps) for a hypothetical. Mixing an id with explicit economics is a 400.\n\nCosts 1 request from your plan.\n\nRequired scope: `campaigns:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"campaigns:read","x-request-cost":1,"parameters":[{"name":"views","in":"query","required":false,"description":"The view count to project a payout for (required, ≥ 0).","schema":{"type":"number"}},{"name":"campaign_id","in":"query","required":false,"description":"A campaign UUID — mutually exclusive with the explicit economics params.","schema":{"type":"string","format":"uuid"}},{"name":"rate_per_1k","in":"query","required":false,"description":"Explicit $/1K (required in the explicit style).","schema":{"type":"number"}},{"name":"budget_total","in":"query","required":false,"description":"Optional total-budget cap (USD).","schema":{"type":"number"}},{"name":"budget_remaining_pct","in":"query","required":false,"description":"Optional remaining-budget cap (0–100).","schema":{"type":"number"}},{"name":"max_payout","in":"query","required":false,"description":"Optional per-campaign payout cap (USD).","schema":{"type":"number"}},{"name":"per_clip_cap","in":"query","required":false,"description":"Optional per-clip payout cap (USD).","schema":{"type":"number"}}],"responses":{"200":{"description":"The projected payout and the figures behind it.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Estimate"}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_id — missing/negative views, a non-UUID campaign_id, or mixed calling styles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — campaign style with an id that matches no campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/leaderboard":{"get":{"operationId":"getLeaderboard","summary":"Public earnings leaderboard by period and platform.","description":"MEMBERS-ONLY (403 not_a_member otherwise). Only members with a public profile are identified; everyone else still ranks but anonymized, and NO user id ever appears.\n\nCosts 2 requests from your plan.\n\nRequired scope: `leaderboard:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"leaderboard:read","x-request-cost":2,"parameters":[{"name":"period","in":"query","required":false,"description":"Window.","schema":{"type":"string","enum":["today","7d","30d","all"],"default":"30d"}},{"name":"platform","in":"query","required":false,"description":"Platform filter.","schema":{"type":"string","enum":["all","tiktok","instagram","youtube","x","other"],"default":"all"}}],"responses":{"200":{"description":"The board plus the caller's own rank.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"board":{"type":"array","items":{"$ref":"#/components/schemas/LeaderboardRow"}},"my_rank":{"oneOf":[{"$ref":"#/components/schemas/MyRank"},{"type":"null"}]}}},"meta":{"type":"object","properties":{"period":{"type":"string"},"platform":{"type":"string"},"returned":{"type":"integer"},"participants":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, no_active_plan, or not_a_member — the leaderboard is a members-only feature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/leaderboard/rising":{"get":{"operationId":"getRisingStars","summary":"Biggest climbers versus the previous window.","description":"MEMBERS-ONLY. Public members only — a private member is never surfaced even anonymized. All-time has no prior window, so it returns [].\n\nCosts 2 requests from your plan.\n\nRequired scope: `leaderboard:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"leaderboard:read","x-request-cost":2,"parameters":[{"name":"period","in":"query","required":false,"description":"Window.","schema":{"type":"string","enum":["today","7d","30d","all"],"default":"7d"}},{"name":"platform","in":"query","required":false,"description":"Platform filter.","schema":{"type":"string","enum":["all","tiktok","instagram","youtube","x","other"],"default":"all"}}],"responses":{"200":{"description":"Biggest climbers vs the previous window.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RisingStar"}},"meta":{"type":"object","properties":{"period":{"type":"string"},"platform":{"type":"string"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, no_active_plan, or not_a_member.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/profiles/{username}":{"get":{"operationId":"getProfile","summary":"A creator's public profile and opted-in earnings.","description":"MEMBERS-ONLY. Returns a row ONLY when the username exists AND that member keeps earnings public — an unknown handle and a private one are deliberately indistinguishable (both 404). No user id is returned.\n\nCosts 1 request from your plan.\n\nRequired scope: `leaderboard:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"leaderboard:read","x-request-cost":1,"parameters":[{"name":"username","in":"path","required":true,"description":"The creator's public handle.","schema":{"type":"string"}}],"responses":{"200":{"description":"The creator's public profile and opted-in earnings.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProfileStats"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, no_active_plan, or not_a_member.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such profile, or that member keeps earnings private.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me":{"get":{"operationId":"getMe","summary":"This key: owner, scopes, plan, quota and balances.","description":"One call that composes the key row, the entitlement math and a per-day usage array for the current UTC month. The key's secret hash is never in the response.\n\nCosts 1 request from your plan.\n\nRequired scope: `account:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"account:read","x-request-cost":1,"responses":{"200":{"description":"This key: owner, scopes, plan, quota and balances.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Me"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — the key was revoked between auth and this read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/bookmarks":{"get":{"operationId":"listBookmarks","summary":"Saved campaigns, hydrated.","description":"Costs 1 request from your plan.\n\nRequired scope: `bookmarks:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"bookmarks:read","x-request-cost":1,"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"Page start.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"fields","in":"query","required":false,"description":"Comma-separated subset of the public campaign columns to return; `id` is always included and unknown names are dropped.","schema":{"type":"string"}}],"responses":{"200":{"description":"Saved campaigns, hydrated (each with saved_at).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedCampaign"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Total matches across all pages."},"limit":{"type":"integer"},"offset":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addBookmark","summary":"Save a campaign.","description":"The campaign must exist (404 otherwise). Idempotent by the (user, campaign) PK: a duplicate save is 200 with the existing row, a fresh save 201.\n\nCosts 1 request from your plan.\n\nRequired scope: `bookmarks:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"bookmarks:write","x-request-cost":1,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-chosen key that makes this unsafe write safe to retry: a replay with the SAME key and body returns the first outcome instead of acting twice; the same key with a different body is 409 idempotency_conflict, and an identical request still in flight is 409 request_in_flight.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The campaign to save.","content":{"application/json":{"schema":{"type":"object","properties":{"campaign_id":{"type":"string","format":"uuid"}},"required":["campaign_id"]}}}},"responses":{"201":{"description":"Saved (201 fresh, 200 already-saved).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"campaign_id":{"type":"string","format":"uuid"},"saved_at":{"type":"string","format":"date-time"}}}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no campaign with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/bookmarks/{campaignId}":{"delete":{"operationId":"removeBookmark","summary":"Un-save a campaign.","description":"204 even when the bookmark didn't exist — DELETE is idempotent and never 404s here.\n\nCosts 1 request from your plan.\n\nRequired scope: `bookmarks:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"bookmarks:write","x-request-cost":1,"parameters":[{"name":"campaignId","in":"path","required":true,"description":"The campaign to un-save.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No content.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/hidden":{"get":{"operationId":"listHidden","summary":"Hidden campaign ids.","description":"Default shape is cheap { campaign_id, hidden_at }. ?hydrate=true returns full campaigns (each with hidden_at).\n\nCosts 1 request from your plan.\n\nRequired scope: `bookmarks:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"bookmarks:read","x-request-cost":1,"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"Page start.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"hydrate","in":"query","required":false,"description":"Return full campaigns instead of ids.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Hidden campaigns (ids by default; full campaigns with ?hydrate=true).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/HiddenRef"}},{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}}]},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Total matches across all pages."},"limit":{"type":"integer"},"offset":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"hideCampaign","summary":"Hide a campaign from the feed.","description":"Mirrors the bookmark write: campaign must exist, idempotent by the PK, honours Idempotency-Key.\n\nCosts 1 request from your plan.\n\nRequired scope: `bookmarks:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"bookmarks:write","x-request-cost":1,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-chosen key that makes this unsafe write safe to retry: a replay with the SAME key and body returns the first outcome instead of acting twice; the same key with a different body is 409 idempotency_conflict, and an identical request still in flight is 409 request_in_flight.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The campaign to hide.","content":{"application/json":{"schema":{"type":"object","properties":{"campaign_id":{"type":"string","format":"uuid"}},"required":["campaign_id"]}}}},"responses":{"201":{"description":"Hidden (201 fresh, 200 already-hidden).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"campaign_id":{"type":"string","format":"uuid"},"hidden_at":{"type":"string","format":"date-time"}}}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no campaign with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/hidden/{campaignId}":{"delete":{"operationId":"unhideCampaign","summary":"Un-hide a campaign.","description":"204 even when absent.\n\nCosts 1 request from your plan.\n\nRequired scope: `bookmarks:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"bookmarks:write","x-request-cost":1,"parameters":[{"name":"campaignId","in":"path","required":true,"description":"The campaign to un-hide.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No content.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/presets":{"get":{"operationId":"listPresets","summary":"Saved filter presets.","description":"Costs 1 request from your plan.\n\nRequired scope: `presets:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"presets:read","x-request-cost":1,"responses":{"200":{"description":"Saved filter presets.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Preset"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createPreset","summary":"Save a filter preset (max 8).","description":"`filters`/`sort` are run through the feed sanitizers before storage. Max 8 per user (409 limit_reached at the cap).\n\nCosts 1 request from your plan.\n\nRequired scope: `presets:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"presets:write","x-request-cost":1,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-chosen key that makes this unsafe write safe to retry: a replay with the SAME key and body returns the first outcome instead of acting twice; the same key with a different body is 409 idempotency_conflict, and an identical request still in flight is 409 request_in_flight.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The preset to save.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"filters":{"$ref":"#/components/schemas/FeedFilters"},"sort":{"type":"string"}},"required":["name"]}}}},"responses":{"201":{"description":"The created preset.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Preset"}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"limit_reached — you already have the maximum of 8 presets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/presets/{id}":{"patch":{"operationId":"updatePreset","summary":"Rename or re-point a preset.","description":"At least one of name/filters/sort. `state` is atomic — replacing it needs BOTH filters and sort; one without the other is a 400. Rename alone is fine.\n\nCosts 1 request from your plan.\n\nRequired scope: `presets:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"presets:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"The fields to change.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"filters":{"$ref":"#/components/schemas/FeedFilters"},"sort":{"type":"string"}}}}}},"responses":{"200":{"description":"The updated preset.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Preset"}},"required":["data"]}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deletePreset","summary":"Delete a preset.","description":"Costs 1 request from your plan.\n\nRequired scope: `presets:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"presets:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No content.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/alerts/rules":{"get":{"operationId":"listAlertRules","summary":"Alert rules.","description":"Costs 1 request from your plan.\n\nRequired scope: `alerts:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:read","x-request-cost":1,"responses":{"200":{"description":"Alert rules.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AlertRule"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createAlertRule","summary":"Create an alert rule (max 20).","description":"ALSO SPENDS main-app usage credits (USAGE_COSTS.alertCreate) exactly as the dashboard does — the API-request meter and the usage-credit meter are independent and both apply. `filters` use the AlertFilters shape. Free users get 402. Max 20 rules. Referenced channel_ids must be yours.\n\nCosts 1 request from your plan. ALSO spends main-app usage credits (a second, independent meter).\n\nRequired scope: `alerts:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:write","x-spends-usage-credits":true,"x-request-cost":1,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-chosen key that makes this unsafe write safe to retry: a replay with the SAME key and body returns the first outcome instead of acting twice; the same key with a different body is 409 idempotency_conflict, and an identical request still in flight is 409 request_in_flight.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The rule to create.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"enabled":{"type":"boolean","default":true},"events":{"type":"array","items":{"type":"string","enum":["new_campaign","budget_low","campaign_expired"]},"minItems":1},"filters":{"$ref":"#/components/schemas/AlertFilters"},"channel_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1},"frequency":{"type":"string","enum":["instant","daily"],"default":"instant"},"digest_hour":{"type":"integer","minimum":0,"maximum":23,"default":9},"cooldown_minutes":{"type":"integer","minimum":0,"maximum":1440,"default":0},"max_per_day":{"type":"integer","minimum":1,"maximum":100,"default":20},"quiet_hours":{"type":["object","null"],"properties":{"start":{"type":"integer"},"end":{"type":"integer"}}},"template":{"type":["string","null"],"maxLength":2000},"tone":{"type":"string","enum":["clean","serious","fun","hype"],"default":"clean"}},"required":["name","events","channel_ids"]}}}},"responses":{"201":{"description":"The created rule.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertRule"}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"payment_required — a free account, or a credits user whose wallet can't cover USAGE_COSTS.alertCreate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"limit_reached — you already have the maximum of 20 rules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/alerts/rules/{id}":{"get":{"operationId":"getAlertRule","summary":"One alert rule.","description":"Costs 1 request from your plan.\n\nRequired scope: `alerts:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:read","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"One alert rule.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertRule"}},"required":["data"]}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateAlertRule","summary":"Edit an alert rule.","description":"Any subset of the create fields; at least one. Editing is never charged usage credits (only creation is). Re-pointed channel_ids must be yours.\n\nCosts 1 request from your plan.\n\nRequired scope: `alerts:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"The fields to change.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"enabled":{"type":"boolean"},"events":{"type":"array","items":{"type":"string","enum":["new_campaign","budget_low","campaign_expired"]}},"filters":{"$ref":"#/components/schemas/AlertFilters"},"channel_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"frequency":{"type":"string","enum":["instant","daily"]},"digest_hour":{"type":"integer","minimum":0,"maximum":23},"cooldown_minutes":{"type":"integer","minimum":0,"maximum":1440},"max_per_day":{"type":"integer","minimum":1,"maximum":100},"quiet_hours":{"type":["object","null"],"properties":{"start":{"type":"integer"},"end":{"type":"integer"}}},"template":{"type":["string","null"],"maxLength":2000},"tone":{"type":"string","enum":["clean","serious","fun","hype"]}}}}}},"responses":{"200":{"description":"The updated rule.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertRule"}},"required":["data"]}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteAlertRule","summary":"Delete an alert rule.","description":"Costs 1 request from your plan.\n\nRequired scope: `alerts:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No content.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/alerts/rules/{id}/test":{"post":{"operationId":"testAlertRule","summary":"Send a test delivery for a rule.","description":"Sends a real test delivery through every channel the rule points at. A channel-level failure is a 200 with ok:false in that channel's result; the request only 4xx/5xxs when the rule is unusable.\n\nCosts 2 requests from your plan.\n\nRequired scope: `alerts:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:write","x-request-cost":2,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Per-channel delivery outcome.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"rule_id":{"type":"string","format":"uuid"},"results":{"type":"array","items":{"type":"object","properties":{"channel_id":{"type":"string","format":"uuid"},"channel_type":{"type":"string"},"channel_name":{"type":"string"},"ok":{"type":"boolean"},"error":{"type":["string","null"]}}}}}},"meta":{"type":"object","properties":{"channels":{"type":"integer"},"sent":{"type":"integer"},"failed":{"type":"integer"}}}},"required":["data"]}}}},"400":{"description":"invalid_id — the rule id isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no rule with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict — the rule has no deliverable channels.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/alerts/channels":{"get":{"operationId":"listAlertChannels","summary":"Delivery channels.","description":"Costs 1 request from your plan.\n\nRequired scope: `alerts:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:read","x-request-cost":1,"responses":{"200":{"description":"Delivery channels.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AlertChannel"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createAlertChannel","summary":"Add a delivery channel (max 10).","description":"Config is validated per type: telegram needs chat_id, discord/slack a webhook_url, the generic webhook a url (+ optional secret), email an address. Config keys not belonging to the type are rejected. A webhook `secret` is accepted here but never returned. Max 10.\n\nCosts 1 request from your plan.\n\nRequired scope: `alerts:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:write","x-request-cost":1,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-chosen key that makes this unsafe write safe to retry: a replay with the SAME key and body returns the first outcome instead of acting twice; the same key with a different body is 409 idempotency_conflict, and an identical request still in flight is 409 request_in_flight.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The channel to add.","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["telegram","discord","slack","webhook","email"]},"name":{"type":"string","maxLength":120},"config":{"type":"object","additionalProperties":true,"description":"Per-type addressing — see the description."},"enabled":{"type":"boolean","default":true}},"required":["type","name"]}}}},"responses":{"201":{"description":"The created channel (secret redacted).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertChannel"}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"limit_reached — you already have the maximum of 10 channels.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/alerts/channels/{id}":{"patch":{"operationId":"updateAlertChannel","summary":"Edit a delivery channel.","description":"A channel's TYPE is immutable. At least one of name/config/enabled. Config is validated against the existing type. The response is redacted.\n\nCosts 1 request from your plan.\n\nRequired scope: `alerts:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"The fields to change.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"config":{"type":"object","additionalProperties":true},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The updated channel (secret redacted).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertChannel"}},"required":["data"]}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteAlertChannel","summary":"Delete a delivery channel.","description":"Costs 1 request from your plan.\n\nRequired scope: `alerts:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No content.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/alerts/deliveries":{"get":{"operationId":"listAlertDeliveries","summary":"Recent alert delivery history.","description":"Newest first. The log carries denormalized rule/channel labels, so it stays readable after a rule or channel is deleted.\n\nCosts 1 request from your plan.\n\nRequired scope: `alerts:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:read","x-request-cost":1,"parameters":[{"name":"rule_id","in":"query","required":false,"description":"Only this rule's deliveries.","schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"query","required":false,"description":"Only this channel's deliveries.","schema":{"type":"string","format":"uuid"}},{"name":"event","in":"query","required":false,"description":"Only this event type.","schema":{"type":"string","enum":["new_campaign","budget_low","campaign_expired","digest","test"]}},{"name":"ok","in":"query","required":false,"description":"Successes or failures only.","schema":{"type":"boolean"}},{"name":"since","in":"query","required":false,"description":"Deliveries at/after this instant (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"Page start.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Delivery history.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AlertDelivery"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Total matches across all pages."},"limit":{"type":"integer"},"offset":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/alerts/preview":{"post":{"operationId":"previewAlertRule","summary":"How many live campaigns a rule's filters match.","description":"POST because the body is a filters object. MEMBERS-ONLY (403 not_a_member for a free/credits user). Runs the dispatch engine's matcher against the live feed and returns the count plus up to five sample campaigns.\n\nCosts 2 requests from your plan.\n\nRequired scope: `alerts:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"alerts:read","x-request-cost":2,"requestBody":{"required":false,"description":"The filters to preview.","content":{"application/json":{"schema":{"type":"object","properties":{"filters":{"$ref":"#/components/schemas/AlertFilters"},"events":{"type":"array","items":{"type":"string","enum":["new_campaign","budget_low","campaign_expired"]}}}}}}},"responses":{"200":{"description":"The match count and a sample.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertPreview"}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, no_active_plan, or not_a_member — previewing is a member feature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/profit/entries":{"get":{"operationId":"listProfitEntries","summary":"Earnings journal entries.","description":"Costs 1 request from your plan.\n\nRequired scope: `profit:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:read","x-request-cost":1,"parameters":[{"name":"from","in":"query","required":false,"description":"entry_date lower bound (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"entry_date upper bound (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"Filter by platform.","schema":{"type":"string","enum":["tiktok","instagram","youtube","x","other"]}},{"name":"campaign_id","in":"query","required":false,"description":"Filter by linked campaign.","schema":{"type":"string","format":"uuid"}},{"name":"source","in":"query","required":false,"description":"Filter by origin.","schema":{"type":"string","enum":["manual","auto"]}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"Page start.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"The earnings journal.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProfitEntry"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Total matches across all pages."},"limit":{"type":"integer"},"offset":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createProfitEntry","summary":"Log an earnings entry.","description":"Only manual rows exist over the API. Per-day cap of 20 manual rows (409 limit_reached). amount is USD (rounded to cents).\n\nCosts 1 request from your plan.\n\nRequired scope: `profit:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:write","x-request-cost":1,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-chosen key that makes this unsafe write safe to retry: a replay with the SAME key and body returns the first outcome instead of acting twice; the same key with a different body is 409 idempotency_conflict, and an identical request still in flight is 409 request_in_flight.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The entry to log.","content":{"application/json":{"schema":{"type":"object","properties":{"entry_date":{"type":"string","description":"YYYY-MM-DD, not in the future."},"amount":{"type":"number","minimum":0,"maximum":1000000,"description":"USD."},"campaign_name":{"type":"string","maxLength":200},"platform":{"type":"string","enum":["tiktok","instagram","youtube","x","other"],"default":"other"},"views":{"type":["integer","null"],"minimum":0},"notes":{"type":["string","null"],"maxLength":2000}},"required":["entry_date","amount"]}}}},"responses":{"201":{"description":"The created entry.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProfitEntry"}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"limit_reached — the 20-manual-entries-per-day cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/profit/entries/{id}":{"patch":{"operationId":"updateProfitEntry","summary":"Edit an earnings entry.","description":"Only source='manual' rows may be edited — an auto-tracked row is 409 conflict. Any subset of the create fields; at least one. views/notes accept explicit null to clear.\n\nCosts 1 request from your plan.\n\nRequired scope: `profit:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"The fields to change.","content":{"application/json":{"schema":{"type":"object","properties":{"entry_date":{"type":"string"},"amount":{"type":"number","minimum":0,"maximum":1000000},"campaign_name":{"type":"string","maxLength":200},"platform":{"type":"string","enum":["tiktok","instagram","youtube","x","other"]},"views":{"type":["integer","null"],"minimum":0},"notes":{"type":["string","null"],"maxLength":2000}}}}}},"responses":{"200":{"description":"The updated entry.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProfitEntry"}},"required":["data"]}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict — the entry is auto-tracked and can't be edited over the API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteProfitEntry","summary":"Delete an earnings entry.","description":"Auto rows are deletable (the sync re-creates them next run if warranted).\n\nCosts 1 request from your plan.\n\nRequired scope: `profit:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No content.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/profit/summary":{"get":{"operationId":"getProfitSummary","summary":"Monthly totals, streak, best day and goal progress.","description":"The monthly rollup, streak, best day and goal progress. `goal_cents` is whole cents.\n\nCosts 1 request from your plan.\n\nRequired scope: `profit:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:read","x-request-cost":1,"parameters":[{"name":"month","in":"query","required":false,"description":"The month to summarize (YYYY-MM); defaults to the current UTC month.","schema":{"type":"string"}}],"responses":{"200":{"description":"The monthly summary.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProfitSummary"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/profit/export":{"get":{"operationId":"exportProfit","summary":"Export the earnings journal as CSV.","description":"The earnings journal as a CSV download.\n\nCosts 2 requests from your plan.\n\nRequired scope: `profit:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:read","x-request-cost":2,"parameters":[{"name":"from","in":"query","required":false,"description":"entry_date lower bound (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"entry_date upper bound (YYYY-MM-DD).","schema":{"type":"string"}}],"responses":{"200":{"description":"A text/csv attachment.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/profit/goals":{"get":{"operationId":"getProfitGoals","summary":"Monthly earnings goals.","description":"Newest month first. `amount_cents` is whole cents (the column's own unit).\n\nCosts 1 request from your plan.\n\nRequired scope: `profit:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:read","x-request-cost":1,"responses":{"200":{"description":"Monthly earnings goals.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProfitGoal"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setProfitGoal","summary":"Set or clear a month's goal.","description":"amount_cents is whole cents (> 0); null clears the month's goal (a non-positive goal is the absence of a row, not a $0 target).\n\nCosts 1 request from your plan.\n\nRequired scope: `profit:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:write","x-request-cost":1,"requestBody":{"required":true,"description":"The goal to set (or clear).","content":{"application/json":{"schema":{"type":"object","properties":{"month":{"type":"string","description":"YYYY-MM."},"amount_cents":{"type":["integer","null"],"minimum":1,"description":"Whole cents > 0, or null to clear."}},"required":["month","amount_cents"]}}}},"responses":{"200":{"description":"The set goal, or a cleared marker.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/ProfitGoal"},{"type":"object","properties":{"month":{"type":"string"},"cleared":{"type":"boolean"}}}]}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/profit/videos":{"get":{"operationId":"listTrackedVideos","summary":"Auto-tracked videos and their campaign matches.","description":"Costs 1 request from your plan.\n\nRequired scope: `profit:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:read","x-request-cost":1,"parameters":[{"name":"match_status","in":"query","required":false,"description":"Filter by match state.","schema":{"type":"string","enum":["pending","matched","unmatched","ignored"]}},{"name":"platform","in":"query","required":false,"description":"Filter by platform.","schema":{"type":"string"}},{"name":"campaign_id","in":"query","required":false,"description":"Filter by matched campaign.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"Page start.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Auto-tracked videos, newest-posted first.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TrackedVideo"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Total matches across all pages."},"limit":{"type":"integer"},"offset":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/profit/videos/{id}":{"patch":{"operationId":"reviewTrackedVideo","summary":"Assign, unassign or ignore a tracked video.","description":"Assigning learns a match route from the clip's hashtags and propagates to sibling videos in the same batch — the response's `propagated` counts them. campaign_id is required for assign, rejected otherwise.\n\nCosts 1 request from your plan.\n\nRequired scope: `profit:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"The review action.","content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["assign","unassign","ignore"]},"campaign_id":{"type":"string","format":"uuid","description":"Required for action=assign."}},"required":["action"]}}}},"responses":{"200":{"description":"The updated video plus the propagation count.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"video":{"$ref":"#/components/schemas/TrackedVideo"},"propagated":{"type":"integer","description":"How many sibling videos the assignment rippled to."}}}},"required":["data"]}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/profit/feedback":{"post":{"operationId":"createMatchFeedback","summary":"Rate a video-to-campaign match.","description":"The campaign/confidence/reason snapshot is read server-side from your owned video, never from the request. Unique on (user, video): re-rating UPDATES the standing verdict rather than 409ing, so this returns 200 (not 201).\n\nCosts 1 request from your plan.\n\nRequired scope: `profit:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:write","x-request-cost":1,"requestBody":{"required":true,"description":"The verdict.","content":{"application/json":{"schema":{"type":"object","properties":{"video_id":{"type":"string","format":"uuid"},"verdict":{"type":"string","enum":["correct","close","wrong"]},"note":{"type":["string","null"],"maxLength":600}},"required":["video_id","verdict"]}}}},"responses":{"200":{"description":"The stored feedback.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no tracked video with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/profit/sync":{"get":{"operationId":"getProfitSync","summary":"Auto-tracking settings and recent sync runs.","description":"The on/off switch, the check frequency and sync timestamps, the last ten run health records, and your tracking-credit capacity at that frequency.\n\nCosts 1 request from your plan.\n\nRequired scope: `profit:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:read","x-request-cost":1,"responses":{"200":{"description":"Auto-tracking settings and recent runs.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProfitSyncState"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateProfitSync","summary":"Set auto-tracking on/off and how often it checks.","description":"Set auto-tracking on/off and how often it checks. There is no trigger-a-sync-now call: auto-tracking is schedule-driven, and the SPEED is the control. `interval_hours` is 24 (default) / 12 / 6 / 3, priced at checks per day — every extra check re-reads every tracked account, so it uses proportionally more tracking capacity. A speed your capacity can't fund for a single account is refused with 402 payment_required rather than saved. (POST on this path was the old trigger and now answers 405 method_not_allowed.)\n\nCosts 1 request from your plan.\n\nRequired scope: `profit:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profit:write","x-request-cost":1,"requestBody":{"required":true,"description":"The settings to change — send either field or both.","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"interval_hours":{"type":"integer","enum":[24,12,6,3]}}}}}},"responses":{"200":{"description":"The saved settings.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"enabled":{"type":"boolean"},"interval_hours":{"type":"integer","enum":[24,12,6,3]},"last_synced_at":{"type":["string","null"],"format":"date-time"}}}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"payment_required — that speed needs more tracking capacity than your plan funds; add capacity or pick a slower one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/social-accounts":{"get":{"operationId":"listSocialAccounts","summary":"Connected social accounts.","description":"Costs 1 request from your plan.\n\nRequired scope: `social:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"social:read","x-request-cost":1,"responses":{"200":{"description":"Connected social accounts, verified and pending.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SocialAccount"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"connectSocialAccount","summary":"Start bio-proof verification for a handle.","description":"Starts bio-proof verification. `handle` may be an @name, bare name or a pasted profile URL (normalized server-side). Returns the proof code + expiry (and `bio_location`, where on the platform to paste it) so the caller can prompt the user, then call verify. 409 conflict when another member already verified the handle or you already have it; 409 limit_reached at the 20-account cap.\n\nCosts 1 request from your plan.\n\nRequired scope: `social:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"social:write","x-request-cost":1,"requestBody":{"required":true,"description":"The handle to verify.","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["youtube","tiktok","instagram","x"]},"handle":{"type":"string","maxLength":2048}},"required":["platform","handle"]}}}},"responses":{"201":{"description":"The pending account and its proof code.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"account":{"$ref":"#/components/schemas/SocialAccount"},"code":{"type":"string","description":"The proof code to paste into the account's bio."},"expires_at":{"type":"string","format":"date-time"},"expires_in_seconds":{"type":"integer"},"bio_location":{"type":"string","description":"Where to paste the code on this platform (e.g. the TikTok bio, the YouTube channel description)."}}}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict (handle claimed by another member, or already yours) / limit_reached (20-account cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/social-accounts/{id}/verify":{"post":{"operationId":"verifySocialAccount","summary":"Check the bio for the proof code and verify.","description":"Reads the account's public bio, looks for its active proof code, and flips it to verified. NO body — the account is addressed by {id}. SLOW (an outbound page render) and costs 5. The failure modes are deliberately distinct, each with a machine-readable error.details.reason.\n\nCosts 5 requests from your plan.\n\nRequired scope: `social:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"social:write","x-request-cost":5,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The now-verified account.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SocialAccount"}},"required":["data"]}}}},"400":{"description":"invalid_id — the account id isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — details.reason is account_not_found or profile_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict — details.reason is no_code, code_not_in_bio, unreachable or claimed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"conflict — details.reason 'expired': the code's TTL lapsed; mint a fresh one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"conflict — details.reason 'code_not_in_bio': the bio was read but the code isn't in it yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"limit_reached — details.reason 'attempts': the per-code read cap is spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"conflict — details.reason 'unreachable': the platform wouldn't serve the bio (transient).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/social-accounts/{id}":{"patch":{"operationId":"updateSocialAccount","summary":"Set primary or niches for an account.","description":"At least one of is_primary/niches. Only a VERIFIED account may be primary (409 conflict otherwise). niches: up to 3, sanitized; [] clears.\n\nCosts 1 request from your plan.\n\nRequired scope: `social:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"social:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"The fields to change.","content":{"application/json":{"schema":{"type":"object","properties":{"is_primary":{"type":"boolean"},"niches":{"type":"array","items":{"type":"string"},"maxItems":3}}}}}},"responses":{"200":{"description":"The updated account.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SocialAccount"}},"required":["data"]}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict — the account isn't verified but is being made primary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"disconnectSocialAccount","summary":"Disconnect a social account.","description":"Verified or pending. Also sweeps any live verification code.\n\nCosts 1 request from your plan.\n\nRequired scope: `social:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"social:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No content.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/analyses":{"get":{"operationId":"listAnalyses","summary":"Stored per-account analyses.","description":"With ?social_account_id, returns just that account's analysis (or null when never analysed); a foreign/unknown id is 404.\n\nCosts 1 request from your plan.\n\nRequired scope: `analysis:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"analysis:read","x-request-cost":1,"parameters":[{"name":"social_account_id","in":"query","required":false,"description":"Return just this account's analysis.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Stored analyses (or one, with the filter).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Analysis"}},{"$ref":"#/components/schemas/Analysis"},{"type":"null"}]},"meta":{"type":"object","properties":{"total":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no connected account with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"runAnalysis","summary":"Analyse a connected account.","description":"The expensive one: 25 requests AND main-app usage credits (per-platform: youtube 0.2 / tiktok 1 / instagram 1 / x 2, drawn from a subscriber's allowance first then the wallet). A fresh cached analysis is FREE unless force=true. Returns 200 for BOTH cached and fresh runs, with a `cost` object exposing both meters. Free users get 402; an account with nothing to analyse is 422 no_signals.\n\nCosts 25 requests from your plan. ALSO spends main-app usage credits (a second, independent meter).\n\nRequired scope: `analysis:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"analysis:write","x-spends-usage-credits":true,"x-request-cost":25,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-chosen key that makes this unsafe write safe to retry: a replay with the SAME key and body returns the first outcome instead of acting twice; the same key with a different body is 409 idempotency_conflict, and an identical request still in flight is 409 request_in_flight.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The account to analyse.","content":{"application/json":{"schema":{"type":"object","properties":{"social_account_id":{"type":"string","format":"uuid"},"force":{"type":"boolean","default":false,"description":"Re-run even when a fresh cached analysis exists (always charges)."}},"required":["social_account_id"]}}}},"responses":{"200":{"description":"The analysis plus what it cost on both meters.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"analysis":{"$ref":"#/components/schemas/Analysis"},"cached":{"type":"boolean"},"cost":{"type":"object","properties":{"api_requests":{"type":"integer","description":"Always 25."},"usage_credits":{"type":"number","description":"0 when the subscriber allowance covered it or the read was cached."},"paid_from":{"type":"string","enum":["allowance","wallet","cache"]}}}}}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"payment_required — a free account, or a wallet shortfall (details carry cost + balance).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict — the account isn't verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"no_signals — nothing to analyse yet (add a bio, post something, tag niches).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — the analysis model is rate-limited; you have not been charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/picks":{"get":{"operationId":"listPicks","summary":"Today's per-account campaign picks.","description":"Today's per-account picks, hydrated. READ-ONLY — never pins. A day with no picks yet returns [].\n\nCosts 1 request from your plan.\n\nRequired scope: `analysis:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"analysis:read","x-request-cost":1,"parameters":[{"name":"social_account_id","in":"query","required":false,"description":"Just this account's picks.","schema":{"type":"string","format":"uuid"}},{"name":"day","in":"query","required":false,"description":"A UTC day (YYYY-MM-DD); defaults to today. A malformed value falls back to today.","schema":{"type":"string"}}],"responses":{"200":{"description":"Today's picks.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Pick"}},"meta":{"type":"object","properties":{"day":{"type":"string"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no connected account with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/for-you":{"get":{"operationId":"getForYou","summary":"Personalized feed ranked for connected accounts.","description":"The personalized feed, ranked for your connected accounts. The four weights (0–2, snapped to 0.1) let a caller shop like the dashboard sliders. With no verified accounts, data is [] and meta.reason explains why.\n\nCosts 2 requests from your plan.\n\nRequired scope: `analysis:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"analysis:read","x-request-cost":2,"parameters":[{"name":"w_match","in":"query","required":false,"description":"Match weight, 0–2.","schema":{"type":"number","minimum":0,"maximum":2}},{"name":"w_viral","in":"query","required":false,"description":"Viral weight, 0–2.","schema":{"type":"number","minimum":0,"maximum":2}},{"name":"w_rate","in":"query","required":false,"description":"Rate weight, 0–2.","schema":{"type":"number","minimum":0,"maximum":2}},{"name":"w_budget_left","in":"query","required":false,"description":"Budget-left weight, 0–2.","schema":{"type":"number","minimum":0,"maximum":2}},{"name":"account_id","in":"query","required":false,"description":"Rank against just this verified account.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"Page start.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"The ranked feed.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ForYouItem"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"returned":{"type":"integer"},"weights":{"type":"object","properties":{"w_match":{"type":"number"},"w_viral":{"type":"number"},"w_rate":{"type":"number"},"w_budget_left":{"type":"number"}}},"reason":{"type":"string","description":"Present (and data empty) when you have no verified accounts."}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/recommendations":{"get":{"operationId":"getRecommendations","summary":"Rank live campaigns against a niche profile.","description":"Rank live campaigns against a niche profile WITHOUT a stored analysis. Two input styles (mutually exclusive): ?social_account_id=<uuid>, OR ?categories=…&keywords=…. Each row carries its score and the matched signals; the profile used is echoed in meta.\n\nCosts 2 requests from your plan.\n\nRequired scope: `analysis:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"analysis:read","x-request-cost":2,"parameters":[{"name":"social_account_id","in":"query","required":false,"description":"Derive the profile from this account (XOR categories/keywords).","schema":{"type":"string","format":"uuid"}},{"name":"categories","in":"query","required":false,"description":"Comma-separated campaign categories (unknowns dropped).","schema":{"type":"string"}},{"name":"keywords","in":"query","required":false,"description":"Comma-separated free-text subjects.","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"Nudges the score (explicit path only).","schema":{"type":"string","enum":["youtube","tiktok","instagram","x"]}},{"name":"limit","in":"query","required":false,"description":"1..50 (default 25).","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}}],"responses":{"200":{"description":"Ranked recommendations.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RecommendationItem"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"profile":{"type":"object","properties":{"platform":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"keywords":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["analysis","declared","explicit"]}}}}}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_id — both input styles supplied, neither supplied, or a non-UUID account id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no connected account with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/profile":{"get":{"operationId":"getMyProfile","summary":"The owner's public profile.","description":"Costs 1 request from your plan.\n\nRequired scope: `profile:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profile:read","x-request-cost":1,"responses":{"200":{"description":"The owner's public profile.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MyProfile"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateMyProfile","summary":"Change username, avatar or earnings visibility.","description":"At least one of username/avatar_url/pnl_public. username is 3–20 chars, [a-z0-9_], not reserved (taken → 409 conflict). avatar_url is a URL only (null clears) — FILE UPLOAD IS OUT OF SCOPE over the API. pnl_public toggles earnings visibility.\n\nCosts 1 request from your plan.\n\nRequired scope: `profile:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"profile:write","x-request-cost":1,"requestBody":{"required":true,"description":"The fields to change.","content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"3–20 chars, starts alphanumeric, [a-z0-9_]."},"avatar_url":{"type":["string","null"],"format":"uri"},"pnl_public":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The updated profile.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MyProfile"}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict — that username is taken.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/affiliate":{"get":{"operationId":"getAffiliate","summary":"Referral code, clicks, referrals and commissions.","description":"The referral code, clicks, referral counts, current rate + tier, the commission ledger split, and an ANONYMIZED referral list (signup month + converted flag only).\n\nCosts 1 request from your plan.\n\nRequired scope: `affiliate:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"affiliate:read","x-request-cost":1,"responses":{"200":{"description":"The whole affiliate picture.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AffiliateSummary"}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateAffiliate","summary":"Claim a custom referral code.","description":"Claim a custom referral code (2–16 chars a–z0–9, not reserved). A code another affiliate owns is 409 conflict. Re-claiming is permitted.\n\nCosts 1 request from your plan.\n\nRequired scope: `affiliate:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"affiliate:write","x-request-cost":1,"requestBody":{"required":true,"description":"The code to claim.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":2,"maxLength":16}},"required":["code"]}}}},"responses":{"200":{"description":"The claimed code.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"code":{"type":"string"}}}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict — that code is already taken.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/affiliate/payouts":{"get":{"operationId":"listPayouts","summary":"Payout requests and available balance.","description":"Each request plus the recomputed available balance and the withdrawal minimum. The destination address is REDACTED to its last 4 characters.\n\nCosts 1 request from your plan.\n\nRequired scope: `affiliate:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"affiliate:read","x-request-cost":1,"responses":{"200":{"description":"Payout requests and the available balance.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"requests":{"type":"array","items":{"$ref":"#/components/schemas/PayoutRequest"}},"available_cents":{"type":"integer"},"available":{"type":"number","description":"The same figure in USD."},"minimum_usd":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"requestPayout","summary":"Request a payout of the available balance.","description":"The AMOUNT IS SERVER-COMPUTED and never taken from the body — sending `amount`/`amount_cents` is a 400. Enforces the $50 minimum and the one-open-request-per-user rule (409 conflict). Idempotent.\n\nCosts 1 request from your plan.\n\nRequired scope: `affiliate:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"affiliate:write","x-request-cost":1,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-chosen key that makes this unsafe write safe to retry: a replay with the SAME key and body returns the first outcome instead of acting twice; the same key with a different body is 409 idempotency_conflict, and an identical request still in flight is 409 request_in_flight.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The payout destination.","content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["usdt_trc20","usdt_erc20","btc","eth"]},"address":{"type":"string","maxLength":128}},"required":["method","address"]}}}},"responses":{"201":{"description":"The created request.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"request":{"$ref":"#/components/schemas/PayoutRequest"},"available_cents":{"type":"integer"},"minimum_usd":{"type":"integer"}}}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"conflict — an open request already exists, or the balance is below the minimum.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/webhooks":{"get":{"operationId":"listWebhooks","summary":"Webhook endpoints.","description":"The signing secret is REDACTED here (secret_hint). To read a secret in full, GET the single webhook.\n\nCosts 1 request from your plan.\n\nRequired scope: `webhooks:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"webhooks:read","x-request-cost":1,"responses":{"200":{"description":"Webhook endpoints (secrets redacted).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createWebhook","summary":"Register a webhook endpoint (max 10).","description":"The url must be https and must not resolve to an internal/loopback/link-local address or the metadata service (SSRF → 400). A signing secret is minted and returned IN FULL here — the ONE list-style response that includes it. Max 10. New webhooks seed their cursor to the current max event id.\n\nCosts 1 request from your plan.\n\nRequired scope: `webhooks:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"webhooks:write","x-request-cost":1,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-chosen key that makes this unsafe write safe to retry: a replay with the SAME key and body returns the first outcome instead of acting twice; the same key with a different body is 409 idempotency_conflict, and an identical request still in flight is 409 request_in_flight.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The webhook to register.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"https only."},"events":{"type":"array","items":{"type":"string","enum":["campaign.created","campaign.expired","campaign.budget_low","campaign.enriched"]},"minItems":1},"filters":{"$ref":"#/components/schemas/FeedFilters"},"description":{"type":["string","null"],"maxLength":200}},"required":["url","events"]}}}},"responses":{"201":{"description":"The created webhook, WITH its full secret.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookWithSecret"}},"required":["data"]}}}},"400":{"description":"validation_failed / invalid_body / body_too_large — the request body is malformed or a field is out of range; see error.details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"limit_reached — you already have the maximum of 10 webhooks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/webhooks/{id}":{"get":{"operationId":"getWebhook","summary":"One webhook endpoint, including its signing secret.","description":"INCLUDES the full signing secret — the owner needs it to verify signatures. Signature recipe: X-ClipRadar-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">; reject if abs(now - t) > 300s.\n\nCosts 1 request from your plan.\n\nRequired scope: `webhooks:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"webhooks:read","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The webhook, with its full secret.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookWithSecret"}},"required":["data"]}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateWebhook","summary":"Edit a webhook's url, events, filters or enabled state.","description":"Any subset of url/events/filters/description/enabled; at least one. Re-enabling an auto-disabled webhook clears its failure state. The url, if sent, is re-checked against the SSRF guard.\n\nCosts 1 request from your plan.\n\nRequired scope: `webhooks:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"webhooks:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"The fields to change.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["campaign.created","campaign.expired","campaign.budget_low","campaign.enriched"]}},"filters":{"$ref":"#/components/schemas/FeedFilters"},"description":{"type":["string","null"],"maxLength":200},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The updated webhook (secret redacted).","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}},"required":["data"]}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook endpoint.","description":"The cascade drops the webhook's delivery history with it.\n\nCosts 1 request from your plan.\n\nRequired scope: `webhooks:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"webhooks:write","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No content.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/webhooks/{id}/test":{"post":{"operationId":"testWebhook","summary":"Send a signed test event to a webhook.","description":"Sends a signed synthetic `webhook.test` event inline (bypassing the queue) and returns the receiver's status + a body excerpt. ok:false still returns HTTP 200 — reaching out succeeded; whether the receiver liked it is data, not an error.\n\nCosts 2 requests from your plan.\n\nRequired scope: `webhooks:write` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"webhooks:write","x-request-cost":2,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The test delivery outcome.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"response_status":{"type":["integer","null"]},"response_excerpt":{"type":["string","null"]},"ok":{"type":"boolean"},"error":{"type":["string","null"]},"delivery_id":{"type":["string","null"],"format":"uuid"}}}},"required":["data"]}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/webhooks/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"Delivery attempts for a webhook.","description":"Newest first. Each row carries last_error and response_status so a caller can diagnose retries/failures.\n\nCosts 1 request from your plan.\n\nRequired scope: `webhooks:read` (enforced by ClipRadar before metering — a missing scope is 403 insufficient_scope, a key change, not a retryable error).","x-required-scope":"webhooks:read","x-request-cost":1,"parameters":[{"name":"id","in":"path","required":true,"description":"id path parameter.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"description":"Filter by delivery status.","schema":{"type":"string","enum":["pending","delivered","failed"]}},{"name":"event","in":"query","required":false,"description":"Filter by event type.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"Page start.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Delivery attempts.","headers":{"X-RateLimit-Limit":{"description":"Requests/minute your plan allows on this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Left in the current one-minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the window resets (ISO 8601).","schema":{"type":"string"}},"X-Quota-Limit":{"description":"This month's request quota (membership allowance + tier).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Left in this month's quota.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"First instant of next UTC month, when the quota resets.","schema":{"type":"string"}},"X-Credits-Remaining":{"description":"Prepaid pay-as-you-go requests left (spent after the quota; never expire).","schema":{"type":"integer"}},"X-Request-Cost":{"description":"Requests this call debited (1 for most; 2 for bulk/timeseries, 5 for social verify, 10 for a profit sync, 25 for an account analysis).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Total matches across all pages."},"limit":{"type":"integer"},"offset":{"type":"integer"},"returned":{"type":"integer"}}}},"required":["data"]}}}},"400":{"description":"invalid_id — the id in the path isn't a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key (missing_key / invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is valid but not allowed or not funded: insufficient_scope (the key lacks this operation's scope — a key change, not a retry), or no_active_plan (no membership, tier or credits fund it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found — no such resource (or not yours; the two are indistinguishable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute window spent; honor Retry-After) or quota_exhausted (month quota AND prepaid credits empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}