CreatorScore API

1. Create a developer account — takes 30 seconds, you'll get an API key immediately.
2. Buy a credit pack from your dashboard. Starter is $399 for 50 creator scores.
3. Hit GET /api/v1/creators/{platform}/{handle} with your key. Every creator is a flat 1 credit — cached or scored fresh, one platform or six.

The fastest way to integrate this API is to paste the system prompt below into Claude, ChatGPT, Cursor, or any AI assistant — it has the full API surface area, request/response shapes, and error codes baked in. You'll get working code in under a minute.

System prompt — copy this verbatim into your AI assistant

You are helping a developer integrate the CreatorScore API. The API enriches influencer rosters with a 1-100 trust score across 7 AI agents.

# Base URL
https://creatorscore.io

# Authentication
Every request requires an HTTP header: X-API-Key: <key>

# Pricing
1 credit = 1 creator. Scoring or vetting a creator costs a flat 1 credit, no matter how many platforms or accounts they have — one platform or a six-platform footprint, TikTok or YouTube, all the same 1 credit. This is true for both a fresh score (scraped + scored on demand) and a cache hit (a score ≤30 days old, returned immediately). Footprint discovery (POST /creators/discover — finding a creator's other accounts from one seed handle) costs 1 credit: it runs a live profile fetch plus a web-grounded account search. Resolving a creator against our existing index (POST /creators/resolve) is free. Every response includes credits_charged. If the balance can't cover a lookup, the API returns 402 insufficient_credits and does NOT return the score.
Customers buy credit packs: Starter $399 = 50 creators ($7.98 each), Pro $1,499 = 250 creators ($6.00 each), Scale $4,990 = 1,000 creators ($4.99 each).

# Endpoints

## GET /api/v1/account
Returns the authenticated tenant info + credit balance + pricing table.
Response 200: { tenant: {id, name}, api_key: {id, label, created_at, last_used_at}, credits: {balance: number}, pricing: {credits_per_creator: 1, discovery_credits: 1, cache_freshness_days: 30, note: "1 credit per creator, any platform; discovery priced separately"} }

## GET /api/v1/creators/{platform}/{handle}
Cache-or-queue lookup of one creator.
Path params: platform (tiktok | instagram | youtube | twitter | x | facebook | reddit | twitch | kick | linkedin | threads | snapchat), handle (URL-encoded social handle, no @).

Response 200 (cache hit):
{
  "status": "cached",
  "creator": {
    "platform": "tiktok", "handle": "alixearle",
    "display_name": "Alix Earle", "followers": 8400000,
    "score": 84, "tier": "Excellent",
    "agents": {
      "content_risk": 81.0, "brand_safety": 82.1, "sentiment": 85.0,
      "authenticity": 98.8, "audience_quality": 84.4,
      "community_trust": 83.9, "roi_prediction": 58.6
    },
    "knockouts": [],
    "last_scored_at": "2026-04-15T05:30:39Z",
    "public_profile_url": "https://creatorscore.io/profile/..."
  },
  "credits_charged": 1
}

Response 202 (queued, fresh score needed):
{ "status": "queued", "job_id": "uuid", "eta_seconds": 1800, "poll_url": "/api/v1/jobs/{job_id}", "deduplicated": false, "credits_charged": 1 }

## POST /api/v1/creators/bulk
Submit up to 100 (platform, handle) pairs at once.
Body: { "creators": [{ "platform": "...", "handle": "..." }, ...] }
Response 200: { "results": [...], "summary": { "total", "cached", "queued", "errored", "credits_spent", "credits_remaining" } }
Each result has the same shape as the single endpoint (cached/queued/error).

## GET /api/v1/creators/{platform}/{handle}/report?sections=...&format=json|pdf
The FULL report for a scored creator (whole footprint from any one handle): risk_flags WITH EVIDENCE (post_url, caption/transcript excerpt, on_screen_text, why_flagged, signed thumbnail + frame image links), brand_mentions with per-brand disclosure verdict (undisclosed = FTC exposure), controversy (summary + filtered web findings), drivers (SHAP per agent), audience, following, score_history, engagement, narrative, detailed_analysis, and pdf_url (browser-openable, no key, expires in 24h). format=pdf streams the PDF.
Billing: 0 credits for a creator this account already paid to score; 1 credit as a cached read otherwise; 404 not_scored/score_stale with no charge. Never scrapes. Evidence image links expire — do not cache them.
Response 200: { "status": "ok", "access": "included"|"paid_cache_read", "sections": [...], "report": {...}, "credits_charged" }

## GET /api/v1/reports/{token}
The pdf_url target. No API key. HMAC-signed, expires (410 when expired), ownership re-checked at download.

## GET /api/v1/background-checks  and  GET /api/v1/background-checks/{id}?format=json|pdf
List this account's Social Background Checks / read one. Completed checks return the full categorized report (report.categories[] with per-flag description, content_preview, post_url, risk_weight, wayback marker, evidence.thumbnail/frame signed links; summary with categories_clean, categories_unassessed + reason, coverage gaps, archive_timeline), a flat flags[] for compatibility, and pdf_url. A Background Check is a separate product: NO score, paid via Stripe not credits.

## GET /api/v1/jobs/{job_id}?include=...
Poll one job. include= takes the same options as the creator lookup (narrative, risk_flags, detailed_analysis, engagement, velocity, report, all) and is free.
Response 200 (done): { "job_id", "status": "done", "progress": 100, "completed_at", "creator": {...same as cached payload...}, "report_url": "/api/v1/creators/{platform}/{handle}/report" }
Response 202 (in flight): { "job_id", "status": "queued"|"processing", "progress", "progress_message", "eta_seconds", "created_at" }
Response 200 (failed): { "job_id", "status": "failed", "progress", "error", "failed_at" }
Response 404: { "job_id", "status": "not_found", "message" }

## POST /api/v1/jobs/bulk-status
Poll up to 100 jobs at once.
Body: { "job_ids": ["uuid1", "uuid2", ...], "include": "narrative,risk_flags" }
Response 200: { "jobs": [...], "summary": { "total", "done", "in_flight", "failed", "not_found" } }

# include= options (creator lookup, jobs, bulk-status)
narrative, velocity, risk_flags (footprint-wide, WITH evidence + risk_flags_summary), detailed_analysis, engagement, report (embeds the full report), all. Free on every endpoint that accepts it.

# Polling guidance
Fresh scores take 10–90 minutes (mostly Whisper transcription on YouTube). Poll every 60 seconds for the first 30 minutes, then every 5 minutes after. Use the eta_seconds field on every queued/processing response as the canonical guide.

# Errors
All errors return { "error": "code", "message": "..." }.
Codes: missing_api_key (401), invalid_api_key (401), insufficient_scope (403), insufficient_credits (402), unsupported_platform (400), invalid_handle (400), invalid_request (400), rate_limit_exceeded (429), daily_scrape_limit_exceeded (429), daily_discovery_limit_exceeded (429), creator_busy (409), queue_failed (500), auth_unavailable (503).
daily_scrape_limit_exceeded (429) is a per-key safety cap on FRESH scrapes per UTC day; cached lookups are unaffected. Treat like a soft 429 — slow down or ask support to raise the cap.
daily_discovery_limit_exceeded (429) is a per-key daily cap on discovery operations (/creators/discover and /creators/score-footprint calls, previews included) — each performs live open-web work. Resets 00:00 UTC.
creator_busy (409) means another job currently holds this creator (e.g. a scan in another workspace). Nothing was charged — retry in ~2 minutes.
insufficient_scope (403) means a read-only key tried to queue a fresh score (cache miss). Only full-scope keys can queue. Cached lookups (charged the flat cache fee) + job-status reads work on read-only keys.

# Constraints
- Bulk endpoints accept max 100 items.
- Duplicate handles in the same batch are charged once (deduped).
- Jobs are scoped to the calling tenant — cross-tenant polling returns not_found.
- Rate limit: 120 requests/minute per API key. Exceeding it returns 429 rate_limit_exceeded with a Retry-After header (seconds). Back off and retry.

When generating code: always send the API key from an environment variable, never hardcoded. Surface insufficient_credits errors clearly so customers know to top up.

Sample user prompts

• "Write a Python script that enriches my CSV of TikTok handles with their CreatorScore. The CSV has one column called ‘handle’."
• "Build a TypeScript function I can use in my Next.js app to display a creator's score and 7-agent breakdown."
• "Show me how to bulk-score 50 creators, then poll their job IDs until they all complete, with backoff between polls."
• "Generate a React component that takes an array of (platform, handle) pairs and renders each creator's tier with a colored badge."

Prefer to vet creators without writing code? The CreatorScore MCP server wraps these same endpoints as tools for Claude, ChatGPT, Cursor, and any Model Context Protocol client. Add it with your API key and ask in plain language — score_creator_footprint, vet_creator (cache-only, so an agent can't fan out into surprise scrapes), get_creator_report (every flag with its evidence, brand mentions, drivers, and a PDF link), check_background_check, and a free calculate_fair_rate. See the MCP setup guide.

Every request requires an X-API-Key header. Keys are tenant-scoped — keep them secret and rotate if compromised. Create or revoke keys at /account/api.

curl https://creatorscore.io/api/v1/account \
  -H "X-API-Key: sk_live_..."

• 1 credit = 1 creator. A creator's whole cross-platform footprint, scored or vetted, is a flat 1 credit — one platform or six, cached or scored fresh, any platform
• Footprint discovery (find a creator's other accounts from one seed handle): 1 credit — a live profile fetch plus a web-grounded account search. Index resolution (POST /creators/resolve) is free
• Platforms & resellers: a credit licenses one end-customer's evaluation of one creator. If you serve multiple brands, each brand's view of a creator is a separate read (and credit) — cache per brand for up to 30 days, never across brands. Send X-Customer-Ref: <your brand id> on each read — it's logged with the request so per-brand usage is reconcilable on both sides. Scores are point-in-time: always display last_scored_at alongside any score you surface
• Pricing may adjust over time. Published pricing is authoritative and firm at the moment of purchase — credits you've bought are yours at the price you paid. Because every analysis runs on frontier AI models whose costs move, published pricing itself may adjust in either direction, with notice before it affects your next purchase or billing cycle
• No monthly fees, no commitments — prepaid credits only
• Refunds are automatic if the scoring pipeline fails

Credit packs

List price is $9.99/creator (matching the dashboard one-off); packs apply a volume discount. The same flat credit covers a fresh scrape-and-score or a cache hit — you pay for the vetted creator, not for how we got there.

All endpoints are versioned under /api/v1.

Reference implementations for the typical workflow: bulk-submit a roster, poll for completion, collect scores. Both samples handle insufficient_credits and failed jobs cleanly. Paste either into your AI assistant with the system prompt above to extend.

Python

import os
import time
import requests

API_KEY = os.environ["CREATORSCORE_API_KEY"]
BASE = "https://creatorscore.io/api/v1"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

def enrich_roster(creators: list[dict]) -> list[dict]:
    """
    creators: [{"platform": "tiktok", "handle": "alixearle"}, ...]
    Returns a list of score dicts (or {"error": "..."} for failures).
    """
    # 1. Bulk-submit
    r = requests.post(f"{BASE}/creators/bulk", json={"creators": creators}, headers=HEADERS)
    r.raise_for_status()
    data = r.json()

    results = list(data["results"])
    pending_jobs = {row["job_id"]: idx for idx, row in enumerate(results) if row["status"] == "queued"}

    if not pending_jobs:
        return [row.get("creator") or {"error": row.get("error")} for row in results]

    print(f"Cached: {data['summary']['cached']}  Queued: {data['summary']['queued']}  Spent: {data['summary']['credits_spent']} credits")

    # 2. Poll until all queued jobs finish (or fail). Backoff: 30s -> 60s -> 5m.
    delay = 30
    while pending_jobs:
        time.sleep(delay)
        r = requests.post(
            f"{BASE}/jobs/bulk-status",
            json={"job_ids": list(pending_jobs.keys())},
            headers=HEADERS,
        )
        r.raise_for_status()
        for job in r.json()["jobs"]:
            if job["status"] == "done":
                idx = pending_jobs.pop(job["job_id"])
                results[idx] = {"status": "done", "creator": job["creator"]}
            elif job["status"] in ("failed", "not_found"):
                idx = pending_jobs.pop(job["job_id"])
                results[idx] = {"status": job["status"], "error": job.get("error", "unknown")}
        delay = min(delay * 2, 300)  # 30 -> 60 -> 120 -> 240 -> 300 cap

    return [row.get("creator") or {"error": row.get("error", "unknown")} for row in results]


if __name__ == "__main__":
    roster = [
        {"platform": "tiktok",    "handle": "alixearle"},
        {"platform": "instagram", "handle": "MrBeast"},
        {"platform": "youtube",   "handle": "MrBeast"},
    ]
    for creator in enrich_roster(roster):
        print(creator)

TypeScript / Node.js

const API_KEY = process.env.CREATORSCORE_API_KEY!
const BASE = "https://creatorscore.io/api/v1"
const HEADERS = { "X-API-Key": API_KEY, "Content-Type": "application/json" }

type Creator = { platform: string; handle: string }

export async function enrichRoster(creators: Creator[]) {
  // 1. Bulk-submit
  const submitRes = await fetch(`${BASE}/creators/bulk`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ creators }),
  })
  if (!submitRes.ok) throw new Error(`Bulk submit failed: ${submitRes.status}`)
  const submit = await submitRes.json()

  const results = [...submit.results]
  const pending = new Map<string, number>()
  results.forEach((r: any, i: number) => {
    if (r.status === "queued") pending.set(r.job_id, i)
  })

  if (pending.size === 0) return results

  console.log(`Cached: ${submit.summary.cached}, Queued: ${submit.summary.queued}, Spent: ${submit.summary.credits_spent}cr`)

  // 2. Poll with exponential backoff (30s -> 60 -> 120 -> 240 -> 300 cap)
  let delay = 30_000
  while (pending.size > 0) {
    await new Promise((r) => setTimeout(r, delay))
    const pollRes = await fetch(`${BASE}/jobs/bulk-status`, {
      method: "POST",
      headers: HEADERS,
      body: JSON.stringify({ job_ids: Array.from(pending.keys()) }),
    })
    const poll = await pollRes.json()
    for (const job of poll.jobs as any[]) {
      if (job.status === "done") {
        const idx = pending.get(job.job_id)!
        results[idx] = { status: "done", creator: job.creator }
        pending.delete(job.job_id)
      } else if (job.status === "failed" || job.status === "not_found") {
        const idx = pending.get(job.job_id)!
        results[idx] = { status: job.status, error: job.error ?? "unknown" }
        pending.delete(job.job_id)
      }
    }
    delay = Math.min(delay * 2, 300_000)
  }

  return results
}

