API Reference

List the per-game gaming boards a region offers — the source for the `game` parameter of board=gaming_game reads, built from captured switcher evidence, never a hardcoded list. `offered` games are readable now; `not_offered` names games TikTok has pulled. An empty list means the region runs only the aggregate gaming board (TikTok has not enabled per-game tabs there). Exposes no creator identity, so no masking applies.

List retained periods of an official rank board, newest first, with cursor pagination. Each period carries its own coverage status — partially captured periods are shown, not hidden. Identity masking follows the caller's plan tier, never the public teaser rule. The `shopping_daily`/`shopping_weekly` boards additionally require the `shop:read` scope (on top of `rank:read`); `board=gaming_game` requires `game`.

ES.2 — League "everyone seen": every creator of a region with League diamonds over a window — `today` (the open board day so far), `yesterday` (the newest closed day), or the last `7d` / `30d` / `90d` closed days — whether or not they were in their class's top 99 when a day closed. Biggest first; at least 1,000 diamonds (`min` raises it). A closed day counts TikTok's sealed number when the creator was in the class's top 99 at the close, else the highest reading of that day (a lower bound). `belowTop99=true` keeps creators never in the top 99 at a day's close (today: not on the class's current board). Identity follows the League board rule: below Scale the 3 biggest creators of the region's unfiltered list for the window show (wherever a filter places them) and every other row is masked (sealed `mk1_` uid, `•••••xx` handle and name). Today: `boardKnown` false = the creator's class has no League read in the last 30 min, so `rankNow` is unknown. An unknown `region` (no stored League day) is 400. `status: building` = the region's list is not built yet. Paged by `offset` + `limit` (≤ 100). 404 while the feature is off.

ES.2 — whether League "everyone seen" is on for the caller and what the caller's plan opens: `unmaskAll` (every handle, search, Copy all), `unmaskTier` (the plan that does, null when the caller has it) and `historyWindowDays` (how many board days back the plan reads; null = no limit — a longer window is 403 `plan_required`). Reads no row and is free (no credit), so a client can decide to show the list without spending one. 404 while the feature is off.

ES.2 — every handle (no `@`) of an "everyone seen" list under the same filters, biggest first, at most 50,000 (`truncated` when the list is longer) — "Copy all". Billed as one export. Needs the plan that shows every League handle (Scale); below it 403 `plan_required` (not billed). 404 while the feature is off.

Region movers (LT1.3): the creators whose rank changed most since the board's previous period, split into `gainers` (moved up) and `losers` (moved down), each biggest-move-first and capped by `limit` (1..99, default 20). Derived from the same official board read, so identity is masked by the caller's plan tier exactly as /v1/rankings/official — never an unmask backdoor. A gated/unpublished board returns empty lists. Shopping boards additionally require `shop:read`; `board=gaming_game` requires `game`.

Get an official (TikTok-observed) rank board with avatar, live status, movement, and honest coverage. Gated boards distinguish incomplete collection (not-covered) from boards TikTok does not publish in that region (not-offered). Creator identity (handle/nickname/avatar) is masked below the unlock tier; rank/score/movement/live always show. Board keys include `hourly`, `daily`, `popular_live`, `gaming_daily`, `gaming_weekly`, the per-game gaming board `gaming_game` (requires the `game` parameter — a game_key from /v1/rankings/gaming/games; the `game` parameter is refused on every other board), the `league_a1`..`league_d5` league boards, and the LIVE Shopping boards `shopping_daily` (rank_type 29, daily, SEA incl. SG) and `shopping_weekly` (rank_type 6, weekly Mon-reset, US/UK/BR/JP). Shopping score is ranking POINTS (not GMV/currency) and its two cadences are not comparable as one unit. The two shopping boards additionally require the `shop:read` scope (on top of `rank:read`).

List the regions a rank board can be read for, each with its coverage, its currently offered captured board keys, and `notOfferedBoards` — the boards proven absent from TikTok's product there. Disable only what `notOfferedBoards` names: a board missing from `boards` may simply be one we have not captured yet. Regions are BUCKET keys (US+, MENA, LATAM, DE+) — not ISO country codes, which match no board — and the list is built from captured availability, not from the crawl configuration.

Get the Teams & Clubs board (rank_type=18) for a region: TikTok LIVE fan-club COMMUNITIES ranked by combined diamonds, not creators. Each row carries the community (name, level, member count, image) + its representative host and score. Gated on the board's own capture like every board. The club name and host handle/name mask below the unlock tier; level/members/image/score always show.

Get the on-demand roster for one Teams & Clubs community host, keyed on the hostCreatorUid the board row exposes (the TikTok user id, or on a masked row the opaque `mk1_…` token, which opens only for the caller it was issued to — 404 otherwise), or on a TikTok @handle (`hostUid` all digits = uid, anything else = handle, resolved through TikTok; the response carries the numeric `creatorUid`, or a token when the host is masked): the persistent fan-club member list ("thành viên hàng đầu", ranked by lifetime member diamonds, with active/total counts) plus today's contributors ("người đóng góp hôm nay", with the next-reset countdown). Live-fetched from TikTok on request (never crawled/stored) and works whether or not the host is currently live. Member + host handle/name mask below the unlock tier (full roster unmasked at Agency); level/score/avatar always show. `section` (members|today) + `offset` page ONE list for load-more (absent = both lists, first page). 404 when the roster feature is disabled or the host does not resolve.

LP.4 — the TikTok LIVE Pro creator directory for a region: creators TikTok surfaces with the ✦ LIVE Pro badge (from the signed anchor/top_creator/list feed, collected over time into a membership union), freshest sighting first, with who is live right now. Handle/nickname mask below the unlock tier (avatar shown even when masked, like the rank boards); a masked row's live roomId is withheld. `region` is an ISO country code (call /v1/live-pro/regions for the live list — rankings bucket keys such as US+ match no directory); `liveOnly=true` restricts to currently-live members; `limit` caps the page (1..1000, default 100). Reads collected directory data only — never reaches TikTok.

LP.7 — the regions the LIVE Pro directory can be read for, each with its member count, how many are live now and its newest sighting. Built from collected directory data (never from the collector configuration), sorted by region code; ISO country codes, NOT the rankings bucket keys. Call this before guessing a region for /v1/live-pro. No parameters.

List creator LIVE performance

Get the LIVE video playback sources (HLS/FLV) for a creator who is live now (D2.12). `live:stream`, not `live:read` — this is the video, not the metrics. The customer's browser fetches the stream directly from TikTok's CDN (`source: tiktok-cdn`). Answers `200` with `status: no_playback`/`offline` when there is nothing to play, and `202` (poll the same URL) while a room is being resolved.

Queue an asynchronous LIVE refresh

REMOVED 2026-09-24 — answers 410 endpoint_removed. Use /v1/live/creators/{uid}/performance.

REMOVED 2026-09-24 — answers 410 endpoint_removed.

Mint a short-lived realtime WS handshake token (present it via the Authorization header or the Sec-WebSocket-Protocol subprotocol when dialing wss://<host>/v1/live/stream — never in the URL)

List the gifters funding one creator in a window, ranked by diamonds given to them

List the gifters of one creator's current LIVE session by their cumulative coins in it (TikTok's in-room ranking); offline → their last session for ~2 h (session.isLive false); session null = no live or recent session tracked

List top observed gifters (whales) by diamonds in a window (24h/yesterday/7d/30d), optionally for one creator

Get one gifter's observed totals in a window and the creators they fund (who-funds-whom)

GH.3 — one gifter's daily history grouped by day|week|month|year (UTC) and split by the creators they gave to, from the long-term daily store. Pro or above; `range` (days, default and cap = the plan's historyWindowDays, 365 when unlimited) is clamped to the plan's read window (`historyTruncated`). The store keeps a gifter's day only when their day total reached `coverage.minDailyCoins` and holds days from `coverage.dataSince`; days the poller covered only in part are in `coverage.partialDays` (their figures are a minimum). Weeks start on Monday, all boundaries UTC.

