Getting Started

Changelog

Public TokPortal API, SDK, CLI, MCP, and documentation changelog.

Changelog

2026-07-16

  • Clarified the account and video review lifecycle: an account listing or video listing left in in_review without user review is automatically moved to finalized after 72 hours.

2026-07-12

  • Ban visibility end-to-end. When an account ban is validated (manager report with no appeal, refused platform appeal, or staff confirmation), TokPortal now cancels every active bundle/order on the account and pushes the signal everywhere:
    • New bundle.cancelled webhook event — fired for each cancelled bundle with reason, cancelled_at, account_banned, saved_account_id, and username. See Webhooks.
    • Documented the existing account.banned and account.ban_appeal.resolved webhook events (emitted since the CM ban-report flow shipped).
    • GET /accounts and GET /accounts/:id now return banned and a ban object (reason, banned_at, plus appeal_status and a signed screenshot_url on the detail response). Banned accounts stay visible.
    • GET /bundles and GET /bundles/:id now return cancelled_at and cancelled_reason.
    • 409 BUNDLE_INVALID_STATUS on publish calls now includes cancelled_at / cancelled_reason when the bundle is cancelled, so the error itself tells you why.
    • Documented the cancelled bundle status in the bundle lifecycle.

2026-07-10

  • Advanced Niche Warming — recorded, AI-verified account warming for TikTok and Instagram (3 credits per niche target, 3-30 targets in multiples of 3). New bundle fields wants_advanced_warming + advanced_warming_terms / advanced_warming_terms_count on POST /bundles and POST /bundles/bulk. See the Advanced Niche Warming guide.
  • Deferred target configuration: buy the target count at creation (advanced_warming_terms_count) and write the targets afterwards via PUT /bundles/:id/account with advanced_warming_terms (one-shot; must match the purchased count exactly). Warming starts at configuration when the account/order is already active, else at submission/accept. Count-only purchases never configured within 14 days are auto-cancelled and fully refunded.
  • Warming task spec: each recording opens on the account profile (handle visible), then the manager searches the target, watches videos from the results, engages with them (likes/saves) and leaves a comment. Every recording is verified before it counts.
  • New endpoints: POST /accounts/:id/rewarm, GET /accounts/:id/warming-sessions, GET /warming-sessions/:id, POST /warming/generate-terms (free AI target generation).
  • New webhooks: warming.session_started, warming.term_verified, warming.session_completed. Bundle payloads expose advanced_warming_terms_count; account payloads gain an advanced_warming summary (with terms_configured).
  • New error codes: ADVANCED_WARMING_PLATFORM, ADVANCED_WARMING_TERMS, WARMING_TERMS_ALREADY_SET, WARMING_SESSION_NOT_FOUND, REWARM_NO_ACTIVE_ORDER, REWARM_ALREADY_ACTIVE, TERM_GENERATION_FAILED, AI_UNAVAILABLE.
  • Deep warming is discontinued: wants_deep_warming: true is now rejected with DEEP_WARMING_DEPRECATED (in-flight orders keep working). Niche warming is review-based and will be deprecated in favor of Advanced Niche Warming.

2026-06-19

  • Added the account.remade webhook event, emitted when an account is remade after a ban or loss. Payload includes bundle_id, external_ref, old_username, new_username, old_account_id, reason, mode, remade_count, and remade_at.
  • Added a remade object to bundle responses (GET /bundles and GET /bundles/:id) with was_remade, remade_count, old_username, and remade_at.
  • Added bundle_id and external_ref to the account detail response (GET /accounts/:id) — stable anchors for correlating an account across remakes (the saved account id itself changes on a remake).
  • Added saved_account_id to GET /bundles/:id (top-level and inside account) and to the account.* webhook payloads (populated from account.in_review onward) — the clean way to obtain the real/new saved-account id for a bundle, including after a remake. Documented the account-listing vs saved-account distinction.

2026-05-25

  • Added first-class OpenAPI assets at /openapi.json and /openapi.yaml.
  • Added llms.txt and llms-full.txt for LLM ingestion.
  • Added ai-context.json and developer-ecosystem.json for structured AI and developer ecosystem ingestion.
  • Documented the canonical API key format: sk_ followed by 64 lowercase hex characters, stored as SHA-256, shown once at creation.
  • Added public Node / TypeScript SDK package: @tokportal/node.
  • Added public CLI package: @tokportal/cli.
  • Added published public MCP package: tokportal-mcp.
  • Deferred Python, Go, Ruby, Java, PHP, .NET, and Rust SDKs until their registry or repository release path is ready.
  • Added package distribution metadata and a public ecosystem manifest with release status for SDK, CLI, and MCP surfaces.
  • Added structured SDK error handling docs for Node, including request IDs and retryability helpers.
  • Added SDK idempotency examples.
  • Added X-TokPortal-Client identification headers across generated SDKs, CLI, and MCP server.
  • Added public API version and stability response headers: X-TokPortal-API-Version: 2026-05-25 and X-TokPortal-API-Stability: stable.
  • Added X-TokPortal-Request-ID response headers across public API responses and SDK error parsing for support/debug correlation.
  • Added request ID persistence in API logs and per-key usage inspection in the Developer Portal.
  • Added API key environment tags, read/write scopes, optional expiry dates, and scope-aware auth errors without changing existing keys.
  • Added API key metadata editing and audit trail events for creation, updates, rotation, rotation replacements, and revocation.
  • Added X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers for authenticated public API requests.
  • Added SDK error metadata for rate limiting and backoff: Node retryAfterSeconds and rateLimit.
  • Added Node webhook signature helper docs plus manual HMAC verification examples.
  • Added CLI and MCP error diagnostics with request_id, retry_after_seconds, and rate_limit metadata.
  • Added the Versioning & Stability docs page with backwards compatibility and deprecation policy.
  • Added public webhook endpoint registry at /webhooks with emitted bundle, account, video, and test events, delivery logs, and test delivery support.
  • Added the public webhook event catalog at /webhooks/events with event availability, payload schemas, example payloads, delivery headers, and signature metadata.
  • Added manual webhook delivery retry at /webhooks/{id}/deliveries/{delivery_id}/retry, preserving the event ID and recording a new signed attempt.
  • Added persisted Idempotency-Key handling for mutating API requests, including replay detection and conflict errors.
  • Expanded OpenAPI/SDK coverage for Analytics v2 contract/export/report endpoints and media upload helpers, including direct upload and image import from URL.
  • Expanded OpenAPI/SDK coverage for bundle updates, account/video review lifecycle actions, video download fixes, analytics refresh checks, raw analytics snapshots, and standalone HTML report export.
  • Added generated OpenAPI x-codeSamples for every operation across curl, Node, Python, and Go.
  • Added a generated /api-reference docs page from OpenAPI so every operation and code sample is searchable and included in llms-full.txt.
  • Kept legacy API key validation compatible while new keys use the canonical sk_ format.