TokPortal

Add edit slots to a bundle.

Add video slots to a bundle.

Approve a manually confirmed comment task. Approves and finalizes an owned manually_confirmed task. Execution is blocked while TokPortal Coverage is inactive; inspect MANAGED_ACCOUNT_TASK_BLOCKED and reactivate a recoverable account first.

Configure video slots in bulk. Configures several slots after one account-level Coverage preflight. When this bundle resolves to a delivered saved account, the account must have active TokPortal Coverage or be permanently grandfathered. A due active period can renew automatically at the account's stored rate immediately before execution. If Coverage cannot renew, no task or media mutation starts.

Check analytics refresh availability.

Pause TokPortal Coverage. Immediately blocks new and ongoing TokPortal work for the account. Payments are not refunded. If a paid or included current period remains, reactivation is free until its original end. Otherwise it costs exactly the unpaid 30-day periods at the rate returned by the Coverage status endpoint.

Configure bundle account profile. Sets the account identity (username, visible name, biography, profile picture). For backward compatibility it can also accept the exact purchased advanced_warming_terms list, but PUT /bundles/{id}/warming-terms is the recommended one-shot deferred-target endpoint because it remains available at any account status. When this bundle resolves to a delivered saved account, the account must have active TokPortal Coverage or be permanently grandfathered. A due active period can renew automatically at the account's stored rate immediately before execution. If Coverage cannot renew, no task or media mutation starts. A new account that has not produced a saved account yet remains configurable before delivery.

Configure a video slot. Configure a slot as a video, carousel, or story. A story (TikTok/Instagram only) is a single video OR a single image (provide exactly one of video_url or story_image_url), has no description, and is verified by an account-manager screenshot. The optional story_repost_url makes the story repost an existing post from the SAME platform and costs +1 credit. When this bundle resolves to a delivered saved account, the account must have active TokPortal Coverage or be permanently grandfathered. A due active period can renew automatically at the account's stored rate immediately before execution. If Coverage cannot renew, no task or media mutation starts.

Configure the niche targets of a count-only Advanced Niche Warming purchase. Sets the niche targets for a bundle created with advanced_warming_terms_count (deferred configuration). Must provide EXACTLY the purchased number of targets. One-shot: once configured the targets cannot be changed. Unlike PUT /bundles/{id}/account, this stays available at any account status after the manager accepted the mission or submitted the account, in which case the warming session starts immediately. When this bundle resolves to a delivered saved account, the account must have active TokPortal Coverage or be permanently grandfathered. A due active period can renew automatically at the account's stored rate immediately before execution. If Coverage cannot renew, no task or media mutation starts. A new account that has not produced a saved account yet remains configurable before delivery.

Request profile edits for a delivered account. Requests profile changes and debits 8 credits. Active TokPortal Coverage and a routable active account manager are required. TokPortal uses the account's current active manager, then its still-active manager relationship, then eligible non-cancelled order history. Completed bundles remain eligible without a delivery-age limit; cancelled orders are never restored. Assignment, debit, and task creation are atomic, so an unavailable manager never costs credits. The task appears directly in that manager's calendar.

Create analytics web report. Creates a shareable Analytics v2 web report and returns its bearer-like access token and URL. Do not send Idempotency-Key. The successful response contains a secret and is never stored in the replay ledger. A request with the header is rejected with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400) before any ledger claim or operation execution.

Create a bundle. Creates and pays an account-only, account-and-videos, or videos-only bundle in one atomic creation checkout. Credits are debited immediately on a successful POST, not when the bundle is published. Credit cost is calculated server-side from the workspace cohort and any contract_bundle_allowance returned by getCreditCosts. A qualifying allowance slot is consumed in the same transaction as the credit debit; failed requests consume nothing. The exact new-customer and saved-account cutoff is the immutable production PRE-migration instant returned by getCreditCosts. A real TikTok or Instagram saved account created on or after that cutoff receives its first 30 days of TokPortal Coverage included unless the creation response marks it contractually exempt. For Advanced Niche Warming, either pass advanced_warming_terms now, or buy a target count with advanced_warming_terms_count at the effective workspace rate and configure the targets later via PUT /bundles/{id}/warming-terms. Count-only purchases that are never configured are auto-cancelled and fully refunded after 14 days. external_ref is a client correlation and duplicate-detection aid, not a retry mechanism; only Idempotency-Key provides exact request replay.

