# TokPortal API

> TokPortal lets developers create geo-targeted TikTok and Instagram accounts, configure videos, publish bundles, retrieve delivered accounts, and pull analytics through one API.

## Canonical URLs

- Docs: https://developers.tokportal.com
- App API base URL: https://app.tokportal.com/api/ext
- OpenAPI JSON: https://developers.tokportal.com/openapi.json
- OpenAPI YAML: https://developers.tokportal.com/openapi.yaml
- Full LLM context: https://developers.tokportal.com/llms-full.txt
- AI context JSON: https://developers.tokportal.com/ai-context.json
- Developer ecosystem JSON: https://developers.tokportal.com/developer-ecosystem.json
- Package release manifest: https://developers.tokportal.com/package-release-manifest.json
- Developer package export command: `npm run export:developer-packages`.

## API Versioning

- Current public API version: `2026-05-25`
- Response header: `X-TokPortal-API-Version: 2026-05-25`
- Response header: `X-TokPortal-API-Stability: stable`
- Response header: `X-TokPortal-Request-ID: req_...`
- Rate limit headers on authenticated responses: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
- 429 responses include `Retry-After`.
- Compatibility policy: additive non-breaking changes remain in the current version; breaking changes require a new public API version and changelog entry.

## Authentication

- Header: `X-API-Key: sk_...`
- New keys use `sk_` followed by 64 lowercase hex characters.
- Raw keys are shown once at creation and stored by TokPortal as SHA-256 hashes.

## Core Concepts

- Profiles: API key owner and developer account context.
- Bundles: account/video work orders grouped by platform and country.
- Accounts: delivered social accounts with credentials and verification flows.
- Posts: video slots configured, published, reviewed, and finalized inside bundles.

## API Reference

