TokPortal

List Advanced Niche Warming sessions for an account. Lists Advanced Niche Warming sessions (newest first) for a saved account you own, including per-term tasks, per-term reports, proof links, and the aggregated session report when completed. Tasks unlock over 3 calendar days in the manager's timezone and, once created, do not expire.

List delivered accounts. Lists delivered saved accounts (real accounts that exist on the platform). Note the product has two ids: the account *listing* id carried by a bundle is stable across remakes, while the `saved_account_id` returned here is replaced every time an account is remade.

List comments for an account post. Returns cached comment text for one tracked post of an account. Full analytics tier only; this read never calls the platform live.

List raw account analytics snapshots. Returns owner-scoped stored raw analytics payloads for a saved account. Full analytics tier only.

List raw post analytics snapshots. Returns owner-scoped stored raw analytics payloads for a tracked post. Full analytics tier only.

List posts flagged by the platform. Owner-scoped list of posted videos carrying a platform signal, newest first: TikTok `not_recommended` (Not For Feed / Not Recommended — the post stays online but is excluded from For You and typically sits at 0 views), `ai_label` (`creator` = declared at posting, `platform` = applied by TikTok moderation) and `sound_status` (`non_commercial` = cannot be promoted, `removed` = pulled for copyright, `muted` = Instagram). Each row carries `platform_signals` (the same object returned on every video by GET /bundles/{id}/videos) and, from the Creator tier, `signal_insights` (followers gained, new vs returning viewers, impression sources, retention curve). Signals are observed by a public check about 48 hours after posting and again after 7 days; `null` means not checked yet, never 'no'. Available on every analytics tier.

List bundle video slots. Lists every video slot of a bundle with its position, configuration, schedule and review status. Positions are 1-based and run up to the bundle's `videos_quantity`. Every video carries `platform_signals`, what the platform did with the live post once it exists: `not_recommended` (TikTok Not For Feed / Not Recommended — online but no distribution), `ai_label` (`creator` | `platform`), `sound` (`ok` | `non_commercial` | `removed` | `muted`) with `sound_reason`, and `checked_at`. All fields are null until the post has been checked (~48 h after posting, again at 7 days); `null` means unknown, never 'no'. The same events arrive as `video.not_recommended`, `video.ai_labeled` and `video.sound_restricted` webhooks.

List bundles. Lists your bundles with their lifecycle status and the computed `next_action` (`configure_account`, `configure_videos`, `publish_bundle`, or null). `next_action` is the recommended way to find what a bundle still needs.

List comment task verification events. Lists verifier attempts for one owned task. This read remains available while TokPortal Coverage pauses task execution.

List comment tasks. Lists owned comment tasks. execution_blocked and execution_block_reason identify tasks paused by inactive TokPortal Coverage; reads remain available while execution is paused.

List available countries. Lists the valid `country` values for bundle creation. Most are ISO-3166-1 alpha-2 (FR, DE, BR), but TokPortal's own codes are the authority and two of them are not alpha-2: the United States is `USA` and the United Kingdom is `UK`. Their ISO aliases `US` and `GB` are accepted and resolved to those two, so send a code from this list verbatim and never assume alpha-2. Call before createBundle or createBundlesBulk: `country` is validated against this list, and a full country name such as "United States" is rejected. `videos_only_countries` applies only to video orders on an existing account and is never valid for /bundles/bulk.

List credit transactions. Paginated ledger of every credit debit and refund, newest first. Use it to reconcile what a bundle or batch actually cost, since server-side pricing (workspace cohort, contract allowance) can differ from the list price.

List available platforms. Lists the orderable platforms and, per video type, the exact required and optional fields. Call before configuring any slot: TikTok carousels require `tiktok_sound_url`, Instagram posts and reels require `instagram_content_type`, and a story takes exactly one of `video_url` or `story_image_url` and no description. Only TikTok and Instagram can be ordered; YouTube fields exist on the video schema but YouTube bundles are rejected with YOUTUBE_DELAYED.

List webhook deliveries. Lists delivery attempts for one endpoint with the response status and body. Deliveries are at-least-once and retries reuse the same `TokPortal-Event-Id` — deduplicate on that id, not on the delivery id.

List webhook endpoints. Lists your webhook endpoints with their subscribed events and enabled state. Signing secrets are never returned here — only once, at creation.