Create bundles in bulk. Creates and pays several bundles in one atomic creation checkout. Credits are debited immediately on a successful POST, not at publication. The complete batch is checked against rolling workspace capacity and any contract_bundle_allowance returned by getCreditCosts. Qualifying allowance slots are consumed in deterministic bundle-ID order in the same transaction as all debits; if any bundle fails, the entire batch rolls back and consumes nothing. A batch crossing the final allowance slot receives the contract price only for the remaining qualifying bundles. For Advanced Niche Warming, either pass advanced_warming_terms, using the same terms for every account, or buy a per-account target count with advanced_warming_terms_count and configure each bundle's targets later via PUT /bundles/{id}/warming-terms. external_ref is one optional batch-level reference copied to the resulting bundles, not a unique per-bundle key or a retry mechanism; use returned bundle IDs for identity and Idempotency-Key for exact replay.

Create comment tasks. Creates one comment task or a partial-success batch of up to 200. Each accepted task costs 1 credit. The saved account must be client-owned, manager-assigned, and allowed to execute tasks by TokPortal Coverage, unless it is permanently grandfathered. TokPortal locks and revalidates the account and Coverage before the accepted-task debit and all accepted inserts commit in one transaction. Rejected rows are never charged. Read credits_charged instead of calculating it from the request. Send an Idempotency-Key and reuse the same key, method, path, and body after an uncertain transport result so the completed response is replayed without a second charge.

Request an ad code (TikTok Spark Code / Instagram Partner Code) for a finalized video. Requests an ad code (TikTok Spark Code or Instagram Partner Code) for one finalized video and debits 7 credits. The video must be finalized on TikTok or Instagram with a live post link. Active TokPortal Coverage and a routable active account manager are required. TokPortal uses the account's current active manager, then its still-active manager relationship, then eligible non-cancelled order history. Completed bundles remain eligible without a delivery-age limit; cancelled orders are never restored. Assignment, debit, and task creation are atomic. Only one open request per video is allowed. Poll the GET endpoint to retrieve the code once the manager submits it.

Create a webhook endpoint. Creates a webhook endpoint and returns its signing secret once. Store the secret to verify TokPortal webhook signatures. Do not send Idempotency-Key. The successful response contains a secret and is never stored in the replay ledger. A request with the header is rejected with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400) before any ledger claim or operation execution.

Cancel a pending comment task. Cancels an owned task only while its status is pending. The terminal transition and refund of the task's exact stored credit cost commit atomically and are idempotent. Current tasks refund 1 credit; credits_refunded remains authoritative for historical tasks. Cancellation remains available when Coverage is paused because it stops pending work rather than executing it. Reuse the same Idempotency-Key after an uncertain transport result.

Delete a webhook endpoint.

Dispute a manually confirmed comment task. Returns an owned manually_confirmed task to pending corrections. Execution is blocked while TokPortal Coverage is inactive; inspect MANAGED_ACCOUNT_TASK_BLOCKED and reactivate a recoverable account first.

Export analytics report HTML. Creates a standalone downloadable HTML analytics report.

Export analytics videos CSV.

Finalize account review. Approves an in-review account and marks it finalized.

Finalize video review. When this bundle resolves to a delivered saved account, the account must have active TokPortal Coverage or be permanently grandfathered. A due active period can renew automatically at the account's stored rate immediately before execution. If Coverage cannot renew, no task or media mutation starts.