- [Social Media Account Creation API – Overview](https://developers.tokportal.com/overview)
- [API Authentication & API Keys](https://developers.tokportal.com/authentication)
- [API Credits & Pricing Per Operation](https://developers.tokportal.com/credits)
- [API Error Codes & Troubleshooting](https://developers.tokportal.com/errors)
- [Rate Limits, Pagination & Idempotency](https://developers.tokportal.com/rate-limits)
- [Getting Started – First API Call in 5 Minutes](https://developers.tokportal.com/getting-started)
- [OpenAPI, SDKs, CLI & MCP](https://developers.tokportal.com/sdks-cli)
- [AI Context](https://developers.tokportal.com/ai-context)
- [Versioning & Stability](https://developers.tokportal.com/versioning)
- [Changelog](https://developers.tokportal.com/changelog)
- [Bundles – Campaign Management API](https://developers.tokportal.com/bundles)
- [Create Bundle - Provision Accounts & Videos](https://developers.tokportal.com/create-bundle)
- [Create Bulk - Multiple Bundles](https://developers.tokportal.com/create-bulk)
- [Publish & Unpublish Bundles via API](https://developers.tokportal.com/publish-unpublish)
- [Account Configuration – Profile Setup API](https://developers.tokportal.com/account-configuration)
- [Account Review & Approval Actions](https://developers.tokportal.com/account-actions)
- [Video Management – Types, Formats & Statuses](https://developers.tokportal.com/videos)
- [Configure Videos – Metadata & Scheduling API](https://developers.tokportal.com/configure-videos)
- [CSV Import – Bulk Video Upload from Spreadsheet](https://developers.tokportal.com/csv-import)
- [Video Actions – Publish, Finalize & Corrections](https://developers.tokportal.com/video-actions)
- [Fix Broken Video Download Links](https://developers.tokportal.com/fix-download-link)
- [Delivered Accounts – Credentials & Verification Codes](https://developers.tokportal.com/saved-accounts)
- [Account Edit Request – Profile Updates via API](https://developers.tokportal.com/account-edit-request)
- [Analytics API – Analytics v2](https://developers.tokportal.com/analytics)
- [Media Upload – Videos & Images via Presigned URLs](https://developers.tokportal.com/media-upload)
- [MCP Server – AI Integration for Cursor & Claude](https://developers.tokportal.com/mcp)
- [OpenClaw Skill – AI Social Media Automation](https://developers.tokportal.com/openclaw)
- [Comments – Overview & Lifecycle](https://developers.tokportal.com/comments-overview)
- [Create Comments – Single & Batch](https://developers.tokportal.com/create-comments)
- [List & Read Comment Tasks](https://developers.tokportal.com/list-and-read-comments)
- [Approve & Dispute – Review Flow](https://developers.tokportal.com/comments-review-flow)
- [Verifier Timeline – Verbose Audit](https://developers.tokportal.com/comments-verifications)
- [Webhooks](https://developers.tokportal.com/webhooks)
- [API Reference](https://developers.tokportal.com/api-reference)

## Use Cases

- [TokPortal + n8n - TikTok Workflow via HTTP](https://developers.tokportal.com/use-cases/n8n-tiktok-automation)
- [TokPortal + Zapier - Social Campaigns via Webhooks](https://developers.tokportal.com/use-cases/zapier-social-media-automation)
- [TokPortal + Make - TikTok Workflow via HTTP](https://developers.tokportal.com/use-cases/make-tiktok-automation)
- [TokPortal + OpenClaw](https://developers.tokportal.com/use-cases/openclaw-tiktok-posting)
- [TokPortal MCP Server for Cursor](https://developers.tokportal.com/use-cases/cursor-mcp-tiktok)
- [TokPortal + Claude via MCP](https://developers.tokportal.com/use-cases/claude-code-social-media)
- [Create Instagram Account Bundles with TokPortal API](https://developers.tokportal.com/use-cases/create-instagram-accounts-api)
- [Order a US TikTok Workflow with TokPortal API](https://developers.tokportal.com/use-cases/post-us-tiktok-from-abroad)
- [Bulk TikTok Bundle Creation API](https://developers.tokportal.com/use-cases/bulk-tiktok-accounts-api)
- [Python Quickstart - TokPortal API](https://developers.tokportal.com/use-cases/python-quickstart)
- [TokPortal API for Agencies](https://developers.tokportal.com/use-cases/agency-multi-client-management)
- [DTC Multi-Market Launch](https://developers.tokportal.com/use-cases/dtc-multi-market-launch)
- [Music Promotion on TikTok with TokPortal](https://developers.tokportal.com/use-cases/music-promotion-tiktok)
- [Product Seeding Workflows for TikTok](https://developers.tokportal.com/use-cases/tiktok-shop-product-seeding)
- [UGC Distribution at Scale](https://developers.tokportal.com/use-cases/ugc-distribution-at-scale)
- [TokPortal Use Cases & Integrations](https://developers.tokportal.com/use-cases/)

## Public Operations

- GET /me — Get authenticated user (getCurrentUser)
- GET /countries — List available countries (listCountries)
- GET /platforms — List available platforms (listPlatforms)
- GET /credit-costs — Get credit pricing (getCreditCosts)
- GET /credits/balance — Get credit balance (getCreditBalance)
- GET /credits/history — List credit transactions (listCreditTransactions)
- GET /bundles — List bundles (listBundles)
- POST /bundles — Create a bundle (createBundle)
- POST /bundles/bulk — Create bundles in bulk (createBundlesBulk)
- GET /bundles/{id} — Get a bundle (getBundle)
- PATCH /bundles/{id} — Update bundle settings (updateBundle)
- POST /bundles/{id}/publish — Publish a bundle (publishBundle)
- GET /bundles/{id}/publish-readiness — Check bundle publish readiness (getBundlePublishReadiness)
- POST /bundles/{id}/unpublish — Unpublish a bundle (unpublishBundle)
- POST /bundles/{id}/add-video-slots — Add video slots to a bundle (addVideoSlots)
- POST /bundles/{id}/add-edit-slots — Add edit slots to a bundle (addEditSlots)
- GET /bundles/{id}/account — Get bundle account configuration (getBundleAccount)
- PUT /bundles/{id}/account — Configure bundle account profile (configureBundleAccount)
- POST /bundles/{id}/account/corrections — Request account corrections (requestBundleAccountCorrections)
- POST /bundles/{id}/account/finalize — Finalize account review (finalizeBundleAccount)
- GET /bundles/{id}/videos — List bundle video slots (listBundleVideos)
- GET /bundles/{id}/videos/{position} — Get video slot configuration (getBundleVideo)
- PUT /bundles/{id}/videos/{position} — Configure a video slot (configureBundleVideo)
- PATCH /bundles/{id}/videos/{position} — Patch video references (patchBundleVideo)
- PUT /bundles/{id}/videos/batch — Configure video slots in bulk (batchConfigureBundleVideos)
- POST /bundles/{id}/videos/publish-all — Publish all configured videos on an active bundle (publishAllBundleVideos)
- POST /bundles/{id}/videos/import-csv — Import video slots from CSV (importBundleVideosCsv)
- POST /bundles/{id}/videos/{position}/publish — Publish one video slot (publishBundleVideo)
- POST /bundles/{id}/videos/{position}/reset — Reset one video slot (resetBundleVideo)
- POST /bundles/{id}/videos/{position}/unschedule — Unschedule one video slot (unscheduleBundleVideo)
- POST /bundles/{id}/videos/{position}/finalize — Finalize video review (finalizeBundleVideo)
- POST /bundles/{id}/videos/{position}/corrections — Request video corrections (requestBundleVideoCorrections)
- POST /bundles/{id}/videos/{position}/fix-download — Fix a broken video download (fixBundleVideoDownload)
- GET /accounts — List delivered accounts (listAccounts)
- GET /accounts/{id} — Get a delivered account (getAccount)
- GET /accounts/{id}/bundles — List bundles for a delivered account (listAccountBundles)
- POST /accounts/{id}/verification-code — Retrieve latest account verification code (retrieveAccountVerificationCode)
- POST /accounts/{id}/reveal-credentials — Reveal delivered account credentials (revealAccountCredentials)
- GET /accounts/{id}/analytics/can-refresh — Check analytics refresh availability (canRefreshAccountAnalytics)
- POST /accounts/{id}/analytics/refresh — Refresh account analytics (refreshAccountAnalytics)
- GET /accounts/{id}/edit-request — Get active account edit request (getAccountEditRequest)
- POST /accounts/{id}/edit-request — Request profile edits for a delivered account (createAccountEditRequest)
- GET /webhooks/events — List webhook event catalog (listWebhookEvents)
- GET /webhooks — List webhook endpoints (listWebhookEndpoints)
- POST /webhooks — Create a webhook endpoint (createWebhookEndpoint)
- GET /webhooks/{id} — Get a webhook endpoint (getWebhookEndpoint)
- PATCH /webhooks/{id} — Update a webhook endpoint (updateWebhookEndpoint)
- DELETE /webhooks/{id} — Delete a webhook endpoint (deleteWebhookEndpoint)
- GET /webhooks/{id}/deliveries — List webhook deliveries (listWebhookDeliveries)
- POST /webhooks/{id}/deliveries/{delivery_id}/retry — Retry a webhook delivery (retryWebhookDelivery)
- POST /webhooks/{id}/test — Send a test webhook (testWebhookEndpoint)
- POST /upload/video — Create a video upload URL (uploadVideo)
- POST /upload/video/direct — Upload a video file directly (uploadVideoDirect)
- POST /upload/image — Create an image upload URL (uploadImage)
- POST /upload/image/direct — Upload an image file directly (uploadImageDirect)
- POST /upload/image/from-url — Import an image from URL (uploadImageFromUrl)
- GET /analytics — Get analytics dashboard (getAnalyticsDashboard)
- GET /analytics/contract — Get analytics data contract (getAnalyticsContract)
- GET /analytics/export/videos — Export analytics videos CSV (exportAnalyticsVideos)
- POST /analytics/export/reports — Create analytics web report (createAnalyticsReport)
- POST /analytics/export/reports/html — Export analytics report HTML (exportAnalyticsReportHtml)
- GET /analytics/series — Get analytics time series (getAnalyticsSeries)
- GET /analytics/accounts/{id} — Get account analytics drilldown (getAnalyticsAccount)
- POST /analytics/accounts/{id}/refresh — Refresh analytics account (refreshAnalyticsAccount)
- GET /analytics/accounts/{id}/raw — List raw account analytics snapshots (listAnalyticsAccountRawSnapshots)
- GET /accounts/{id}/analytics — Get account analytics compatibility view (getAccountAnalytics)
- GET /accounts/{id}/analytics/videos — List post analytics for an account (listAccountVideoAnalytics)
- GET /videos/{id}/analytics — Get single video analytics (getVideoAnalytics)
- GET /analytics/comments — Get comment pulse analytics (getCommentPulse)
- GET /analytics/accounts/{id}/comments — List comments for an account post (listAnalyticsAccountComments)
- GET /analytics/posts/{id}/raw — List raw post analytics snapshots (listAnalyticsPostRawSnapshots)
- GET /comments — List comment tasks (listCommentTasks)
- POST /comments — Create comment tasks (createCommentTasks)
- GET /comments/{id} — Get a comment task (getCommentTask)
- DELETE /comments/{id} — Delete a comment task (deleteCommentTask)
- POST /comments/{id}/approve — Approve a manually confirmed comment task (approveCommentTask)
- POST /comments/{id}/dispute — Dispute a manually confirmed comment task (disputeCommentTask)
- GET /comments/{id}/verifications — List comment task verification events (listCommentTaskVerifications)