List webhook event catalog. Returns the supported webhook event types with, for each one, its description, exact trigger condition, payload schema and an example payload, plus the delivery envelope and signature scheme. Read it before subscribing: several names are counter-intuitive — account.published fires when you publish the order, not when the account is delivered (that is account.in_review), and warming.session_started is not emitted for warming whose terms were set at bundle creation. This endpoint is public so teams can inspect webhook contracts before creating an API key.

Patch video metadata or schedule. Changes a configured slot's name, description, external reference or schedule without re-sending its media. Rescheduling obeys the maximum of 3 videos per day per bundle AND — enforced since 2026-08-26, where before only the per-day cap ran — the same minimum publish lead time as configuration: today+1 with a delivered or existing account, today+3 while the account is still being created, in UTC. Today and any past date are rejected with `INVALID_DATE` carrying `min_days_ahead` and `earliest_allowed` (YYYY-MM-DD), the same shape the configure PUT returns. Send either target_publish_date (a 2-day window whose end is derived as that day + 1) or the target_publish_start_date/target_publish_end_date pair, never both — this is the ONLY endpoint where the window's end can be chosen, and it must fall strictly after the start. Cannot be used once the video is finalized. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.

Publish all configured videos on an active bundle. Hands every configured, unpublished slot on an active bundle to the account manager for posting. Publishing is irreversible once a manager has posted; call unscheduleBundleVideo beforehand to hold a slot back. Slots whose target date has already reached today or the past are moved forward to the earliest allowed day, respecting the 3-videos-per-day-per-bundle cap (an overflowing day spills to the next); slots still in the future are left alone, and the publish never fails because of it. When something moved, the response carries `dates_adjusted` (how many), `adjusted_videos` (one `{video_id, position, previous_date, new_date}` per moved slot) and `hint`. There is no `earliest_allowed_date` field on this response — it was documented but never returned, and `adjusted_videos` replaces it with the per-slot dates. Read them back instead of assuming the original schedule survived. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.

Publish a bundle. Submits a fully configured bundle to the account-manager marketplace, which is what actually starts the work. Requires status `pending_setup`, a complete account profile, and at least one configured video on an `account_and_videos` bundle — call getBundlePublishReadiness first, it returns every blocker without debiting. A due Coverage period renews here, so this call can debit credits even though the bundle's own cost was charged at creation. Irreversible once a manager accepts: unpublishBundle only works before that, and never refunds. Publish-time date guard: any slot whose target date has already reached today or the past is moved forward to the earliest allowed day (today+1 with a delivered or existing account, today+3 while the account is still being created, in UTC), respecting the 3-videos-per-day-per-bundle cap — an overflowing day spills to the next one. Slots still in the future are NOT moved. This never fails the publish. When something moved, the response carries `adjusted_videos` — one entry per moved slot, `{video_id, position, previous_date, new_date}` — and `adjusted_videos_note`. Read them back instead of assuming the schedule you sent survived. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.

Publish one video slot. Hands one configured slot to the account manager for posting on its target date. Irreversible once the manager has posted. If that target date has already reached today or the past it is moved forward to the earliest allowed day rather than published as instantly-due work, and the response then carries `date_adjusted: true`, `original_date`, `new_date` (both YYYY-MM-DD) and `hint`. Those four fields were documented long before they were real: until 2026-08-26 the RPC never returned them, and the slot published on its stale date. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.

Reactivate TokPortal Coverage. Reactivates TokPortal Coverage from an explicit GET snapshot, and debits the projected unpaid 30-day periods — read the quote from getAccountManagedSubscription and confirm the amount with the user first. Reactivation is free while the current billing period is already paid or included; Coverage benefits and tasks remain paused until reactivation. At and after current_period_end, the endpoint accepts the effective lapsed state even if recorded_status has not yet been updated by the renewal worker, and charges exactly the projected unpaid periods without adding an extra period. The expected credits, period end, and lock version are checked atomically before any debit or task resume. Scheduled videos receive new future dates while preserving their cadence.

Refresh account analytics. Legacy account-analytics refresh path, kept for older integrations; new code should call refreshAnalyticsAccount. Comment collection is gated on three conditions: includeComments only runs when force is true, includePosts is not false, and the workspace holds the full analytics tier. The two you control are refusals, not silence — includeComments without force, or with includePosts false, fails with INVALID_FIELD for MCP callers and is reported for direct REST callers. The one you cannot control, the analytics tier, comes back on the response as applied.include_comments plus applied.include_comments_dropped_reason. The call can still return 200 with deduped: true and skippedReason: "recent_snapshot", which means nothing was refreshed. Check canRefreshAccountAnalytics first: a forced retry consumes the manual-refresh cooldown slot and the next one is rejected with 429. Refresh is blocked for revealed/detached, banned or inactive-Coverage accounts; permanently grandfathered accounts remain eligible.