Fix a broken video download. Replaces a manager-flagged broken video or carousel download URL and clears the download issue flag. When this bundle resolves to a delivered saved account, the account must have active TokPortal Coverage or be permanently grandfathered. A due active period can renew automatically at the account's stored rate immediately before execution. If Coverage cannot renew, no task or media mutation starts.

Generate Advanced Niche Warming search terms. Generates platform-appropriate Advanced Niche Warming search terms (niche targets) from a free-text niche description (max 1000 characters). This is free and no credits are charged. Pass the result to advanced_warming_terms (bundle creation or PUT /bundles/{id}/warming-terms deferred configuration) or search_terms (rewarm).

Get a delivered account.

Get account analytics compatibility view.

Get active account edit request.

Get TokPortal Coverage status. Returns the effective TokPortal Coverage status, current 30-day period, account-specific rate, unpaid periods, task access, and an exact timestamped reactivation quote for one eligible saved account. At current_period_end, status and task_access change immediately even if recorded_status remains included or active for a few minutes until the renewal worker persists the transition; period_expired makes that boundary explicit. A zero-credit quote is valid. Use its current_period_end and lock_version snapshot for reactivation. An eligible TikTok or Instagram account created before the global Coverage cutoff is grandfathered and has no subscription record. A missing record can also mean the account is not Coverage-eligible or has not reached delivery, so clients must not infer grandfathering from a generic 404. Coverage is independent from bundle completion or closure.

Get account analytics drilldown.

Get analytics data contract. Returns the Analytics v2 contract, current access payload, metric semantics, freshness targets, and redaction rules.

Get analytics dashboard.

Get analytics time series.

Get a bundle.

Get bundle account configuration.

Check bundle publish readiness. Returns every current publish blocker without mutating the bundle, settling Coverage, or debiting credits. MANAGED_ACCOUNT_TASK_BLOCKED includes details.account_id and details.reason. Fetch GET /accounts/{account_id}/managed-subscription for the authoritative state and exact reactivation quote. A due included or active period can temporarily appear blocked until renewal is settled by cron or an approved mutation.

Get video slot configuration.

Get comment pulse analytics.

Get a comment task. Returns one owned comment task, including whether inactive TokPortal Coverage currently blocks manager execution and the stable block reason.

Get credit balance.

Get credit pricing.

Get authenticated user.

Get / poll the ad code for a video. Returns the latest ad code request for the video. The `code` field is null until the manager submits it (status `in_review`) or it is delivered (status `finalized`).

Get single video analytics.

Get an Advanced Niche Warming session. Returns one Advanced Niche Warming session you own: status, per-term tasks (with 3-calendar-day dispatch in the manager's timezone, verification status, client report and proof video link), and the aggregated report on completion. Created tasks remain open until completed; they do not expire.

Get a webhook endpoint.

Import video slots from CSV. Uploads a CSV file, downloads referenced media, and configures available video slots. Coverage is checked before TokPortal fetches or stores referenced media. When this bundle resolves to a delivered saved account, the account must have active TokPortal Coverage or be permanently grandfathered. A due active period can renew automatically at the account's stored rate immediately before execution. If Coverage cannot renew, no task or media mutation starts.

List ban reports and appeals. Pollable list of validated ban reports for the caller's delivered accounts, covering the whole lifecycle: appeal_pending (platform appeal filed, account unavailable but NOT yet banned), appeal_accepted (account survived), appeal_refused / no_appeal_banned (confirmed ban), and the staff commercial resolution (refund / remake / no_remake with a machine-readable reason_code such as tos_ban). This is the REST counterpart of the account.banned, account.ban_appeal.submitted, account.ban_appeal.resolved and account.ban_resolution.decided webhook events. Only staff/CM-validated bans appear here — detections from TokPortal's internal health scan are never listed. Poll with the since parameter (updated_at watermark) to pick up new reports and status changes.

List bundles for a delivered account.

List post analytics for an account.