Search/browse the already-observed creator set, most-followed first (never a live TikTok search). Without a search `q` (none, or under 3 characters after the `@`) it is always the finder below (most-followed first, masked below `agency`, ≤ 50 a page; RM — a bare or one-letter call no longer lists the corpus unmasked); a 3+ character `q` filters by handle/display-name substring (case-insensitive). Suppressed creators are excluded. **LT2.1 recruiting finder:** without `q`, the filters `region`, `minFollowers`, `liveNow` and `sort` (`followers` default | `rank` = the region's current Daily board order) browse the pool with `cursor`/`nextCursor` pagination. Creator identity (handle/name/avatar) is masked below the `agency` tier (`masked:true`, `unmaskTier`); `region`/`followerCount`/`isLive`/`verified` always show. A `q` search is never masked.

Get a public creator profile with metric history. An account we have no fresh copy of is resolved from TikTok on demand (billed `profile-resolve` once per upstream fetch — other reads riding the same resolve, in any spelling or workspace, are `cached-read`; a 202'd workspace's poll that delivers a resolve which ended after its 202 books it, once, within 10 minutes — CR.17/CR.4); a store hit is billed `cached-read`. A resolve that exceeds the synchronous budget, or whose signed fetch fails upstream (signer down, TikTok 429/5xx) with no real stored profile to serve, answers 202 — poll this same URL. A failure on a deployment with only the anonymous path, and a profile call that answers a non-zero status with no user, still read as a miss. A miss (TikTok says nobody holds the handle) is a 404 `creator_not_found`, not billed, when nothing real is stored under the handle — no row, or only a stub (counts / identity only, CR.10) — and no former holder matches. `{uid}`: a bare all-digit value is the stored user id first, then a numeric handle; `@N` or a profile URL is always the handle. A creator found by its user id is refreshed by its own identity (sec_uid, else user id; a 202 then carries jobId `resolve:uid:<id>`), never by searching the number as a handle, and an upstream answer for another account is never served (CR.14); see the Outcomes table in the API contracts.

Full-analysis report for one creator (R4.4): engagement rates, posting cadence, top videos, audience signal from collected comments and follower growth — all derived from stored observations, never fetched at read time. Coverage is always `partial` and `limits` names each gap. `{uid}`: a bare all-digit value is the stored user id first, then a numeric handle; `@N` or a profile URL is always the handle (CR.14).

Timeline of observed identity changes (handle, display name, avatar, bio, region, verification) for one creator. `{uid}`: a bare all-digit value is the stored user id first, then a numeric handle; `@N` or a profile URL is always the handle (CR.14).

List a creator's followers (R4.5). Same collection path as `/following`, but TikTok streams followers newest-first and never declares an end, so the response is always a SAMPLE of the most recent followers — compare `storedCount` with `totalReported`. `{uid}`: a bare all-digit value is the stored user id first, then a numeric handle; `@N` or a profile URL is always the handle (CR.14).

List the accounts a creator follows (R4.5). Collected on demand through the signed mobile list API when we hold nothing fresh (billed `follow-list-resolve` once per walk, to the read that receives it: the first poll waiting as the walk ends books it, the other polls riding the walk pay `cached-read`, and the first read after a walk that ended after its 202 books it for the workspace that was answered 202 or a partial 200, once, within 10 minutes — CR.4); a store hit is `cached-read`. The first call for an uncollected account normally answers 202 — poll this same URL. Paginate with the opaque `cursor`. `{uid}`: a bare all-digit value is the stored user id first, then a numeric handle; `@N` or a profile URL is always the handle (CR.14). An owner found by its user id is walked by its own stored handle, and a walk that comes back for another account is never served.

Get a creator's active story tray (D6.1). Content, so it is `content:read` (grouped with videos, not the profile read). Resolves store-first like the profile read, then fetches the tray FRESH through the signed mobile path — stories are ephemeral and never stored. Degrades to an empty tray when no signed credential is configured. Priced like the profile read (CR.3): `profile-resolve` when this read resolved the creator from TikTok (once per fetch, CR.17), `cached-read` for a store hit — except the poll that delivers a resolve this workspace was answered 202 for (1,250, once, within 10 minutes, CR.4); a 202 (profile resolve pending, or its signed fetch failing upstream) and a 404 (the profile read's miss, CR.10 included) are not billed.