Refresh analytics account. Refreshes an owner-scoped account through Analytics v2. Comment collection is gated on three conditions: includeComments only runs when force is true, includePosts is not false, and the workspace holds the full analytics tier. The two you control are refusals, not silence — includeComments without force, or with includePosts false, fails with INVALID_FIELD for MCP callers and is reported for direct REST callers. The one you cannot control, the analytics tier, comes back on the response as applied.include_comments plus applied.include_comments_dropped_reason. The call can still return 200 with deduped: true and skippedReason: "recent_snapshot", which means nothing was refreshed. Check canRefreshAccountAnalytics first: a forced retry consumes the manual-refresh cooldown slot and the next one is rejected with 429. Refresh is blocked for revealed/detached, banned or inactive-Coverage accounts; permanently grandfathered accounts remain eligible.

Request account corrections. Moves an in-review account back to pending corrections with reviewer feedback.

Request video corrections. Sends a delivered video back to the account manager with written feedback instead of approving it. Only valid while the slot is `in_review`, i.e. inside the ~72-hour window before it auto-finalizes. The response does not echo `fields`, so keep your own record of what you flagged. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.

Reset one video slot. Clears a slot's configuration so it can be configured again. Only works from `pending` or `configured`: to clear a published or accepted slot call unscheduleBundleVideo first, then reset. The slot's credits are not refunded and any paid option already charged on it stays charged. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.

Retrieve latest account verification code. Retrieving a verification code is the same irreversible first-access event as revealing credentials. Its policy is determined by this saved account's created_at timestamp against the immutable managed_pricing_new_customer_cutover_at value, never by the workspace action-pricing cohort or August 14 grace deadline. A saved account created before the cutoff permanently keeps the prior API contract: 0 credits, no new versioned acknowledgment body required, no TokPortal detachment, existing task access remains available, and support plus ban coverage end after access. A saved account created at or after the cutoff follows the managed policy: normally 150 credits, or the stored $10 legacy / $15 new per-30-day rate when Account Owning is already admin-approved. Managed access permanently detaches the account, makes it read-only, and ends TokPortal Coverage, task access, analytics updates, support, ban protection, replacement, refunds, compensation and credit restoration. For a new-policy account, missing explicit acceptance fails with 428 and returns the exact account-specific terms, price and policy version. A changed quote returns 409 before any debit or reveal. Reaching the Account Owning eligibility threshold only submits an admin review request; it never activates the agreement automatically. While approval is pending, reveal remains available for 150 credits on a post-cutoff account. Do not send Idempotency-Key: this response contains a verification secret and is never stored in the replay ledger. A request that includes the header is rejected before any ledger claim, reveal, debit, or inbox access with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400). After an uncertain transport result, fetch the safe account state before deciding whether to call this endpoint again without the header.

Retry a webhook delivery. Resends the stored webhook payload to the endpoint's current URL with a fresh TokPortal-Signature header. The event ID is preserved so receivers can keep idempotent processing.

Reveal delivered account credentials. The first credential or verification-code access is priced from this saved account's created_at timestamp against the immutable managed_pricing_new_customer_cutover_at value, never from the workspace action-pricing cohort or August 14 grace deadline. A saved account created before the cutoff permanently keeps the prior API contract: the reveal costs 0 credits, requires no new versioned acknowledgment body, and is irreversible; support and ban coverage end, but the account is not detached and existing TokPortal task access remains available. A saved account created at or after the cutoff follows the managed policy and requires the explicit versioned acknowledgment handshake: normally 150 credits, or the stored $10 legacy / $15 new per-30-day rate when Account Owning is already admin-approved. Crossing the Account Owning eligibility threshold only submits an admin review request and never activates it automatically. While approval is pending, reveal remains available for 150 credits on a post-cutoff account. Under the managed policy the charge is final and non-refundable, and reveal permanently detaches the account, makes it read-only, and ends TokPortal Coverage, all task access, analytics updates, support, ban protection, replacement, refunds, compensation and credit restoration. TokPortal is not responsible for later access, performance, reach, security, restrictions or bans. The debit or Account Owning activation, reveal marker and Coverage shutdown commit atomically. Previously revealed accounts are not charged a second time. Do not send Idempotency-Key: this response contains credentials and is never stored in the replay ledger. A request that includes the header is rejected before any ledger claim, reveal, debit, or secret access with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400). After an uncertain transport result, fetch the safe account state before deciding whether to call this endpoint again without the hea…

