Source: https://developers.tokportal.com/getting-started/
Markdown: https://developers.tokportal.com/getting-started.md

# Getting Started

Try your first TokPortal integration in 5 minutes without spending credits. The write requests below use the [sandbox](https://developers.tokportal.com/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](https://github.com/tokportal):

| Surface                                        | Install                                                                  | Repo                                                                                                                |
| ---------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Node / TypeScript SDK                          | `npm install @tokportal/node`                                            | [tokportal-node](https://github.com/tokportal/tokportal-node)                                                       |
| Python SDK                                     | `pip install tokportal`                                                  | [tokportal-python](https://github.com/tokportal/tokportal-python)                                                   |
| Go SDK                                         | `go get github.com/tokportal/tokportal-go`                               | [tokportal-go](https://github.com/tokportal/tokportal-go)                                                           |
| CLI                                            | `npm install -g @tokportal/cli`                                          | [tokportal-cli](https://github.com/tokportal/tokportal-cli)                                                         |
| MCP server (Claude, Cursor, ChatGPT, VS Code…) | `npx -y tokportal-mcp` or remote `https://app.tokportal.com/api/ext/mcp` | [tokportal-mcp](https://github.com/tokportal/tokportal-mcp) · [install guide](https://developers.tokportal.com/mcp) |
| Examples                                       | copy-paste scripts and workflows                                         | [examples](https://github.com/tokportal/examples)                                                                   |

## Prerequisites

- A TokPortal account at [app.tokportal.com](https://app.tokportal.com/)
- An API key ([generate one](https://app.tokportal.com/developer/api-keys))

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](https://app.tokportal.com/developer/api-keys) and click **Generate**. Copy your key — it starts with `sk_` and is shown only once.

## Step 2: Verify Your Key

```bash
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

```bash
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

```bash
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:

```bash
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](https://developers.tokportal.com/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

```bash
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:

```bash
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](https://developers.tokportal.com/sdks-cli) — Node, Python, Go, CLI ([GitHub](https://github.com/tokportal))
- [MCP Server](https://developers.tokportal.com/mcp) — drive TokPortal from Claude, Cursor, ChatGPT, VS Code and other AI agents
- [Create Bulk bundles](https://developers.tokportal.com/bundles/create-bulk) for large-scale campaigns
- [CSV Import](https://developers.tokportal.com/videos/csv-import) for spreadsheet-based workflows
- [Analytics](https://developers.tokportal.com/analytics) to track account performance
- [Accounts](https://developers.tokportal.com/accounts/saved-accounts) to manage delivered accounts and retrieve verification codes