List a creator's public videos with current metrics. `{uid}`: a bare all-digit value is the stored user id first, then a numeric handle; `@N` or a profile URL is always the handle (CR.14).

AR.13 — bulk handle lookup: 1–100 handles, @handles or tiktok.com profile / LIVE links → what the platform ALREADY STORES about each, in one call. Never reads TikTok on the call (a fresh live status is the in-app Live check, `POST /v1/watchlist/live-check`). Per item: `found`, `creatorUid`, `displayName`, `avatarUrl`, `followers`, `region` + `regionSource` (`profile` = ISO country from the creator's profile; `board` = the country board they rank on, which can be a multi-country bucket such as `MENA` or `US+`; null = unknown, never guessed), `live` (the newest stored reading from the last 15 minutes — our own tracking, or this workspace's watchlist — else null), `lastSeenLive` and `profileRefreshedAt`. Repeats collapse (first spelling wins); an input that is not a handle comes back with `handle: null` and is not charged; a creator we hold nothing about — or who asked to be removed — is `found: false`. Metered as one `cached-read` per DISTINCT valid handle (`creditsCharged` echoes the charge; 0 in the app).

Get one public video with per-video metric history

List a public video's comments (R4.3). Collected anonymously from TikTok on demand when we hold nothing fresh (billed `comments-collect` once per collection, to the read that receives it — CR.4, as for follow lists); a store hit is billed `cached-read`. Paginate with the opaque `cursor` returned by the previous page, and pass `parentCommentId` to page one comment's replies. `503 comments_unavailable` (`retryable: false`, not billed) instead of a `404` when collection is off on this deployment and the thread was never collected (CR.20).

List public trending hashtags/sounds for a region (honest coverage)

List workspace exports

Create an export (format csv|xlsx). The job's filename names its main scope and the UTC minute it was made, kept short: toktik-<dataset>[-<scope>]-<YYYYMMDD>-<HHmm>.<format> (EX.7b). Datasets: rankings (needs region + either board or boards — several boards in one file, CSV stacked / XLSX one sheet per board; optional game for a per-game gaming board and period=current|history), gifters (optional region + segment + window=24h|yesterday|7d|30d: the board on screen; without window, rangeDays is bucketed to 24h/7d/30d), creator_roster (the watchlist as a file; with rosterOnly=true just the signed hosts + roster/KPI/commission-estimate columns over rosterWindow 7d|30d|90d), creator_gifters (needs creatorUniqueId; window=24h|yesterday|7d|30d|live, default 7d; Live module only; capped by plan like the read: Free top 3 / Starter top 3 / Pro+ all), gifter_funded_creators (the whale drill-in's funded-creators list; needs gifterKey; window=24h|yesterday|7d|30d default 7d; Live module only), teams (the Teams & Clubs board; needs region), team_roster (one community's roster; needs hostUid; optional section=members|today), live_pro (one region's LIVE Pro creator directory; needs region; Live-module data), gifter_watchlist (GA.2b — the workspace's gifter watchlist as a file: the board columns over window=24h|yesterday|7d|30d default 7d, plus live status and each gifter's alert settings; Pro+, 403 gifter_watchlist_upgrade_required below it), recruit (the recruiting pool of GET /v1/recruit as a file, up to 60000 rows — 400 export_too_large past it; optional region + excludeLivePro/newOnly/minFollowers/maxCoins30d/live/country — the same filters as the read; the mark/mark_note columns are this workspace's own marks). league_window (ES.2 — Rankings › League "everyone seen" as a file; needs region (not GLOBAL) + optional leagueWindow/leagueClass/minDiamonds/belowTop99 — the same filters as GET /v1/rankings/league-window; the biggest 50000 rows when more match (GET /v1/rankings/league-window's `total` says how many); a window longer than the plan's history window is 403 plan_required; one diamonds column per bar of the window; a masked row keeps its numbers but its unique_id and nickname cells are empty, and its `masked` column is true — the file never carries a masked handle; 404 league_window_unavailable while the list is off). Rankings/teams/live_pro/recruit/league_window honour the caller's tier identity-mask (export is not an unmask backdoor). 400 invalid_format/invalid_request; 403 export_format_not_entitled if the plan lacks the format; rankings/gifters/creator_gifters/gifter_funded_creators/live_pro/recruit/league_window are Live-module data: 403 module_not_entitled without Live, 503 entitlement_unavailable when the entitlement cannot be resolved; team_roster: 404 team_roster_unavailable when the roster feature is off; rankings with boards: 404 board_unavailable when one of them is not published for the region

Get one export job

Download a completed export (CSV or XLSX, with a format-appropriate content-type)

List the workspace's watchlist creators (D6.1). Sold under `watchlist:manage`; not credit-metered. `?roster=1` (AO.1) lists only the signed hosts: `404` while the roster is not enabled on this deployment, `403 plan_required` below Agency.

Add a creator to the workspace watchlist (D6.1). `409 watchlist_full` at the 25-entry cap; `409` on a duplicate handle (case-insensitive).

