Getting Started

Try your first TokPortal integration in 5 minutes without spending credits. The write requests below use the sandbox: real validation and pricing, with nothing created or published.

Prefer a language SDK, the CLI or an AI agent? Everything is open source on GitHub at github.com/tokportal:

Prerequisites

• A TokPortal account at app.tokportal.com
• An API key (generate one)

Credits are needed for paid live calls, after you have tested the request and reviewed its price.

Step 1: Generate an API Key

Go to the Developer Portal and click Generate. Copy your key — it starts with sk_ and is shown only once.

Step 2: Verify Your Key

curl https://app.tokportal.com/api/ext/me \
  -H "X-API-Key: sk_your_key_here"

You should see your profile and credit balance.

Step 3: Simulate a Bundle

curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-TokPortal-Dry-Run: true" \
  -H "Idempotency-Key: first-bundle-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_type": "account_and_videos",
    "platform": "tiktok",
    "country": "USA",
    "title": "My First Bundle",
    "videos_quantity": 5
  }'

This simulates a TikTok account in the USA with 5 video slots. The response contains data.bundle_id, dry_run: true, credits_charged: 0 and credits_would_charge. Those pricing fields are at the top level of the response. The standard estimate is 42 credits (32 for setup plus 5 x 2 video credits); use the returned credits_would_charge, which reflects your workspace pricing and any contract allowance.

Copy data.bundle_id into {bundle_id} below. It starts with 00000000-0000-4000-8000- and can be used only in subsequent dry-run writes. Simulated bundles have no cross-call memory, so this checks individual request shapes rather than the state of a real account.

Step 4: Simulate Account Configuration

curl -X PUT https://app.tokportal.com/api/ext/bundles/{bundle_id}/account \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-TokPortal-Dry-Run: true" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "mybrand",
    "visible_name": "My Brand Official",
    "biography": "Fashion and lifestyle content"
  }'

Step 5: Simulate Video Configuration

Use a public sample video URL to validate a slot. This does not upload or publish the video:

curl -X PUT https://app.tokportal.com/api/ext/bundles/{bundle_id}/videos/1 \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-TokPortal-Dry-Run: true" \
  -H "Content-Type: application/json" \
  -d '{
    "video_type": "video",
    "description": "Check out this trend! #fashion",
    "target_publish_date": "2026-09-01",
    "video_url": "https://cdn.example.com/video1.mp4"
  }'

Or use batch configuration to set up multiple videos at once, or CSV import to import from a spreadsheet.

For a live run, follow Media Upload to obtain an upload URL, upload your file, and use the returned public URL. An upload URL returned by a dry run is a placeholder; do not send a file to it.

Step 6: Simulate Publishing

curl -X POST https://app.tokportal.com/api/ext/bundles/{bundle_id}/publish \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-TokPortal-Dry-Run: true"

This validates the publish request in simulation. No account manager receives an order. GET requests read real data, so do not poll or run publish-readiness checks on this synthetic bundle.

Step 7: Confirm the Price and Run for Real

Review credits_would_charge from creation before continuing. Credits are debited when a real bundle is created, before publishing. Only after you approve that cost, repeat Step 3 without X-TokPortal-Dry-Run and use its new real data.bundle_id for the remaining steps. The same Idempotency-Key is safe to reuse: a dry run does not consume it.

Never reuse a synthetic ID in a live request. Configure the real bundle with your actual media and schedule, then publish it without the dry-run header to send the order to a manager. You can now track the real bundle:

curl https://app.tokportal.com/api/ext/bundles/{bundle_id} \
  -H "X-API-Key: sk_your_key_here"

Monitor the status field on the bundle, account, and each video.

What's Next?

• SDKs & CLI — Node, Python, Go, CLI (GitHub)
• MCP Server — drive TokPortal from Claude, Cursor, ChatGPT, VS Code and other AI agents
• Create Bulk bundles for large-scale campaigns
• CSV Import for spreadsheet-based workflows
• Analytics to track account performance
• Accounts to manage delivered accounts and retrieve verification codes