Order Advanced Niche Warming (rewarm) on a delivered account. Starts an Advanced Niche Warming session on a saved account that is already delivered: for each provided term the manager screen-records a session that opens on the account profile (handle visible), searches the term on the account's platform, watches videos from the results, engages with them (likes/saves) and leaves a comment. Every recording is verified before completion. The standard rate is 5 credits per term, charged per target and never per day (3-30 terms, multiples of 3), with a 15-credit minimum; GET /credit-costs returns the effective rate. Once the session has tasks it is NEVER refunded, so confirm the total with the user before calling. Call listAccountWarmingSessions first: only one session can be active per account and a second one is rejected with 409 REWARM_ALREADY_ACTIVE. Requires active TokPortal Coverage, a routable active account manager backed by a non-cancelled support order, TikTok or Instagram, and no already-active warming session. A completed bundle remains eligible. Terms are split evenly over 3 calendar days in the manager's timezone; earlier-day tasks remain available until completed and sessions with tasks do not expire.

Send a test webhook. Sends a signed webhook.test event to the endpoint and records the delivery result.

Unpublish a bundle. Returns a published bundle to `pending_setup` so its account configuration can be edited again. Only works while the bundle is published and no account manager has accepted it (409 otherwise). Credits are NOT refunded and this is not a cancellation: there is no API path to cancel a bundle or recover its credits.

Unschedule one video slot. Pulls a published slot back out of the account-manager queue and returns it to `configured`, so it can be rescheduled or reset. Does not refund the slot. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.

Update account commenting profile. Sets the internal commenting-autopilot metadata (niche, persona, goal, language, tracked handles) that TokPortal uses to draft comments for this account. It NEVER changes the account's public profile — use createAccountEditRequest to change a delivered account's username, visible name, biography, picture or link. The account must belong to the API key owner and must have active TokPortal Coverage, unless it is permanently grandfathered. Revealed/detached, banned, paused, lapsed and unrecoverable accounts are read-only.

Update bundle settings. Updates mutable bundle metadata: title, external_ref, and auto_finalize_videos. auto_finalize_videos true (the default) approves every delivered video automatically — it counts as final on arrival; set it to false to hold each delivered video for your review, approving with finalizeBundleVideo or pushing back with requestBundleVideoCorrections yourself. Note that anything left in review is auto-finalized about 72 hours after entering it either way.

Update safe workspace settings. Updates client-owned workspace profile fields used by Operator context. Does not expose auth, role, credit, staff, or manager settings.

Update a webhook endpoint. Changes an endpoint's URL, subscribed events, description or enabled state. The signing secret is unchanged and is never re-returned. Call listWebhookEvents for the meaning, trigger condition and payload of each event type before changing the subscription list.

Create an image upload URL. Returns a short-lived signed upload URL and upload token for an image. Use the returned `storage_path` — NOT `public_url` — for `carousel_images` and `profile_picture_url`; videos are the opposite, uploadVideo returns a `public_url` that goes straight into `video_url`. The stored object's extension comes from the declared `content_type` (image/png stores a .png), and only falls back to the extension in `filename` when the content type is unknown, so send the content type that matches the bytes you are about to PUT. `storage_path` on the response is the key the object is actually stored under — read it rather than rebuilding it from `filename`. 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.

Upload an image file directly. Uploads multipart/form-data directly through TokPortal and returns storage details. Use the returned `storage_path` — NOT `public_url` — for `carousel_images` and `profile_picture_url`. HEIF/HEIC may be converted to JPEG. `purpose` is validated like it is on the JSON upload endpoints: an explicit value other than `carousel` or `profile_picture` is refused with INVALID_FIELD for MCP callers and reported in `meta.ignored_fields` for direct REST callers — it is no longer quietly rounded down to `carousel`. Omitting `purpose` still means `carousel`, which is the documented default. Confirm the destination with the returned `bucket`.

Import an image from URL. Fetches a public direct image URL and stores it permanently in TokPortal storage. Use the returned `storage_path` — NOT `public_url` — for `carousel_images` and `profile_picture_url`.

Create a video upload URL. Returns a short-lived presigned upload capability for a video file. The `public_url` it returns is what goes into `video_url` on configureBundleVideo — images are the opposite and require the upload response's `storage_path`. 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.

Upload a video file directly. Uploads multipart/form-data directly through TokPortal and returns the public video URL, which goes straight into `video_url` on configureBundleVideo.