Remove a host from the roster (AO.1). The creator STAYS on the watchlist. `404 not_on_roster` when it was not a host; Agency plan only.

Flag a watched creator as a signed host (AO.1). Agency plan only (`403 plan_required` below it); `404` while the roster is not enabled on this deployment. A creator not yet watched is added first and takes one slot (`409 watchlist_full` at the cap); an already-watched creator takes none. `status` defaults to `active`, `signedOn` to today (UTC); omitted fields keep their value. AO.5 — also accepts the owner / follow-up / contract-end fields below; each changed field appends one line to the host's history (an unchanged re-PUT appends none). Returns the entry with its roster fields.

AO.11 — record that you contacted a roster host. Send a JSON object (`{}` for no note). Appends one `contact` line to the host's history (with your optional note, at most 200 characters, else `400 invalid_contact_note`) and hides the host from the Today list for 3 days. A `manager` may log on its own assigned hosts only; any other handle is the same `404 not_on_roster`. Agency plan only; `404` while the roster is not enabled.

AO.5 — the history of a roster host (roster status, owner, follow-up, contract-end and note changes), newest first, at most 50; it also carries the lines recorded while the same creator was a recruit mark (`subject: recruit`, matched through the host's pinned creator uid). Never another workspace's. Agency plan only (`403 plan_required` below it); `404` while the roster is not enabled, or when the handle is not on the roster.

Remove a creator from the workspace watchlist (D6.1)

Stop watching up to 100 creators in ONE transaction — the many-at-once form of `DELETE /v1/watchlist/{id}` (owner / member / API key; a manager is refused `403 forbidden_role`). A host on the roster leaves it too, because the entry itself is deleted. Handles are normalised (lowercase, `@` stripped) and de-duplicated. A handle that is not on THIS workspace's watchlist (or not a valid handle) is never touched and is returned in `skipped` — the answer does not reveal whether another workspace has it. 0 handles, more than 100, an unknown key or a non-array / non-string `handles` is `400`. Sold under `watchlist:manage`; not credit-metered.

Bulk-import creators to the workspace watchlist (WL.8): add up to 500 handles at once (paste / CSV). Returns a per-input outcome (`added` / `duplicate` / `invalid` / `limit_reached`) plus counts; a repeated handle collapses to one result, a handle whose creator is already watched under another handle (same TikTok uid — they renamed) is `duplicate` with `watchedAs` (RN.6a), and new creators beyond the tier's pin cap are `limit_reached` rather than an error. With `asRoster: true` (Agency plan, roster enabled) the creators become signed hosts: new ones take a watchlist slot (same cap as a single add), already-watched non-hosts are `promoted` (no slot), existing hosts are `duplicate` and left untouched, and `assigneeUserId` assigns every host created; the response then also carries `summary.promoted` and `roster`. Sold under `watchlist:manage`; not credit-metered.

Bulk live check (LC.1 + AR.13): paste up to 200 @handles or tiktok.com profile / LIVE links and get who is live RIGHT NOW (a fresh read from TikTok per handle, usually 5–15 s for 100). Each result is `live` (with the current `roomId` and, when TikTok sends it, `liveStartedAt`), `offline`, `not_found` (TikTok says no account has that handle — renamed or deleted), `unknown` (TikTok did not answer, even after one retry) or `invalid`; repeats collapse. AR.13 — every answer also carries what the platform already stores: `creatorUid`, `followers`, `region` + `regionSource` (`profile` = ISO country from the creator's profile; `board` = the country board they rank on, which can be a multi-country bucket such as `MENA` or `US+`; null = unknown, never guessed), `lastSeenLive` (our own tracking, or THIS workspace's watchlist) and `onLists` (this workspace's watchlist / roster / recruiting mark — never another workspace's). These AR.13 fields are filled for a signed-in (in-app) check only: an API key gets the LC.1 fields plus `not_found`, with the AR.13 fields null (the same facts are sold per handle by `POST /v1/creators/batch`). Nothing is saved to the watchlist. Sold under `watchlist:manage`; not credit-metered; limited to 30 checks per workspace per hour, one at a time (`429 live_check_rate_limited` / `live_check_busy`); a check where TikTok answered nothing is not counted. `quota` reports the budget after the check.

AR.13 — this workspace's live-check budget in the rolling hour (`used` of `limit`; `nextSlotAt` = when the oldest counted check leaves the window). Read-only; never counts as a check. Sold under `watchlist:manage`; not credit-metered.

Poll each watched creator's current live state (WL.1). The same `isLive` the list computes, minus enrichment, for a lightweight in-place refresh. Sold under `watchlist:manage`; not credit-metered.

Bulk roster action on up to 100 hosts in ONE transaction (owner / member / API key; a manager is refused `403 forbidden_role`). `assign` sets (or, with `assigneeUserId: null`, clears) the owner of every listed host that is on the roster; `remove` unflags them with exactly the single `DELETE /v1/watchlist/{handle}/roster` semantics (the creator stays on the watchlist; signed / left dates, roster note, owner, follow-up, contract end and commission % are cleared). Handles are normalised (lowercase, `@` stripped) and de-duplicated. A handle that is not on THIS workspace's roster (or not a valid handle) is never created or touched and is returned in `skipped` — the answer does not reveal whether another workspace has it. `assign` is idempotent: a host that already has that owner counts as `unchanged` and writes no history line; each changed host appends the same history line the single PUT would. The assignee must be a CURRENT member of this workspace (`422 assignee_not_member`). Agency plan only (`403 plan_required`); `404` while the roster is not enabled. 0 handles or more than 100 is `400`.

Health band + reasons for every roster host (AO.3). Always the host's last 7 CLOSED UTC days against its own preceding 28 (never the KPI window selector). Bands: healthy | watch | at_risk | new (under 14 baseline days or a partly-covered recent week — not judged) | unscored (paused, left, or the handle is not matched). Every band carries at least one reason with a stable `code`; `evaluated` lists the signals that had enough data (league needs about a week of snapshots). Judged only from gifts the platform observed in the rooms it polls: 'no gifts observed' is never 'not live', and a host with no observed gifts in its baseline is `watch`, not `at_risk`. Agency plan only (`403 plan_required` below it); `404` while the roster is not enabled on this deployment.

Per-host KPIs for the workspace's roster (AO.2): observed diamonds over the last 7/30/90 CLOSED UTC days, the change against the previous equal window, days with gifts, a daily series, followers and the newest league standing. Every figure is a LOWER BOUND observed from the rooms the platform polls (coins = diamonds 1:1) — never TikTok's number and never earnings. Each host also carries the agency's own `splitPct` and a `commission` ESTIMATE (observed diamonds x `diamondUsdRate` x that %), with `commissionTotals` over active hosts. A window reports `coverageDays`: `ok` when every day has data, `partial` (>= 7 days) with the real count, else `insufficient_history` with no number; a day without data is `null`, never 0, and nothing is interpolated. Agency plan only (`403 plan_required` below it); `404` while the roster is not enabled on this deployment.

AO.11 — the 'Today' list: the roster hosts that need action now, at most 10, most urgent first, with the stable reason codes behind each row. Built ONLY from signals the platform already has: the host's health band (AO.3), the follow-up and contract-end days the agency typed (AO.5) and the contact log below. Order is fixed by the tier of the strongest reason (health_at_risk, follow_up_overdue, contract_ending, health_watch, no_contact, follow_up_due, unassigned), then more reasons first, then more observed diamonds in the last 7 closed days first, then handle. A host with a contact logged in the last 3 days is hidden; a host signed in the last 7 days is not flagged `no_contact`; `unassigned` only fires when at least one host of the workspace has an owner. `snoozed` counts the hosts that would qualify but are hidden by a recent contact. `notJudged` counts active hosts the health judgement cannot score yet (new or unmatched), so a short list is never read as 'all fine'. A `manager` session sees only its own assigned hosts (no owners, no `unassigned`). Agency plan only (`403 plan_required` below it); `404` while the roster is not enabled on this deployment.

AR.5 — the delivery log: what happened to each alert / host alert / recruit digest / weekly report sent to this workspace's channels (delivered, failed with a short sanitized reason, or capped by the metering cap). Newest first; test sends are hidden unless `includeTest=true`. Telegram is `delivered` once handed to the Telegram sender and is settled to the real send result moments later. Rows are kept 90 days. Not credit-metered.

List webhook/alert rules

Create a webhook/alert rule. Any webhook channel's signing secret is returned ONCE in `webhookSecrets` — store it now.

Delete a webhook/alert rule

Update a webhook/alert rule (partial). Returns the updated rule. `scope`+`creatorUniqueId` are coupled — moving to `watchlist`/`any` drops the handle; `creator` requires one. A `gifter_watchlist` rule stays gifter-scoped (only name / channels / enabled are editable); re-enabling one is Pro+.

Fire a synthetic test event through a rule's channels to verify delivery (does not consume the live event stream)

AD.2 — the TikTok LIVE agency directory (TikTok's own LIVE Creator Network registry, swept by id): name, TikTok region bucket, onboarding date, official account, services, TikTok's size bands and TikTok's apply deep link. Filter by `region` (TikTok's bucket verbatim — see /v1/agencies/regions), `q` (name or official handle contains), `serviceType`, `publicProfileOnly`; `sort` size (default) | newest | name; page with `limit` (1..100, default 24) + `offset`. List rows never carry contact details — read one agency for those. Reads collected data only — never reaches TikTok.

AD.2 — one agency in full: everything in the list row plus its published introduction, its contact details (email / phone / address — public on every plan) and its website / apply / Discord links when known. 404 `agency_not_found` when TikTok's catalog holds no such id.

AD.2 — the region buckets the agency directory holds, each with its agency count, how many published a public profile and its newest onboarding, largest first, plus whole-directory totals. Buckets are TikTok's own agency regions verbatim (MENA, US+, …) — NOT the rankings bucket keys or ISO codes; `null` groups agencies that left the region empty. No parameters.

List workspace API keys (metadata only — never a secret)

Create an API key. The full secret token is returned ONCE in `token` — store it now.

Revoke a workspace API key

Get the workspace's plan tier, modules, limits (incl. exportFormats) and credit position

GA.2 — the workspace's GIFTER watchlist: gifters (any @handle) you watch, each with live status and the Gifters-board figures (diamonds, est. value, sessions, region, segment…) over `?window=24h|yesterday|7d|30d` (default 7d), plus its own alert settings. Pro plan or above uses it (below Pro returns 200 with `access.allowed: false` and an empty list). Cap: Pro 10 · Scale 30 · Agency 100 (enforced on add; a list already over a lowered cap keeps its gifters). The alert that fires when a listed gifter is gifting in a covered live is ONE alert rule with scope `gifter_watchlist` (POST /v1/alerts/rules). Sold under `watchlist:manage`; not credit-metered.

GA.2 — add gifters to the workspace's gifter watchlist. Each item is `{ gifterKey }` (picked from observed data) or `{ handle }` (any @handle; unseen handles are resolved via TikTok and watched anyway). Up to 10 per request; per-item outcome `added` / `exists` / `not_found` / `limit_reached` / `invalid` / `unavailable`. 403 gifter_watchlist_upgrade_required below Pro. Sold under `watchlist:manage`; not credit-metered.

GA.2 — remove a gifter from the workspace's gifter watchlist

GA.2b — change ONE listed gifter's alert settings: `alertEnabled` (mute), `alertMinCoins` (fire only once the gifter has given at least this many coins in the live; null clears), `alertChannels` (narrow to a subset of the shared alert rule's channel types; null = all of them). Pro plan or above (403 gifter_watchlist_upgrade_required below it). Returns the updated entry.