// Example usage
enrichRoster([
  { platform: "tiktok",    handle: "alixearle" },
  { platform: "instagram", handle: "MrBeast" },
  { platform: "youtube",   handle: "MrBeast" },
]).then((rows) => rows.forEach((r) => console.log(r)))

Most fresh scores complete in 10–90 minutes (depends on platform count + video-heavy posts that need transcription). We recommend polling every 60 seconds for the first 30 minutes, then every 5 minutes after that. Don't hammer — the eta_seconds field on every queued/processing response is your guide.

All errors return a consistent JSON shape:

{ "error": "error_code", "message": "Human-readable description." }

For job completion you have two options: poll /api/v1/jobs/{id} or configure a webhook on your API key. With a webhook configured, we POST a score.completed event the moment your job finishes, including the full creator payload — same shape as the GET response.

Set the URL at /account/api. The URL must be HTTPS. When you set or update it we generate a fresh signing secret and show it to you exactly once.

Delivery

We POST a JSON body with these headers:

X-CreatorScore-Event: score.completed       # or score.failed
X-CreatorScore-Signature: <hex HMAC-SHA256>
X-CreatorScore-Delivery: <delivery uuid>
X-CreatorScore-Attempt: 1                   # 1..5
Content-Type: application/json

Body

{
  "event": "score.completed",
  "job_id": "fa9b2c1e-...",
  "platform": "tiktok",
  "handle": "alixearle",
  "creator": { ...GET /api/v1/jobs/{id} 'done' creator field, WITH narrative + risk_flags (evidence) inline... },
  "report_url": "/api/v1/creators/tiktok/alixearle/report",
  "delivered_at": "2026-05-25T03:42:11Z"
}

