# TokPortal [Health: Active]

**Category:** 🌐 Social Media  
**Repository:** https://github.com/tokportal/tokportal-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 684  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tokportal

## Description
Managed TikTok/Instagram/YouTube accounts + video posting at scale, operated by human managers.

## Tools
Capabilities this server exposes over MCP:

- **tokportal_send_account_inbox_message** — Reply to an Instagram direct message. Send plain text in an existing owned Instagram conversation, on an eligible Creator or Business connection. No Facebook Page. Costs 0 credits for this release. Supply the conversation reference from GET inbox kind=conversations. Requires write access, current Coverage, live messaging permissions and an incoming message in the past 24 hours; no cold outreach. The server verifies the latest 100 messages and refuses without positive window proof. Keep request_key unchanged for an exact retry. Shared account leases and provider quotas apply. pending/unknown is not success and must not be resent; inspect GET operation and thread. succeeded means the provider returned a message ID, not recipient delivery or reading. Dry-run validates without sending.
- **tokportal_create_account_private_reply** — Send a comment-to-DM private reply. Send one plain-text private Instagram reply to a new received comment on an owned post, within seven days. Creator and Business are supported with comment access. Costs 0 credits. Pass the post reference and comment private_reply_action_reference. No TikTok DMs. Hidden, own, stale or unverifiable comments are refused. This consumes the single private reply for the comment; another key or changed wording cannot resend it. A platform refusal may consume it too. The recipient must send an incoming message before follow-up DMs; a private reply does not open a 24-hour window. Use a stable request_key, honor Retry-After and never retry unknown delivery blindly. Dry-run validates without sending.
- **tokportal_get_account_message_operation** — Read a DM or private-reply result. Read the durable, owner-scoped operation state. A stale pending operation becomes unknown after two minutes, with no resend. Native message content and provider credentials are not returned.
- **tokportal_get_account_comment_dm** — Read comment-to-DM rules and history. Read one account rule and the latest 20 job results. Instagram only. Disabled by default. GET settings.version before editing. The optional post_reference is freshly signed for the saved post scope. next_cursor reads older history. No comment or DM bodies are retained in job history; the owner-configured message template is returned in settings.
- **tokportal_update_account_comment_dm** — Configure keyword comment-to-DM. Explicitly enable, edit or pause one Instagram keyword rule, account-wide (post_reference=null) or for a signed owned post reference. Costs 0 credits. Whole-word/contains and exceptions use the same Unicode matching as moderation. Rules apply only to original comments created after saving; no historical scan, own-account triggers or reply loops. Defaults disabled. Requires version for optimistic concurrency. Rule changes skip queued old-version jobs. Current owner, connection pin, Coverage, comment age/text and rules are rechecked before sending. Durable resource dedupe and a shared per-account lease prevent duplicate sends. Provider webhooks trigger jobs, normally immediately; a five-minute worker recovers queued work. At most three safe verification or explicit-quota retries. An ambiguous write is never automatically retried. A private reply never authorizes follow-up DMs until the person replies. Read history and subscribe to inbox.comment.automation.updated. Dry-run validates without saving or sending.
- **tokportal_get_current_user** — Get authenticated user. Returns the authenticated workspace: profile, role, analytics access tier and live credit balance. Call once at the start of a session to learn what this key can do.
- **tokportal_update_current_user_settings** — Update safe workspace settings. Updates client-owned workspace profile fields used by Operator context. Does not expose auth, role, credit, staff, or manager settings.
- **tokportal_get_account_managed_subscription** — 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.
- **tokportal_reactivate_account_managed_subscription** — 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. After cancellation, access continues through the current paid period if no overdue Coverage is unpaid. After it expires, account features stay unavailable until Coverage is restored. 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.
- **tokportal_cancel_account_managed_subscription** — Pause TokPortal Coverage. Stops renewal without refunding payments. Account actions and analytics remain available through the paid/included period if no overdue Coverage is unpaid. Afterwards they are blocked until Coverage is restored; after 30 days of unavailability the API connection is removed. Resuming renewal during the current paid period is free. Otherwise reactivation costs exactly the unpaid 30-day periods shown by the Coverage status endpoint.
- **tokportal_list_countries** — 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.
- **tokportal_list_platforms** — 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.
- **tokportal_get_credit_costs** — Get credit pricing. Authoritative live credit prices and workspace cohort. Call it immediately before any purchase and never hard-code or recall a price. Not every key is orderable: `youtube_account_creation` is listed for reference only (YouTube bundles are rejected with YOUTUBE_DELAYED), and `niche_warming` and `deep_warming` are legacy prices published for backward compatibility only — they are not products a caller may choose, and `advanced_warming` (Advanced Niche Warming, priced per niche target) is the only warming TokPortal sells. `managed_account_subscription` (TokPortal Coverage) recurs every 30 days per account after the included first period, so a multi-account quote must include it as a monthly cost. There is no dry-run endpoint: assemble the total from this table (account setup + video slots + Advanced Niche Warming targets + edit slots + paid video options), apply the returned cohort and contract_bundle_allowance, and confirm it with the user before creating anything.
- **tokportal_get_credit_balance** — Get credit balance. Returns the currently spendable credit balance and upcoming expirations. Check it before any purchase: a 402 on a mutation means this was short.
- **tokportal_list_credit_transactions** — 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.
- **tokportal_list_bundles** — 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. Video counters cover all slots and are independent of page/per_page: `videos_quantity` is the recorded slot quantity, `videos_total` counts existing slots, and `videos_configured_count` includes configured, published, accepted, in_review, pending_corrections and finalized slots. Unused slots have status `pending`; with the current status set their count is `videos_total - videos_configured_count`. Configured or finalized slots are not unused capacity. A failed video read returns an error, never zero counters.
- **tokportal_create_bundle** — 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, and THERE IS NO CANCELLATION OR REFUND PATH — read getCreditCosts and getCreditBalance and confirm the total with the user before calling. One bundle produces exactly one account; order several accounts with createBundlesBulk. TikTok and Instagram only: a YouTube bundle is rejected with YOUTUBE_DELAYED even though getCreditCosts lists a YouTube price. Advanced Niche Warming requires wants_advanced_warming: true ALONGSIDE advanced_warming_terms or advanced_warming_terms_count; targets sent without the flag are refused with ADVANCED_WARMING_FLAG_REQUIRED, never charged and dropped. Send the term list or the count, not two quantities that disagree (ADVANCED_WARMING_COUNT_MISMATCH), and send distinct terms — anything removed by cleanup fails the call with ADVANCED_WARMING_TERMS_REJECTED rather than silently reducing what you receive and pay for. 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, and Coverage then recurs every 30 days per account at the managed_account_subscription price. For Advanced Niche Warming, 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 — one or the other, always with wants_advanced_warming: true. Set the targets BEFORE publishing: publishBundle refuses a bundle whose warming has no targets (ADVANCED_WARMING_NOT_CONFIGURED), and a purchase left unconfigured is not refunded. The bundle is created in pending_setup and still needs configureBundleAccount and publishBundle. Delivered videos are approved automatically unless you send auto_finalize_videos: false — the response echoes the settlement mode as review_mode ('auto' or 'manual'), plus a one-off review_mode_notice when you left the choice to the default. external_ref is a client correlation and duplicate-detection aid, not a retry mechanism; only Idempotency-Key provides exact request replay.
- **tokportal_create_bundles_bulk** — 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, and THERE IS NO CANCELLATION OR REFUND PATH — read getCreditCosts and getCreditBalance and confirm the total with the user before calling, because the loss is multiplied by accounts_count and platforms. Each bundle produces exactly one account. Warming targets and credits are charged per account, not per batch. Advanced Niche Warming requires wants_advanced_warming: true ALONGSIDE advanced_warming_terms or advanced_warming_terms_count; targets sent without the flag are refused with ADVANCED_WARMING_FLAG_REQUIRED for the whole batch, never charged and dropped. Send the term list or the count, not two quantities that disagree (ADVANCED_WARMING_COUNT_MISMATCH), and send distinct terms — anything removed by cleanup fails the call with ADVANCED_WARMING_TERMS_REJECTED. 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, so never split a 429 capacity-cooldown batch into parallel calls. A batch crossing the final allowance slot receives the contract price only for the remaining qualifying bundles. For Advanced Niche Warming, 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 — one or the other, always with wants_advanced_warming: true. Every bundle is returned in pending_setup with no username: each one still needs configureBundleAccount and publishBundle before any work starts. Delivered videos are approved automatically for every bundle in the batch unless you send auto_finalize_videos: false — the response echoes review_mode ('auto' or 'manual'), plus a one-off review_mode_notice when you left the choice to the default. 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.
- **tokportal_get_bundle** — Get a bundle. Full state of one bundle: status, account configuration, video slot counts, warming purchase, cancellation and remake history, and `next_action`. A remade bundle keeps the same id while its `saved_account_id` changes. Includes all video slots, including bundles with more than 1,000 slots. For unused capacity, count `videos` with status `pending`; `videos_configured_count` includes slots that have since been published or finalized. Counters have the same meaning as listBundles.
- **tokportal_update_bundle** — 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.
- **tokportal_publish_bundle** — 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.
- **tokportal_get_bundle_publish_readiness** — 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.
- **tokportal_unpublish_bundle** — 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.
- **tokportal_add_video_slots** — Add video slots to a bundle. Buys additional video slots on an existing bundle and debits credits immediately (see `video_upload` in getCreditCosts). The slots are non-refundable and there is no cancellation path for this purchase; confirm the exact cost with the user before calling. Allowed bundle statuses: `pending_setup`, `published`, `published_priority`, `accepted`. An `account_only` or `completed` bundle cannot receive more slots; create a `videos_only` bundle for the saved account instead, subject to account eligibility. Configure the new positions with configureBundleVideo, then publish them.
- **tokportal_add_edit_slots** — Add VIDEO-editing slots to a bundle. Buys video-editing slots — professional editing of a video by the account manager — and debits credits immediately (see `video_edit` in getCreditCosts). Non-refundable, with no cancellation path; confirm the exact cost with the user before calling. `edits_quantity` cannot exceed the bundle's `videos_quantity`, one video consumes at most one slot, and a slot is only consumed when that video carries `editing_instructions`. This has nothing to do with editing an account profile — use createAccountEditRequest for that.
- **tokportal_get_bundle_account** — Get bundle account configuration. Returns the current account-profile configuration of a bundle (username, visible name, biography, picture) and its listing status. Read it before configureBundleAccount to see what is already set and whether the profile is still editable.
- **tokportal_configure_bundle_account** — Configure bundle account profile. Sets the profile of an account that has NOT been delivered yet: username, visible name, biography, profile picture, and link-in-bio on Instagram bundles. Only valid while the bundle is `pending_setup` or `configured` — unpublish first to edit after publishing, and use createAccountEditRequest for an account that is already delivered. This is a full replacement: any field you omit is written back as null, so re-send the whole profile when you change one part of it. `link_in_bio` is stored on Instagram bundles only. On any other platform it is accepted but not stored, and the response says so explicitly through `_warnings` while echoing `link_in_bio: null` — read both back. For backward compatibility this endpoint also accepts 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. 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. A new account that has not produced a saved account yet remains configurable before delivery.
- **tokportal_request_bundle_account_corrections** — Request account corrections. Moves an in-review account back to pending corrections with reviewer feedback.
- **tokportal_finalize_bundle_account** — Finalize account review. Approves an in-review account and marks it finalized.
- **tokportal_list_bundle_videos** — List bundle video slots. Lists every video slot of a bundle with its position, configuration, schedule and review status, including bundles with more than 1,000 slots. Unused slots have status `pending`; configured, scheduled and finalized slots are already allocated. 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.
- **tokportal_get_bundle_video** — Get video slot configuration. Returns one video slot's configuration, schedule, review status and post link, plus `platform_signals` (TikTok not-recommended flag, AI label, sound status — null until the live post has been checked). Use it to check whether a slot is still inside its review window before finalizing it, or whether the platform is distributing the post at all.
- **tokportal_configure_bundle_video** — Configure a video slot. Configures one slot as a video, carousel, or story, and schedules it. 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. Platform-specific fields are only stored on their own platform: `tiktok_sound_url` on TikTok, every `instagram_*` field on Instagram, every `youtube_*` field on YouTube. A field belonging to another platform is accepted and not stored, but it is no longer discarded in silence: the response lists those names in `ignored_fields`, next to `platform`, with an `ignored_fields_note` explaining why. Check `ignored_fields` on every 200 — an empty or absent list is the only proof that everything you sent landed. Some options are paid and charged the first time they are set, never refunded: story_repost_url, instant_repost_as_story, and setting either volume field. Scheduling: `target_publish_date` is the FIRST day of a 2-day publishing window, never a fixed date — the end day is derived as that day + 1 and cannot be chosen, so `target_publish_end_date` is refused here with a hint pointing at PATCH. The window that was actually stored comes back as `target_publish_start_date` / `target_publish_end_date`. `auto_publish` is per-video HERE and top-level-only on the batch endpoint. 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.
- **tokportal_patch_bundle_video** — 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.
- **tokportal_batch_configure_bundle_videos** — Configure video slots in bulk. Configures many video slots in one call after a single account-level Coverage preflight. Partial success: this call returns HTTP 200 even when some or all rows are rejected. Read `configured`, `results` and `errors[]` and never infer success from the status code — rows breaking the 3-videos-per-day cap or the minimum lead time fail individually while the rest succeed, and the paid options they carry are only charged for the rows that succeeded. An `auto_publish` failure never fails the request; inspect `auto_publish.blockers`. TOP-LEVEL ONLY on this endpoint: one publish attempt per call, applying to every video in it. auto_publish inside videos[] is rejected with a hint telling you to move it out — it is per-video only on the single-slot PUT /bundles/{id}/videos/{position}. Each row's `target_publish_date` is the first day of a 2-day window whose end is derived (that day + 1); `target_publish_end_date` is refused on this endpoint. 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.
- **tokportal_publish_all_bundle_videos** — 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.
- **tokportal_import_bundle_videos_csv** — Import video slots from CSV. Uploads a CSV file, downloads the referenced media, and configures the available video slots. Partial success: this call returns HTTP 200 even when some or all rows are rejected. Read `imported`, `results` and `errors[]` and never infer success from the status code — rows breaking the 3-videos-per-day cap or the minimum lead time fail individually while the rest succeed. An `auto_publish` failure never fails the request; inspect `auto_publish.blockers`, and `auto_publish.adjusted_videos` when a stale date was moved forward at publish time. The date column is `target_publish_start_date` (note the name: the JSON endpoints call the same value `target_publish_date`) and it is the FIRST day of a 2-day window — the end is derived as that day + 1, so a `target_publish_end_date` column is refused with CSV_PARSE_ERROR rather than dropped. `auto_publish` is a form field on the multipart body and covers the whole import. Coverage is checked before TokPortal fetches or stores any referenced media. 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.
- **tokportal_publish_bundle_video** — 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.
- **tokportal_reset_bundle_video** — 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.
- **tokportal_unschedule_bundle_video** — 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.
- **tokportal_finalize_bundle_video** — Finalize video review. Approves a delivered video and releases the account manager's payout — the review window cannot be reopened afterwards. Only valid while the slot is `in_review`. Any slot left in review is auto-finalized about 72 hours after entering it, so act inside that window. 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.
- **tokportal_request_bundle_video_corrections** — 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.
- **tokportal_fix_bundle_video_download** — Fix a broken video download. Replaces a manager-flagged broken video or carousel download URL and clears the download-issue flag. 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.
- **tokportal_list_accounts** — 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.
- **tokportal_list_account_bans** — 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). While a report is appeal_pending, do NOT order a replacement account: a duplicate can trigger a ban-evasion strike on the platform, which is why TokPortal itself waits for the appeal. Key your reports on bundle_id — account_id can be null after a staff reset. A resolution of refund returns setup, warming and unused video slots, but not work already delivered and not the Coverage period, and the restored credits expire 60 days after restoration (see the credits.restored event in listWebhookEvents). 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.
- **tokportal_get_account** — Get a delivered account. Returns one delivered account: handle, platform, Coverage state, ban state and warming summary. A `saved_account_id` invalidated by a remake returns 404 — re-read the bundle to get the new one.
- **tokportal_get_account_connection** — Check the API connection of an account. Returns the current API connection state, checked_at, recovery action and separate feature eligibility. Ownership and current expected identity are checked. A fresh server check may be reused for up to 60 seconds and is invalidated by a newer disconnection event. An unavailable provider returns state checking, never a false disconnection. Messaging configuration eligible is not proof of an open reply window or successful send. This read does not create tasks or charge credits.
- **tokportal_get_account_inbox** — Read account messages or comments. Read-only inbox for one owned account with active API connection and eligible TokPortal Coverage. Posts/comments work for eligible Instagram and TikTok connections; conversations/messages require an eligible Instagram professional account (Creator or Business), granted messaging permissions and no current messaging restriction. First list posts or conversations, then pass the returned opaque reference for comments or messages. To read comment replies, keep the post reference and pass the comment's reference as reply_reference. References and pagination cursors expire after one hour and are bound to the account, connection and resource. Refresh the parent list on inbox_reference_expired_or_invalid. Messages are newest first; reading never marks them as read. Comments may be cached upstream for 10 minutes. Replayed Instagram DM history is limited to the latest 500 conversations and 500 messages per conversation. This endpoint does not send, reply, moderate, create automations or charge credits. The separate /comments routes are paid human commenting tasks. Subscribe to inbox.comment.received and inbox.message.received for metadata notifications, then fetch this scoped endpoint. Public replies use POST /accounts/{id}/inbox/replies with reply_action_reference; this GET remains read-only. Instagram DM writes and private replies use the separate messages/private-replies endpoints; messaging metadata reports the current reply window.
- **tokportal_get_account_comment_moderation** — Read comment moderation rules and history. Owner-scoped keyword hiding rules and the latest 20 processing results for Instagram or TikTok. Disabled by default. No private comment text is stored or returned. Use next_cursor to read older history. post_reference opens the owned comment thread using GET inbox kind=comments. Reading never hides or sends anything.
- **tokportal_update_account_comment_moderation** — Configure automatic keyword comment hiding. Set keyword moderation for one owned Instagram or TikTok account. No DMs or credit charge. GET first, then pass settings.version for optimistic concurrency; a stale version returns moderation_version_conflict. Enabling requires a verified connection, comment access and usable Coverage. Disabling is always allowed for the owner. New signed comment events after saving are matched case-insensitively using Unicode NFKC; exceptions take priority, own comments are skipped. Whole-word mode treats letters, numbers and underscore as word characters. Hiding runs asynchronously after publication, normally immediately, with a five-minute recovery worker; comments can be visible before hiding. It cannot guarantee pre-publication filtering or delivery of every upstream webhook. Prior comments are not scanned. Rule changes cancel waiting older jobs. Provider quotas and shared per-account leases apply; Safe read verification can wait 330 seconds for newly received comments to become available. Processing is capped at three attempts; an external write is retried only after an explicit 429 refusal. Unknown writes are never resent automatically. Turning rules off does not restore hidden comments; TikTok unhide is currently unreliable. Dry-run validates without saving or hiding.
- **tokportal_create_account_comment_action** — Moderate a received comment. Delete, hide, restore visibility, pin or unpin a comment on an owned post. Costs 0 credits. Only use actions returned on that comment by getAccountInbox, with their signed action.reference and the signed post reference. Capabilities are checked again before the write. Instagram supports delete/hide/unhide when allowed; TikTok supports delete/hide and top-level pin/unpin when allowed. TikTok deletion is generally limited to the connected account's own comments/replies. TikTok unhide and comment likes are not exposed in this release. Deletion is permanent and may also remove replies; ask the person using your integration for confirmation before deleting. Requires active Coverage, the current connection and write permission. Reuse the request_key for the same intent, including transport retries. No bulk action or automatic retry of ambiguous results. Honor Retry-After and fetch operation status. Dry-run validates without modifying the platform. A provider acknowledgement is required for succeeded; an HTTP 200 alone is insufficient.
- **tokportal_get_account_comment_action** — Read a comment moderation result. Read an owner-scoped durable action result. pending/unknown never authorizes an automatic resend. Deleted or absent comments alone do not prove this operation succeeded. No comment text is stored in the operation.
- **tokportal_create_account_comment_reply** — Reply to a received comment. Reply publicly to one received comment on an owned Instagram or TikTok post. Costs 0 credits and never renews Coverage. Requires active Coverage, verified connection and can_reply=true. Fetch posts, then comments; pass the post reference and the comment reply_action_reference. The body request_key UUID must remain identical on an exact retry. Account leases and provider quotas apply; honor Retry-After. A succeeded operation has a reply_id. pending/unknown means delivery is unconfirmed: fetch operation status and the comment thread, never blindly resend. Dry-run validates without sending. TikTok max 150 characters, Instagram max 2200.
- **tokportal_get_account_comment_reply** — Read a comment reply result. Owner-scoped durable delivery state: pending, succeeded, failed, rate_limited or unknown. No reply text or private credentials returned. Never automatically resend an unknown outcome.
- **tokportal_get_account_business_setup** — Read Instagram Business setup progress. Client task status and 5-credit price. Manager compensation and private diagnostics are never returned. Completion verifies account identity, Business status, fresh authorization and messaging permissions; it does not prove that every recipient can receive a message.
- **tokportal_request_account_business_setup** — Order Instagram Business setup. Requests a manager conversion and fresh connection for 5 credits, once per saved account. Requires write scope, active Coverage and current manager. Existing requests replay without a second debit; accounts already Business are not charged. Explicitly acknowledge restricted commercial music access. Manager payout is separate. Dry-run validates without charging or assigning a task.
- **tokportal_update_account_commenting_profile** — 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.
- **tokportal_list_account_bundles** — List bundles for a delivered account. Lists every bundle attached to one delivered account, including cancelled ones. Use it to see an account's full order history before ordering more work on it.
- **tokportal_retrieve_account_verification_code** — 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.
- **tokportal_reveal_account_credentials** — 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 header.
- **tokportal_can_refresh_account_analytics** — Check analytics refresh availability. Reports whether a manual analytics refresh is currently allowed and when the next one will be. Call it before refreshAccountAnalytics / refreshAnalyticsAccount to avoid a 429 cooldown (6 h for connected accounts, 24 h for the public fallback).
- **tokportal_refresh_account_analytics** — 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.
- **tokportal_get_account_edit_request** — Get active account edit request. Returns the account's profile edit requests, newest first, with their status and credit cost. Only one request can be open per account at a time, so check here before calling createAccountEditRequest.
- **tokportal_create_account_edit_request** — Request profile edits for a delivered account. Requests profile changes on an account that is already delivered and debits 8 credits. This is the ONLY way to change a delivered account's public username, visible name, biography, picture or link-in-bio: addEditSlots is unrelated (it buys video-editing slots) and configureBundleAccount only works before the account is delivered. Besides the username and visible name, supply at least one of requested_biography, requested_profile_picture_url or requested_link_in_bio — a request that changes nothing else is rejected. Only one request can be open per account at a time (409 otherwise); check getAccountEditRequest first. 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.
- **tokportal_rewarm_account** — 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.
- **tokportal_configure_bundle_warming_terms** — Configure the niche targets of a count-only Advanced Niche Warming purchase. Only for a bundle created with advanced_warming_terms_count (deferred targets). To warm an account that is already delivered, use rewarmAccount instead; this endpoint answers 404 WARMING_SESSION_NOT_FOUND when there is no count-only purchase to configure. 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. 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. A new account that has not produced a saved account yet remains configurable before delivery.
- **tokportal_list_account_warming_sessions** — 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.
- **tokportal_get_warming_session** — 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.
- **tokportal_generate_warming_terms** — 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. Call it before buying warming rather than inventing terms: pass the result to advanced_warming_terms (bundle creation or PUT /bundles/{id}/warming-terms deferred configuration) or to search_terms (rewarmAccount).
- **tokportal_list_webhook_events** — 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.
- **tokportal_list_webhook_endpoints** — List webhook endpoints. Lists your webhook endpoints with their subscribed events and enabled state. Signing secrets are never returned here — only once, at creation.
- **tokportal_create_webhook_endpoint** — Create a webhook endpoint. Creates a webhook endpoint and returns its signing secret once — store it, because a lost secret can only be replaced by deleting the endpoint and creating a new one. Call listWebhookEvents before choosing `events`: it returns the description, trigger condition and payload schema of each event, and several names are counter-intuitive. In particular account.published fires when YOU publish the order, not when the account is delivered — the delivery signal is account.in_review, and account.finalized fires when the account review is approved. 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.
- **tokportal_get_webhook_endpoint** — Get a webhook endpoint. Returns one webhook endpoint's URL, subscribed events and enabled state. The signing secret is not returned; if you lost it, delete this endpoint and create a replacement.
- **tokportal_update_webhook_endpoint** — 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.
- **tokportal_delete_webhook_endpoint** — Delete a webhook endpoint. Permanently deletes a webhook endpoint and invalidates its signing secret. Events that could not be delivered are not queued for a replacement endpoint.
- **tokportal_list_webhook_deliveries** — 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.
- **tokportal_retry_webhook_delivery** — 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.
- **tokportal_test_webhook_endpoint** — Send a test webhook. Sends a signed webhook.test event to the endpoint and records the delivery result.
- **tokportal_upload_video** — 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.
- **tokportal_upload_video_direct** — 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.
- **tokportal_upload_image** — 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.
- **tokportal_upload_image_direct** — 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`.
- **tokportal_upload_image_from_url** — 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`.
- **tokportal_get_analytics_dashboard** — Get analytics dashboard. Portfolio-level analytics across your accounts for a date range. Call getAnalyticsContract before interpreting these numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, the two intentionally do not mirror each other, and your access tier may redact metrics — a missing field means unavailable, never zero.
- **tokportal_get_analytics_contract** — Get analytics data contract. Returns the Analytics v2 contract, current access payload, metric semantics, freshness targets, and redaction rules.
- **tokportal_export_analytics_videos** — Export analytics videos CSV. CSV export of post-level analytics for the selected accounts and date range. Requires the Creator tier or above. Call getAnalyticsContract before interpreting these numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, the two intentionally do not mirror each other, and your access tier may redact metrics — a missing field means unavailable, never zero.
- **tokportal_create_analytics_report** — Create analytics web report. Creates a shareable Analytics v2 web report and returns its bearer-like access token and URL. The body is validated before anything is rendered, so a malformed request fails with INVALID_FIELD instead of quietly producing a wrong report for your end client. `from` and `to` are calendar dates in YYYY-MM-DD; a full ISO timestamp is accepted and truncated to its date, and anything else is refused rather than treated as "no filter" (which used to widen the report to the account's entire history). An inverted window (`from` after `to`) is refused too. `template` is a published enum — executive, agency, creator, minimal, growth, board — and an unknown value is refused instead of becoming executive. `brandAccent` must be #rrggbb (#rgb is expanded); named colours, rgb() and 8-digit hex are refused instead of being replaced by the TokPortal default. White-labelling still depends on entitlement: `brandName` and `brandAccent` only apply on the full analytics tier with a Farmer plan, and are otherwise reset. The response carries `applied` — the template, brand name, brand accent and the exact date window the report covers — plus `canBrand`, so read those back instead of inspecting the rendered report. 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.
- **tokportal_export_analytics_report_html** — Export analytics report HTML. Creates a standalone downloadable HTML analytics report from the same body as createAnalyticsReport, and validates it identically: `from` and `to` are YYYY-MM-DD (a full ISO timestamp is truncated to its date, anything else is refused with INVALID_FIELD rather than treated as no filter), an inverted window is refused, `template` is the published enum (executive, agency, creator, minimal, growth, board) and an unknown value is refused instead of becoming executive, and `brandAccent` must be #rrggbb or #rgb. The body of the response is the HTML document itself, so what was applied travels in headers: X-TokPortal-Report-Template, X-TokPortal-Report-Can-Brand, X-TokPortal-Report-Brand-Name, X-TokPortal-Report-From, X-TokPortal-Report-To, alongside X-TokPortal-Export-Rows and X-TokPortal-Export-Accounts. Read those headers to confirm the window and the branding actually used.
- **tokportal_get_analytics_series** — Get analytics time series. Daily or weekly time series for one metric, built from stored snapshots and date-scoped rollups — never a live fetch. `mode` selects cumulative totals, per-period gains, or raw snapshot values. Series are excluded on the Starter tier. Call getAnalyticsContract before interpreting these numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, the two intentionally do not mirror each other, and your access tier may redact metrics — a missing field means unavailable, never zero.
- **tokportal_get_analytics_account_insights** — Get connected Instagram or TikTok insights. Read stored account-period insights, daily follower/reach history and per-post watch time, completion, traffic and audience data. Requires Creator or above; fields remain tier-aware. available=false and connected_analytics=null when no recently verified active Zernio connection exists, including after disconnection. Never starts a provider refresh. Account metrics use the explicit period; post metrics are lifetime observations. Missing metrics are omitted, not zero; completion_rate is 0..1, traffic_sources and audience_types are 0..100 percentages, watch times are seconds. Instagram demographics need an eligible audience (normally 100+ followers). Detailed metrics may lag 24–48 hours. The same connected_analytics block appears on getAnalyticsAccount.
- **tokportal_get_analytics_account** — Get account analytics drilldown. Analytics v2 drilldown for one account: current metrics, top posts and demographics. Includes optional connected_analytics with account-period insights and post depth only while a Zernio connection has recent active identity proof; absent for disconnected accounts and Starter plans. getAnalyticsAccountInsights returns this block alone. This is the current endpoint; getAccountAnalytics is the older compatibility shape. Call getAnalyticsContract before interpreting numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, and your access tier may redact metrics. Missing fields mean unavailable, never zero.
- **tokportal_refresh_analytics_account** — 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.
- **tokportal_list_analytics_account_raw_snapshots** — List raw account analytics snapshots. Returns owner-scoped stored raw analytics payloads for a saved account. Full analytics tier only.
- **tokportal_get_account_analytics** — Get account analytics compatibility view. Legacy compatibility view of one account's analytics, kept for older integrations. New code should call getAnalyticsAccount instead. Call getAnalyticsContract before interpreting these numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, the two intentionally do not mirror each other, and your access tier may redact metrics — a missing field means unavailable, never zero.
- **tokportal_list_account_video_analytics** — List post analytics for an account. Post-level analytics for one account, sortable by views, likes, engagement rate or upload date. Values are lifetime per-post totals. Call getAnalyticsContract before interpreting these numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, the two intentionally do not mirror each other, and your access tier may redact metrics — a missing field means unavailable, never zero.
- **tokportal_get_video_analytics** — Get single video analytics. Lifetime metrics for one tracked post. Interpret them with getAnalyticsContract: these are lifetime per-post totals and deliberately do not match the rolling-window figures shown for a connected account. Also returns `platform_signals` (not recommended, AI label, sound) and `signal_insights` (followers gained, audience split, impression sources, retention curve — Creator tier and above).
- **tokportal_create_video_ad_code_request** — 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, which are not refundable. The platform is resolved from the video itself and cannot be chosen. 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, so a request made on the wrong video cannot be replaced until it closes. Poll the GET endpoint to retrieve the code once the manager submits it.
- **tokportal_get_video_ad_code_request** — 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`).
- **tokportal_get_comment_pulse** — Get comment pulse analytics. Aggregated comment sentiment and themes across your posts, served from the analytics comment cache — never a live fetch. Full analytics tier only. Filters are not combinable: when `post` is supplied it takes precedence and `platform`, `country`, `account`, `workspace`, `from` and `to` are all ignored, and at most 12 post ids are sampled.
- **tokportal_list_analytics_account_comments** — 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.
- **tokportal_list_analytics_post_raw_snapshots** — List raw post analytics snapshots. Returns owner-scoped stored raw analytics payloads for a tracked post. Full analytics tier only.
- **tokportal_list_analytics_signals** — 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.
- **tokportal_list_comment_tasks** — 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.
- **tokportal_create_comment_tasks** — Create comment tasks. Creates one comment task or a partial-success batch of up to 200. Each accepted task costs 1 credit. The target is any public TikTok or Instagram video, including a third party's — that is the intended use — while the posting account must be one of your own delivered accounts and its platform must match the target's (COMMENT_PLATFORM_MISMATCH otherwise). Deduplicate locally on (saved_account_id, target URL, comment_text): two different Idempotency-Keys carrying the same comment bill twice. 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, and read meta.rejected_count and each row's reason rather than inferring success from the 201. 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.
- **tokportal_get_comment_task** — Get a comment task. Returns one owned comment task, including whether inactive TokPortal Coverage currently blocks manager execution and the stable block reason.
- **tokportal_delete_comment_task** — 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.
- **tokportal_approve_comment_task** — 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.
- **tokportal_dispute_comment_task** — 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.
- **tokportal_list_comment_task_verifications** — List comment task verification events. Lists verifier attempts for one owned task. This read remains available while TokPortal Coverage pauses task execution.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "tokportal": {
    "command": "npx",
    "args": ["-y","tokportal-mcp"]
  }
}
```

## Documentation & README

# tokportal-mcp

[![npm](https://img.shields.io/npm/v/tokportal-mcp.svg)](https://www.npmjs.com/package/tokportal-mcp)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

TokPortal is the managed social infrastructure API: real TikTok and Instagram brand accounts created, warmed and operated by human account managers in 16+ countries, exposed as a REST API and an MCP server. Run geo-sharding across markets without connecting every social account through OAuth. YouTube bundle creation is not available through this API.

**Upgrade before using the sandbox:** local `tokportal-mcp` requires **1.15.1 or newer** for `dry_run`. Version 1.15.0 advertised the argument but did not send the sandbox header, so a preview could execute a real operation. Update your local server or use the [remote connector](https://developers.tokportal.com/mcp/remote/).

Docs https://developers.tokportal.com · API base https://app.tokportal.com/api/ext · OpenAPI https://developers.tokportal.com/openapi.json · MCP remote https://app.tokportal.com/api/ext/mcp · Get an API key https://app.tokportal.com/developer/api-keys?utm_source=npm&utm_medium=readme&utm_campaign=tokportal-mcp · llms.txt https://developers.tokportal.com/llms.txt

---

`tokportal-mcp` is the official [Model Context Protocol](https://modelcontextprotocol.io) server for the TokPortal API. Its core tools remain available to Claude, Cursor, VS Code, Windsurf, Codex, Gemini CLI and other MCP clients. When AI is enabled for your workspace, seven additional curated tools cover model discovery, quoted generation, media management and the separate AI USD wallet. Model-specific schemas are fetched on demand, not exposed as hundreds of tools.

Two ways to use it:

| Mode | Transport | When to use |
| --- | --- | --- |
| **Local** (`npx tokportal-mcp`) | stdio | Desktop clients, local agents, file uploads from disk |
| **Remote** (`https://app.tokportal.com/api/ext/mcp`) | Streamable HTTP | Hosted agents, no install; same tool catalogue |

Requires Node.js 20 or newer. The local server runs on it directly. Get an API key at https://app.tokportal.com/developer/api-keys?utm_source=npm&utm_medium=readme&utm_campaign=tokportal-mcp (format `sk_` + 64 hex chars).

## 30-second quickstart

```bash
npm install -g tokportal-mcp@1.22.0
TOKPORTAL_API_KEY=sk_your_key_here tokportal-mcp
```

The server speaks MCP over stdio. Point any MCP client at it and ask, for example:

> "Read the available countries, credit prices and my balance. Preview a TikTok account-only bundle in the USA with dry_run: true. Show me the immediate and recurring costs, and wait for my GO before any live purchase."

The preview calls `tokportal_create_bundle` with `{ "dry_run": true, "body": { "bundle_type": "account_only", "platform": "tiktok", "country": "USA" } }`. It validates the request and returns `credits_would_charge` with `credits_charged: 0`, without creating work. Creation in live mode is charged immediately. Preview IDs are synthetic and must never be reused in live requests. After GO, create the real resources and use their live IDs. See the [sandbox contract](https://developers.tokportal.com/sandbox/).

Programmatic smoke test with the MCP SDK:

```js
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const client = new Client({ name: "demo", version: "1.0.0" });
await client.connect(
  new StdioClientTransport({
    command: "npx",
    args: ["-y", "tokportal-mcp"],
    env: { ...process.env, TOKPORTAL_API_KEY: process.env.TOKPORTAL_API_KEY },
  }),
);

const { tools } = await client.listTools(); // Core tools, plus 7 when AI is enabled
const me = await client.callTool({ name: "tokportal_get_current_user", arguments: {} });
console.log(tools.length, me.content[0].text);
```

## AI generation (staged availability)

AI discovery calls authenticated `GET /ai/status`. If unavailable, only the existing catalogue is shown; no provider fallback or automatic payment is attempted. Local AI support requires `1.16.0` or newer and server-side availability. Installing this package does not enable generation, grant spending permissions or activate billing. Version `1.15.1` retains the existing account-management tools without AI discovery. Remote availability is controlled server-side.


Generation requires `body: { quote_id, max_cost_usd }` and `idempotency_key`. Reuse the same key after an uncertain response. Quotes expire within 15 minutes; use the returned expiry. The AI dollar wallet is independent of account-management credits. AI tools do not accept the legacy `dry_run` contract; use the quote operation, which does not start paid provider work. Cancellation is best effort, not a refund guarantee. Creation does not publish: review the returned assets, then use existing TokPortal scheduling tools.

## Client configuration

Replace `sk_your_key_here` with your key. Every snippet below is the local stdio server; the remote URL variant is listed at the end.

### Cursor

`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "tokportal": {
      "command": "npx",
      "args": ["-y", "tokportal-mcp"],
      "env": { "TOKPORTAL_API_KEY": "sk_your_key_here" }
    }
  }
}
```

### Claude Desktop

`claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):

```json
{
  "mcpServers": {
    "tokportal": {
      "command": "npx",
      "args": ["-y", "tokportal-mcp"],
      "env": { "TOKPORTAL_API_KEY": "sk_your_key_here" }
    }
  }
}
```

### Claude Code

```bash
claude mcp add tokportal -e TOKPORTAL_API_KEY=sk_your_key_here -- npx -y tokportal-mcp
# or the remote server:
claude mcp add --transport http tokportal https://app.tokportal.com/api/ext/mcp --header "X-API-Key: sk_your_key_here"
```

### VS Code (GitHub Copilot agent mode)

`.vscode/mcp.json`:

```json
{
  "servers": {
    "tokportal": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tokportal-mcp"],
      "env": { "TOKPORTAL_API_KEY": "sk_your_key_here" }
    }
  }
}
```

### Windsurf

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "tokportal": {
      "command": "npx",
      "args": ["-y", "tokportal-mcp"],
      "env": { "TOKPORTAL_API_KEY": "sk_your_key_here" }
    }
  }
}
```

### OpenAI Codex CLI

`~/.codex/config.toml`:

```toml
[mcp_servers.tokportal]
command = "npx"
args = ["-y", "tokportal-mcp"]
env = { TOKPORTAL_API_KEY = "sk_your_key_here" }
```

### Gemini CLI

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "tokportal": {
      "command": "npx",
      "args": ["-y", "tokportal-mcp"],
      "env": { "TOKPORTAL_API_KEY": "sk_your_key_here" }
    }
  }
}
```

### Remote server (Streamable HTTP)

Any client that supports remote MCP servers can connect to
`https://app.tokportal.com/api/ext/mcp` with either an `X-API-Key: sk_...` header
or `Authorization: Bearer sk_...`. Example for clients using the `url` form:

```json
{
  "mcpServers": {
    "tokportal": {
      "url": "https://app.tokportal.com/api/ext/mcp",
      "headers": { "X-API-Key": "sk_your_key_here" }
    }
  }
}
```

## Environment variables

| Variable | Required | Description |
| --- | --- | --- |
| `TOKPORTAL_API_KEY` | yes | API key (`sk_` + 64 hex). Only a SHA-256 hash is stored server-side. |
| `TOKPORTAL_BASE_URL` | no | Defaults to `https://app.tokportal.com/api/ext`. |

## How the tools work

The server exposes TokPortal API actions as MCP tools over stdio. It is generated from the public API schema and uses the same `X-API-Key` authentication as the HTTP API.

- Tool names are `tokportal_<operation_id_snake_case>` (`tokportal_create_bundle`, `tokportal_list_accounts`, ...). Path and query parameters are top-level inputs; JSON bodies go in `body`.
- Every tool carries `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint`. Read the annotations on each tool: paid operations and irreversible actions can be destructive even when they do not delete anything.
- Every non-GET tool accepts top-level `dry_run: true`, sent as `X-TokPortal-Dry-Run: true`. It is never placed in the query or request body. Dry runs consume normal rate limits but do not consume an `idempotency_key`; use the same key for a later live request if its operation supports idempotency.
- Multipart upload tools are generated from OpenAPI too. Binary fields are exposed as local path inputs such as `file_path`, with the remaining form fields exposed by their schema names.
- Mutations accept an optional `idempotency_key` (sent as `Idempotency-Key`) except for secret-bearing operations (credential reveal, verification codes, webhook creation, signed upload URLs, report creation) which are never replayed.

The MCP server sends `X-TokPortal-Client: tokportal-mcp/1.22.0` on API requests for observability and support diagnostics.

Failed tool calls return an error result with a `diagnostics` object containing `request_id`, `retry_after_seconds`, and `rate_limit` when those headers are available.

Legacy config using the globally installed binary still works:

```json
{
  "mcpServers": {
    "tokportal": {
      "command": "tokportal-mcp",
      "env": {
        "TOKPORTAL_API_KEY": "sk_your_key_here"
      }
    }
  }
}
```

## Source of truth

This package is generated from the TokPortal public OpenAPI schema
(https://developers.tokportal.com/openapi.json) in the private TokPortal
monorepo. `src/generated.ts` is regenerated on every release — do not edit it by
hand. See [CONTRIBUTING.md](https://github.com/tokportal/tokportal-mcp/blob/HEAD/CONTRIBUTING.md) for what we accept as PRs and
[SECURITY.md](https://github.com/tokportal/tokportal-mcp/blob/HEAD/SECURITY.md) for vulnerability reporting.

## Links

- Documentation: https://developers.tokportal.com
- MCP guide: https://developers.tokportal.com/mcp
- SDKs & CLI: https://developers.tokportal.com/sdks-cli
- API reference (OpenAPI): https://developers.tokportal.com/openapi.json
- Other packages: [`@tokportal/node`](https://www.npmjs.com/package/@tokportal/node) · [`@tokportal/cli`](https://www.npmjs.com/package/@tokportal/cli) · [`tokportal` (PyPI)](https://pypi.org/project/tokportal/) · [`github.com/tokportal/tokportal-go`](https://github.com/tokportal/tokportal-go)

MIT © TokPortal

## Connected analytics (1.18.0)

Use `tokportal_get_analytics_account_insights` with `{ "id": "saved-account-uuid" }` to read Instagram account-period reach/views/engagement and eligible TikTok post watch time/completion/traffic data. Requires Creator or above; existing tiers remain enforced. A disconnected or unverified account returns `available: false` with `connected_analytics: null`. This is read-only and never starts a refresh. Missing metrics are omitted, completion is a 0–1 fraction, traffic/audience splits are 0–100 percentages, and watch times are seconds. The same block appears on `tokportal_get_analytics_account`. [Full contract](https://developers.tokportal.com/analytics/#connected-instagram-and-tiktok-insights).

## Inbox actions and Business setup (1.19.0)

Read scoped received comments and Instagram messages with `tokportal_get_account_inbox`. Reply publicly with `tokportal_create_account_comment_reply` (0 credits, requires a signed reply capability, stable request key, current Coverage and account quota). Check delivery with `tokportal_get_account_comment_reply`; never blindly resend an unknown result.

`tokportal_get_account_business_setup` reads progression; `tokportal_request_account_business_setup` orders the manager task for 5 credits once per Instagram account, after explicit music-limit acknowledgment. TikTok DMs are unavailable. Public metadata webhooks notify connection, incoming activity, reply result and Business task changes. See the Connection & Inbox guide for contracts and limits.

### Keyword comment moderation

`tokportal_get_account_comment_moderation` reads account rules and result history.
`tokportal_update_account_comment_moderation` saves explicit keyword/exception rules for Instagram and TikTok. Read the settings version first. Disabled by default; no DM or credit charge. Only new comments are processed after saving. TikTok unhide is currently unreliable, and disabling rules does not restore hidden comments. Use `dry_run: true` to validate without saving.

### Instagram messaging and comment-to-DM

Use `tokportal_send_account_inbox_message` for replies in an existing Instagram
conversation within 24 hours of an incoming message. Use
`tokportal_create_account_private_reply` once per comment within seven days.
Creator and Business are eligible when connection permissions allow. Fetch
account-bound references through `tokportal_get_account_inbox`; arbitrary
recipient IDs are not accepted. These actions currently charge no credits.

`tokportal_get_account_comment_dm` and `tokportal_update_account_comment_dm`
manage one opt-in keyword rule per account, optionally scoped to an owned post.
Rules start disabled, process only new original comments and expose durable
history. Shared account cooldowns, Coverage, strict identity checks and durable
request-key dedupe apply. Unknown delivery must never trigger a blind resend.
Use `tokportal_get_account_message_operation` for status. A private reply alone
does not permit follow-up DMs. TikTok DMs are not offered.

Full guide: https://developers.tokportal.com/account-connection-inbox

### Manual comment controls (1.22.0)

`tokportal_create_account_comment_action` supports delete, hide, Instagram unhide
and TikTok top-level pin/unpin only when returned in the comment's `actions`.
Pass the exact signed action reference and post reference. Confirm permanent
deletion with the user first. Costs 0 credits. The server checks permissions,
Coverage, current connection and provider capabilities before reserving a shared
account lease. Use a stable `request_key`; use
`tokportal_get_account_comment_action` after an uncertain result. Never blindly
repeat pending/unknown writes. `dry_run: true` verifies without modifying comments.
`inbox.comment.action.updated` contains result metadata only. TikTok unhide and
likes are not exposed in this release. Wait for `Retry-After`; quotas are not
safe activity targets and cannot guarantee that an account will not be restricted.