GB.4 — the goody-bag watch lane's capacity as this workspace sees it: whether the lane is on, its sweep `intervalMs`, the rooms it can sweep (`capacity`), rooms already promised to other workspaces (`claimedByOthers`), the rooms still `available` to this workspace (bounded by its own grant), and the grant itself (`entitlement.includedRooms`, `expiresAt`; `entitlementExpired` when it ended). Workspace configuration of a granted capability, not credit-metered. Sold under `goodybag:manage`.

PB.10 — the countries scanned for this workspace's `top` set: every rank board read now (`code` such as VN, US+, MENA, its name, flag, the countries a group board covers, `enabled`, and how many of the set's rooms sit on it), plus the priority countries (ISO-2) whose live rooms take the set's slots first. A set pinned to one board (`region`) lists that board alone. 404 `watch_set_not_found` before a set exists, 409 `countries_need_top_set` on a `custom` set. Sold under `goodybag:manage`; not credit-metered.

PB.10 — change what the set scans. `boards` maps board codes to `false` (leave the board out of the ranking pool) or `true` (scan it again); boards not named keep their state. `priorityCountries` replaces the priority list (≤ 10 ISO-2 codes, `[]` clears it); a priority country is scanned even when its board is switched off. The workspace's own lists (priority creators, follow lists) are never filtered by board. The lane follows on its next refresh (~30 s). Every malformed JSON body is 400 `invalid_countries` — nothing is coerced or dropped (a body that is not JSON at all is 400 `bad_request`): a value that is not exactly `true`/`false`, an unknown field (`details.unknownFields`), one board named twice with different values (`details.conflicting`), an unknown board code (`details.unknown`), a bad priority list. 409 `countries_region_pinned` when `boards` is sent for a set pinned to one board. Sold under `goodybag:manage`.