The webhook carries the narrative and the evidence-bearing risk flags so a reviewer can act on it directly; report_url is the full report (brand mentions, drivers, PDF link) and costs nothing extra for the creator you just scored.

Verifying the signature

Compute HMAC-SHA256 over the raw request body using your signing secret. Compare with the X-CreatorScore-Signature header. Reject anything that doesn't match.

// Node.js (Next.js route example)
import { createHmac, timingSafeEqual } from "crypto"

export async function POST(req: Request) {
  const raw = await req.text()
  const sig = req.headers.get("x-creatorscore-signature") || ""
  const expected = createHmac("sha256", process.env.CREATORSCORE_WEBHOOK_SECRET!)
    .update(raw)
    .digest("hex")

  // Constant-time comparison; both must be the same length first.
  if (
    sig.length !== expected.length ||
    !timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
  ) {
    return new Response("bad signature", { status: 401 })
  }

  const event = JSON.parse(raw)
  // ... store event.creator, update your roster, etc.
  return new Response("ok")
}

Retries

We treat any non-2xx response (or connection failure / timeout >10s) as a retryable failure. Backoff is 30s → 1m → 5m → 30m → 2h, with up to 5 attempts. After that the delivery is marked failed and surfaced in your dashboard. Make your handler idempotent — duplicate deliveries are rare but possible.

