Creator API

GET/v1/health

Is the API up? No key needed.

{ "ok": true, "version": "1.0" }

GET/v1/me

The key you're using and whether its owner is the super admin.

{
  "key": { "id": "3f9a1c2b", "owner_id": "1444906668923027466", "name": "my-script",
           "hint": "tts_Ab3d…x9Qz", "created_at": "2026-11-05T09:12:44+00:00",
           "last_used_at": "2026-11-05T09:13:02+00:00", "revoked_at": null, "revoked_by": null },
  "is_admin": false
}

GET/v1/usage

Your scan data used today and what's left. All sizes are bytes.

{
  "usage": { "owner_id": "1444…", "day": "2026-11-05", "browser_bytes": 81234567,
             "country_bytes": 1203344, "total_bytes": 82437911 },
  "daily_limit_bytes": 5000000000,
  "scan_limit_bytes": 2500000000,
  "remaining_today_bytes": 4917562089
}

GET/v1/stats

Pool totals, the scan queue and whether the TikTok token is ready (the same numbers as /status).

{
  "pool": { "total": 10839, "eligible": 2210, "live_now": 14, "seen_live_7d": 640, "us": 3021,
            "by_status": { "new": 10500, "contacted": 120 }, "country_known": 5400,
            "country_unknown": 5439, "consistent_live": 310 },
  "queue": { "running": "a1b2c3d4e5f6", "waiting": 1 },
  "tiktok_token": { "present": true, "age_hours": 3.2 }
}

GET/v1/reference

Valid values for categories, leagues and sort.

{
  "categories": [ { "key": "gaming:fortnite", "label": "Fortnite" }, … ],
  "leagues": [ "D5", "D4", "D3", "D2", "D1", "C5", … , "A2", "A1" ],
  "sorts": [ "followers_desc", "followers_asc", "engagement_desc", … ]
}

GET/v1/creators

Search and page through saved creators. All filters are optional and combine with AND.

GET /v1/creators?country=US&min_followers=1000&live_only=true&limit=2

{
  "total": 14, "limit": 2, "offset": 0,
  "items": [ { "username": "examplecreator", "followers": 48200, "region": "US",
               "verified_live": true, "live_league": "C2", … }, … ]
}

To get everything, keep adding limit to offset until offset >= total, or use export.

GET/v1/creators/{username}

One creator plus their observed LIVE sessions (newest first, up to 20). The @ is optional and case doesn't matter.

{
  "creator": { "username": "examplecreator", … },
  "live_sessions": [ { "room_id": "7311…", "first_seen_at": "…", "last_seen_at": "…", "observed_days": 2 } ]
}

GET/v1/creators/export

Every creator matching the same filters as /v1/creators, in one download.

curl -H "Authorization: Bearer tts_YOUR_KEY" -o us.csv \
  "http://YOUR_SERVER:8787/v1/creators/export?country=US&format=csv"

POST/v1/jobs

Start a scan. Send a JSON body. Every field is optional. Returns 202 with the new job.

kind: "generate" (default) — same as /generate

kind: "autoscan" — same as /autoscan

Scans every category and ranks the most recruitable creators. Fields: country (default "US"), count (1–100, default 100), include_existing, unlimited_passes. Results carry _score, _grade and _why.

POST /v1/jobs
Content-Type: application/json

{ "country": "US", "count": 25, "categories": ["gaming:fortnite", "gaming:roblox"],
  "min_followers": 500, "max_followers": 50000 }

→ 202
{ "id": "a1b2c3d4e5f6", "kind": "generate", "state": "queued", "source": "api", "target": 25, … }

A 409 queue_unavailable means the queue is full or you already have a scan waiting.

GET/v1/jobs

Your recent jobs, newest first — including ones started in Discord. Results aren't included here; use results.

{ "items": [ { "id": "a1b2c3d4e5f6", "kind": "generate", "state": "running", … } ] }

GET/v1/jobs/{id}

One job with live progress while it runs. Add ?include_creators=true to include the result rows.

{
  "id": "a1b2c3d4e5f6", "kind": "generate", "state": "running", "source": "api",
  "target": 25, "created_at": "2026-11-05T09:20:01+00:00",
  "progress": { "phase": "Checking profiles", "currently_qualified": 7, … },
  "remaining_seconds": 1420.5,
  "data": { "used_bytes": 41022331, "limit_bytes": 2500000000, "limit_source": "scan" },
  "checkpoint": { "pass": 2, "dropped": { "region": 31, "min_followers": 12 } },
  "result_count": 7
}

GET/v1/jobs/{id}/results

The creators a job found. While it runs you get what's qualified so far; once it's finished you get the final list.

{ "state": "completed", "count": 25, "items": [ { "username": "examplecreator", … } ] }

POST/v1/jobs/{id}/stop

Stop a queued or running job. Work already done is kept. A running job moves to stopping, then stopped; a queued one becomes cancelled. No body needed.

curl -X POST -H "Authorization: Bearer tts_YOUR_KEY" \
  http://YOUR_SERVER:8787/v1/jobs/a1b2c3d4e5f6/stop