TB.7 — how much this workspace's goody-bag / treasure-chest feed covers: `monitoredRooms` (rooms in the set now), `regions` (distinct regional boards they come from, e.g. VN, US+, LATAM) with their `regionCodes`, and `updatedAt` (when the set was last refilled). Sold under `goodybag:manage`; not credit-metered.

PB.14 — look up several goody bags / treasure chests this workspace's feed sent, by the `eventId` of their `goodybag.event` frames (`ids`, comma-separated or repeated, ≤ 50), with fresh numbers: viewers in the room now and the bag's latest joined count. Ids this workspace was not sent come back in `notFound`. 400 `invalid_event_id` for a malformed id (`details.invalid`) or more than 50; 403 `goodybag_not_entitled` / `goodybag_entitlement_expired` without an in-force grant. Sold under `goodybag:read`; not credit-metered.

PB.14 — one goody bag / treasure chest this workspace's feed sent, by the `eventId` of its `goodybag.event` frame, with viewers in the room now and the bag's latest joined count. 404 `event_not_found` when this workspace was not sent it; 400 `invalid_event_id`; 403 `goodybag_not_entitled` / `goodybag_entitlement_expired` without an in-force grant. Sold under `goodybag:read`; not credit-metered.

PB.11 — the accounts (≤ 5) whose FOLLOWING list this workspace has asked us to scan for live rooms, each with `status` (`ok` readable and scanned, `hidden` a private account or a hidden following list, `reading` still being read, `not_found` no account under this handle; only `ok` is scanned), how many accounts it follows and how many of them are scanned. Each list is read again every 7 days. Requires a `top` set. Sold under `goodybag:manage`; not credit-metered.

PB.11 — add accounts (TikTok handles, ≤ 5 in all) whose following list is scanned for live rooms in addition to the leaderboard set. The list is read at once and `results` answers per submitted handle: `ok` (readable, with the number of accounts it follows), `hidden` (a private account or a hidden following list — a new handle is NOT kept; make it public and send it again), `reading` (a long list still being read), `not_found`. Rooms found this way count against the purchased rooms and hold their slots ahead of the ranking; their frames carry `is_bxh: 0` (rooms the platform picks — creators on a leaderboard or who have been on one — carry `is_bxh: 1`). 409 `follow_sources_limit`, 409 `follow_needs_top_set`, 503 `follow_lists_unavailable`. Sold under `goodybag:manage`.

PB.11 — stop scanning one account's following list; its rooms leave the set on the next refresh. 404 `follow_source_not_found` when it is not listed. Sold under `goodybag:manage`.

TB.9 — the priority creators of this workspace's `top` goody-bag / treasure-chest set, each with its status from the last refresh: `live` (holds a slot), `offline` (slot given back to the ranking pool until they go live), `not_tracked` (not on any regional rank board, so liveness is not known), `over_size`, or `pending` (not checked yet). Sold under `goodybag:manage`; not credit-metered.

TB.9 — add creators (handles or numeric creator ids, ≤ 500 per call) to the priority list of the `top` set without replacing the ranking pool or the creators already listed. Live priority creators take slots first; the set's total stays `size`. 409 `priority_limit` past the list limit, 409 `priority_needs_top_set` on a `custom` set. Sold under `goodybag:manage`.

TB.9 — remove one creator (handle or numeric creator id) from the priority list; its slot returns to the ranking pool on the next refresh. 404 `priority_not_found` when it is not listed. Sold under `goodybag:manage`.

GB.4 — remove this workspace's goody-bag watch set (the lane stops sweeping its rooms within one refresh). Sold under `goodybag:manage`.

GB.4 — this workspace's goody-bag watch set (`null` until one is set) and the lane capacity. A `top` set watches the N best-ranked live rooms; a `custom` set watches the live rooms of the creators listed (`entries`, each with the status the last refresh found: live | offline | not_tracked | over_size | pending — never dropped silently). `rooms` is how many live rooms the set holds right now; the lane refills it as rooms end. Sold under `goodybag:manage`; not credit-metered.