Send an Idempotency-Key header (any string, 8–128 chars — use a UUID) on a charged POST (/creators/score-footprint, /creators/discover, /creators/vet, /creators/bulk) and retries become safe: the first request runs normally, and a retry with the same key + same body replays the stored response with Idempotency-Replay: true — nothing re-runs, nothing is charged twice.

• Same key + different body → 422 idempotency_key_reused (a client bug, never silently replayed)
• Retry while the original is still running → 409 idempotency_in_flight; retry in a few seconds
• Non-2xx outcomes are not stored — after a 402, top up and retry the same key for a genuine re-attempt
• Keys expire after 24 hours

curl -X POST https://creatorscore.io/api/v1/creators/score-footprint \
  -H "X-API-Key: sk_live_..." \
  -H "Idempotency-Key: 9b2f7c3e-8d41-4c5a-b1aa-2f5c9e7d1a03" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "tiktok", "handle": "alixearle", "confirm": true }'

Create a key with scope: "test" (it's issued with an sk_test_ prefix) and build against the real endpoints without spending a cent: every response is a deterministic fixture — nothing is scraped, scored, queued, charged, or written. Request validation still runs for real, so your error handling is exercised too.

• Every sandbox payload carries "sandbox": true — assert on it so production code can never be pointed at fixtures unnoticed
• Fixtures mirror the real response shapes field-for-field; IDs and timestamps are stable, so integration tests can snapshot them
• Any job_id polled on a test key returns done immediately with the fixture creator; a sandbox background check returns a completed report with sample flags

Each API key is rate-limited to 120 requests per minute (rolling 60-second window). Exceeding the limit returns 429 rate_limit_exceeded with a Retry-After header in seconds. The credit balance remains your real ceiling for fresh-score work — the rate limit is just there to prevent runaway loops.

The full machine-readable spec lives at /api/v1/openapi.json (OpenAPI 3.1). Use it to:

• Import the API into Postman / Insomnia in one click
• Generate a typed SDK in any language with openapi-generator or openapi-typescript
• Render interactive docs in Swagger UI / Redocly

# Generate a TypeScript client from the spec
npx openapi-typescript https://creatorscore.io/api/v1/openapi.json -o creatorscore-api.d.ts

This is v1. We'll add fields and endpoints without bumping the version; we won't remove or rename anything without bumping to v2 and maintaining v1 for at least 6 months after. Build clients that tolerate unknown fields.

One API for everyone. We don't fork behavior per customer: every integrator gets the same endpoints, the same response shapes, and the same semantics. Per-key configuration is limited to numeric limits (rate, daily caps, discovery pricing) — never different behavior.

Deprecations are announced by email to every active key at least 90 days ahead, and deprecated fields are marked in the OpenAPI spec before removal.

Email [email protected]. We respond same-day.