GB.4 — create or replace this workspace's goody-bag watch set; idempotent. Body `{ mode: top|custom, size (1..100000: the most live rooms watched), region? (top only: a board region code), priorityCountries? (top only, ≤ 10 ISO-2 codes: those countries' live rooms fill first, then the ranking; omitted keeps the stored list, `[]` clears it), enabled? (default true), entries? (custom only, ≤ 5000 creator handles or numeric creator ids) }`. Refused `403 goodybag_not_entitled` / `goodybag_entitlement_expired` without an in-force grant, `409 goodybag_plan_limit` when `size` is above the grant, `409 goodybag_lane_capacity` (retryable) when the lane has not enough free rooms (`details.available`), `400 invalid_watch_set` for a malformed body. The rooms themselves are filled by the lane within one refresh (~30 s). Receive the bags over the realtime WebSocket `goodybag.*` plane (token scope `goodybag:read`). Sold under `goodybag:manage`.

PUBLIC (token only): turn product-update emails back on for the user named by the token. Idempotent. Token in the form body or the query string. HTML.

PUBLIC (token only): the page the product-update emails' unsubscribe link opens. It shows an Unsubscribe button and changes NOTHING (a mail scanner prefetching the link cannot unsubscribe anyone); if the user is already unsubscribed it offers Resubscribe instead. HTML. No email address is printed.

PUBLIC (token only): opt the user named by the signed `product-updates-unsub` token out of product-update emails, idempotently. The token comes from the form body (`token=`) or the query string (the RFC 8058 one-click request: `application/x-www-form-urlencoded` body `List-Unsubscribe=One-Click`, token in the URL). The response page carries a Resubscribe button. HTML.

EC.1 — the recruiting pool: creators on a current board, live or not (EC.14 — live creators come first whatever the sort; `isLive` marks them; `live=live|offline|all` filters, default all) (EC.11: every board the collector reads — Daily, every League class, Hourly, Popular LIVE, Gaming, Shopping), enriched with today's score on their best board (`scoreBoard`: Daily first, then League, then the rest), the 30-day diamonds (`diamonds30d`: an estimate from TikTok's own board numbers and the gifts we observed, an upper bound, the days with a TikTok number, the real window and an under | check | over signal against the ceiling), followers/verified, and the ✦ LIVE Pro badge, so an agency can find who is worth recruiting. It never computes eligibility (the agency checks that in TikTok's backstage). Identity (handle/nickname/avatar/roomId) masks below the Agency unlock tier; RM.9 — so do the numbers that would find a masked row on a board: rank, scoreToday, the 30-day figures and the followers become ranges (`rankBand` / `scoreBand` / `diamonds30d.estimateBand` / `followerBand`, the exact fields null, coins30d null), `movement` and `diamonds30d.daysWithTiktok` are null too (`daysWithTiktokBand`; `newOnly` is ignored), every sort orders masked rows on those ranges (ties in a secret-keyed per-viewer order), and `minScoreToday` / `minFollowers` / `maxCoins30d` (and so the ceiling `status` is read against) snap down to a range start (`stats.ceiling` reports it). `region` is a board bucket (empty = every bucket); `excludeLivePro` (default true) hides current LIVE Pro badge-holders; `maxCoins30d` is the 'not yet graduated' ceiling — it drops rows whose 30-day ESTIMATE is above it and sets the ceiling `diamonds30d.status` is computed against (default 500000); `newOnly` keeps movement=new; `minFollowers`/`minScoreToday` filter; every filter runs over the whole pool before paging; `sort` = score|diamonds30d|coins30d|followers|rank (default score; score = today's diamond score, creators only on point boards after; EC.7's removed liveFirst|windowScore are read as score); `minScoreToday` compares scoreToday whatever the board (diamonds or points); `limit` 1..200; `cursor` pages. The EC.7 not-live read (`includeOffline`, `from`/`to`, `minDaysOnBoard`, `minWindowScore`/`maxWindowScore`) was removed in EC.11 — those parameters are now ignored. Reads collected data only — never reaches TikTok.

EC.12 — one creator's 30-day diamonds with every board day of the window (the Recruit creator panel): per day TikTok's own number and where it came from (a sealed Daily / League final is exact; a reading during the day is a minimum), the gifts we observed, what the day adds to the estimate and the most it can be. `diamonds30d` is the same as on the creator's /v1/recruit row (read fresh, so it can differ from a row read up to a few minutes earlier); `maxCoins30d` = the ceiling its status is computed against (default 500000). `creatorUid` = the TikTok user id (digits), or the opaque `mk1_…` token a masked /v1/recruit row carries instead (below Agency); a token opens only for the workspace it was issued to (404 otherwise) and is echoed back as `creatorUid`; RM.9 — by token, Agency plan or above (403 plan_required below it): a masked creator's exact board days would match them on past boards; by uid any tier (a creator the caller already knows, e.g. from Rankings). Numbers only — no identity; a creator with no board day in our data returns `days: []`. Reads collected data only — never reaches TikTok.

EC.5 — delete this workspace's digest subscription (and its 'sent' memory). `removed` is false when there was none. Agency plan or above.

EC.5 — this workspace's Recruit Creator Digest subscription (or null), plus the cadence floor in force (`minCadenceHours`) and the cadences a client may pick. One subscription per workspace, delivered through the workspace's EXISTING alert channels. Agency plan or above (403 plan_required below it). Workspace-owned config, not credit-metered. 404 while the digest flag is off.

EC.5 — create or replace this workspace's digest subscription; idempotent. Body `{ cadence: 6h|12h|daily|weekly (6h only when the floor allows), mode?: full|new_only (default new_only), countries?: string[] (resolved-country codes; empty = all), skipMarked? (default true), conditions?: { excludeLivePro? (default true), newlyRankedOnly? (default false), maxCoins30d? (int 0..1e12 or null = no ceiling on the 30-day estimate; a NEW subscription defaults to 500000), minFollowers? (int 0..1e10 or null) } — the Recruit-page filters as digest conditions; topCount? (EC.8: 5|10|25, default 10 — names listed in the message, the full list is in the Excel attachment); omitted keeps the current values, and each delivered digest states them (webhook: `digest.conditions`), channelIds: string[] (0..10 enabled channels that belong to THIS workspace's alert rules — may be empty when sendToAccountEmail is true), sendToAccountEmail? (the built-in email delivery, independent of alert channels; omitted keeps the current value, off for a new subscription via the API; needs a signed-in session or an `emailRecipient`), emailRecipient? (string = a NEW address that must be CONFIRMED by an emailed link before it receives anything — digests keep going to the previous recipient meanwhile; null = back to the account email; omitted = unchanged), enabled? (default true) }`. A digest needs at least one of the built-in email or an enabled channel. A channel of another workspace, or a disabled one, is refused (400 invalid_recruit_digest_input). A new/changed cadence schedules the next run one cadence from now. Agency plan or above.

EC.5b — drop the address awaiting confirmation (its emailed link stops working). Digests are untouched. Agency plan or above.

EC.5b — PUBLIC (token only): the page an emailed confirmation link opens. It shows a Confirm button and changes nothing (a mail scanner prefetching the link cannot confirm for the recipient). HTML.

EC.5b — PUBLIC (token only): confirm the address named by the signed, 48-hour token; from then on digests go to it. The token binds the subscription, its workspace and the exact address, so it cannot confirm anything else, and it stops working once the pending address changes or is cancelled. HTML.

EC.5b — mail the confirmation link again for the address awaiting confirmation (rate-limited to 3 confirmation emails per subscription per UTC day, drawn from the daily digest-email budget). 409 when nothing is pending. Agency plan or above.

EC.5 — 'send me a test digest now': enqueues one small sample digest (≤ 10 creators, subject-prefixed [TEST]) to the subscription's selected, enabled channels. Never advances the schedule and never records 'sent' memory. Rate-limited to one per minute per workspace (429). 404 when there is no subscription. Agency plan or above.

EC.2 — this workspace's recruiting marks (the agency's own status per creator: checked | eligible | ineligible | contacted | signed), newest change first, optionally one `status`; `limit` 1..200 (default 50) and `cursor` page. Private to the workspace — never another's. Agency plan or above (403 plan_required below it). Workspace-owned data, not credit-metered.

EC.2 — clear this workspace's mark for a creator. `removed` is false when there was no mark (idempotent). Agency plan or above.

EC.2 — set (or overwrite) this workspace's mark for a creator; idempotent. Body `{ status, note?, assigneeUserId?, followUpOn? }` (note ≤ 500 chars). AO.5 — `assigneeUserId` (a CURRENT member's users.id, else `422 assignee_not_member`; `null` unassigns) and `followUpOn` (a real UTC day `YYYY-MM-DD`, 2000–2100, else `400 invalid_follow_up_on`; `null` clears) are optional: OMITTED keeps the stored value. Each changed field (status, note, owner, follow-up) appends one line to the mark's history; an unchanged re-PUT appends none. Signed handoff: `addToRoster: true` (only with `status: signed`) also adds the creator to the roster in the same transaction — see that field. `creatorUid` is the TikTok user id a /v1/recruit row carries. The agency's own call — we never auto-mark. Agency plan or above (403 plan_required below it).

AO.5 — the history of this workspace's mark for a creator (status, note, owner and follow-up changes), newest first, at most 50. Never another workspace's. Agency plan or above (403 plan_required below it). Workspace-owned data, not credit-metered.

Recruit → Pipeline — this workspace's marks as a CRM pipeline: each mark with the creator it is about (handle, nickname, avatar, resolved region, followers), its status, note, owner, follow-up and `inRoster` (a roster host exists for the creator). Filters: `status` (comma list of checked|eligible|ineligible|contacted|signed), `assignee` (a member's users.id, or `unassigned`), `followUp` (overdue|today|upcoming, UTC days), `region` (uppercase code), `q` (prefix of the handle or nickname). Newest change first (uid ascending tie-break); `limit` 1..100 (default 50) and the opaque keyset `cursor` page. `counts` (per status, overdue, Eligible/Signed not in the roster) is narrowed by assignee / region / q but NOT by status or followUp, so it is a stable menu for the same filters. A `manager` session may call it but only ever sees marks assigned to them (the server ignores `assignee`); a manager never gets a mutation. Private to the workspace — never another's. Agency plan or above (403 plan_required below it). Workspace-owned data, not credit-metered; not part of the SDKs (customer-ui surface).

List workspace usage and per-key request charges for a billing period

AO.7b — PUBLIC (token only): turn the weekly owner report back on for the owner named by the token — only while they are STILL an owner of that workspace (403 otherwise). Idempotent. Token in the form body or the query string. HTML.

AO.7b — PUBLIC (token only): the page the weekly owner report's unsubscribe link opens. It shows an Unsubscribe button and changes NOTHING (a mail scanner prefetching the link cannot unsubscribe the owner); if the owner is already unsubscribed it offers Resubscribe instead. HTML. No email address or workspace is printed.

AO.7b — PUBLIC (token only): opt the owner named by the signed `weekly-report-unsub` token out of the weekly owner report, idempotently, whatever their current role. The token comes from the form body (`token=`) or the query string (the RFC 8058 one-click request: `application/x-www-form-urlencoded` body `List-Unsubscribe=One-Click`, token in the URL). The response page carries a Resubscribe button. HTML.