### Example: Retrieve Bundle Account with cURL

Source: https://developers.tokportal.com/account-config/account-configuration

An example using cURL to retrieve the account configuration for a bundle. This demonstrates how to make a GET request to the API endpoint.

```curl
curl -X GET https://app.tokportal.com/api/ext/bundles/bnd_abc123/account \
  -H "X-API-Key: tok_live_xxx"
```

--------------------------------

### Verify API Key and Get Account Info (curl)

Source: https://developers.tokportal.com/getting-started/overview

This example demonstrates how to verify your API key and retrieve basic account information using a curl command. It sends a GET request to the /me endpoint with the API key in the header.

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

--------------------------------

### Run TokPortal MCP Server using npx

Source: https://developers.tokportal.com/mcp/mcp

This command executes the TokPortal MCP server using Node Package Execute (npx). No prior installation is needed as npx automatically downloads and runs the package, simplifying the setup process.

```bash
npx tokportal-mcp
```

--------------------------------

### Configure TikTok Video - cURL Example

Source: https://developers.tokportal.com/videos/configure-videos

This example demonstrates how to configure a single TikTok video using a cURL command. It includes setting the video type, description, publish date, video URL, TikTok sound URL, editing instructions, and an external reference.

```shell
curl -X PUT https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos/1 \
  -H "X-API-Key: tok_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "video_type": "video",
    "description": "Check out this new product! #ad #sponsored",
    "target_publish_date": "2026-03-15",
    "video_url": "https://pub-xxx.r2.dev/videos/bundle-id/promo.mp4",
    "tiktok_sound_url": "https://www.tiktok.com/music/trending-sound-789",
    "editing_instructions": "Add brand watermark in bottom-right corner",
    "external_ref": "campaign-42-v1"
  }'
```

--------------------------------

### List All Bundles (cURL Example)

Source: https://developers.tokportal.com/bundles/bundles

This example demonstrates how to retrieve a list of all bundles associated with your organization using a cURL command. It includes the necessary API endpoint and authentication header.

```curl
curl -X GET https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: tok_live_xxx"
```

--------------------------------

### Example: Configure Bundle Account with cURL

Source: https://developers.tokportal.com/account-config/account-configuration

An example using cURL to configure a bundle's account details, including username, visible name, biography, profile picture URL, and niche warming instructions. This demonstrates the API endpoint and request body structure.

```curl
curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/account \
  -H "X-API-Key: tok_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ \
    "username": "streetstyle.nyc", \
    "visible_name": "Street Style NYC", \
    "biography": "Daily street fashion from New York City.", \
    "profile_picture_url": "https://cdn.example.com/profiles/streetstyle.jpg", \
    "niche_warming_instructions": "Engage with fashion and streetwear content in NYC area." \
  }'
```

--------------------------------

### Example API Request with Pagination Parameters

Source: https://developers.tokportal.com/getting-started/rate-limits

This example demonstrates how to use the `page` and `per_page` query parameters to retrieve paginated data from the bundles endpoint.

```curl
curl -X GET "https://app.tokportal.com/api/ext/bundles?page=2&per_page=50" \
  -H "X-API-Key: tok_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

--------------------------------

### Configure TikTok Video - API Response Example

Source: https://developers.tokportal.com/videos/configure-videos

This is an example of a successful API response when configuring a TikTok video. It confirms the video configuration details, including its status and the provided metadata.

```JSON
{
  "data": {
    "position": 1,
    "video_type": "video",
    "status": "configured",
    "description": "Check out this new product! #ad #sponsored",
    "target_publish_date": "2026-03-15",
    "video_url": "https://pub-xxx.r2.dev/videos/bundle-id/promo.mp4",
    "tiktok_sound_url": "https://www.tiktok.com/music/trending-sound-789",
    "editing_instructions": "Add brand watermark in bottom-right corner",
    "external_ref": "campaign-42-v1"
  }
}
```

--------------------------------

### List All Videos in a Bundle (cURL)

Source: https://developers.tokportal.com/videos/videos

Example cURL command to list all videos within a bundle. This demonstrates how to make a GET request to the API endpoint, including the necessary bundle ID and API key for authentication. The response is a JSON object containing an array of video data.

```cURL
curl -X GET https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos \
  -H "X-API-Key: tok_live_xxx"
```

--------------------------------

### Batch Video Configuration Request Body Example

Source: https://developers.tokportal.com/videos/configure-videos

An example of the JSON request body for the batch video update endpoint. It includes an array of video objects, each specifying its position and type, along with other relevant metadata.

```JSON
{
  "videos": [
    { "position": 1, "video_type": "video", "..." : "..." },
    { "position": 2, "video_type": "carousel", "..." : "..." }
  ]
}
```

--------------------------------

### Get Bundle API Response Example

Source: https://developers.tokportal.com/bundles/bundles

An example JSON response when retrieving a single bundle by its ID. This response provides comprehensive details, including account information and video-related quantities if applicable.

```json
{
  "data": {
    "id": "bnd_abc123",
    "type": "account_and_videos",
    "platform": "tiktok",
    "country": "US",
    "status": "published",
    "options": {
      "niche_warming": true,
      "deep_warming": false,
      "moderation": false,
      "editing": false,
      "auto_finalize_videos": false
    },
    "videos_quantity": 3,
    "edits_quantity": 0,
    "account": {
      "username": "cooluser123",
      "visible_name": "Cool User",
      "biography": "Just vibes.",
      "profile_picture_url": "https://example.com/pic.jpg"
    },
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T12:00:00Z"
  }
}
```

--------------------------------

### Example API Request with Idempotency Key

Source: https://developers.tokportal.com/getting-started/rate-limits

This example shows how to use the `Idempotency-Key` header with a POST request to ensure that the operation is performed only once, even if the request is retried.

```curl
curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: tok_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: my-unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "tiktok", "country": "US", "videos": 10 }'
```

--------------------------------

### Install TokPortal Skill using ClawHub

Source: https://developers.tokportal.com/openclaw/openclaw

This command installs the TokPortal skill from ClawHub, making its functionalities available within the OpenClaw environment. No specific inputs are required beyond executing the command.

```bash
clawhub install tokportal
```

--------------------------------

### List Bundles API Response Example

Source: https://developers.tokportal.com/bundles/bundles

An example JSON response when listing all bundles. It includes key information for each bundle such as ID, type, platform, country, status, and configuration options.

```json
{
  "data": [
    {
      "id": "bnd_abc123",
      "type": "account_and_videos",
      "platform": "tiktok",
      "country": "US",
      "status": "published",
      "options": {
        "niche_warming": true,
        "deep_warming": false,
        "moderation": false,
        "editing": false,
        "auto_finalize_videos": false
      },
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T12:00:00Z"
    }
  ]
}
```

--------------------------------

### Upload and Configure Video

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

This endpoint group covers uploading a video file and configuring its details within a bundle. It involves getting an upload URL, uploading the file, and then setting video properties.

```APIDOC
## Video Upload and Configuration

### Description
This section details the process of uploading a video file and configuring its metadata for a specific bundle.

### 1. Get Presigned Upload URL

#### Method
POST

#### Endpoint
https://app.tokportal.com/api/ext/upload/video

#### Headers
- **X-API-Key** (string) - Required - Your TokPortal API key.
- **Content-Type** (string) - Required - application/json

#### Request Body
- **filename** (string) - Required - The name of the video file (e.g., "video1.mp4").
- **bundle_id** (string) - Required - The ID of the bundle to associate the video with.

#### Request Example
```json
{
  "filename": "video1.mp4",
  "bundle_id": "{bundle_id}"
}
```

#### Response (Success)
- **upload_url** (string) - The presigned URL to upload the video file to.

#### Response Example
```json
{
  "upload_url": "https://storage.tokportal.com/upload/...?"
}
```

### 2. Upload Video File

#### Method
PUT

#### Endpoint
{upload_url} (from the previous response)

#### Headers
- **Content-Type** (string) - Required - video/mp4

#### Request Body
- Binary data of the video file.

#### Request Example
```bash
curl -X PUT "{upload_url}" \
  -H "Content-Type: video/mp4" \
  --data-binary @video1.mp4
```

### 3. Configure Video Slot

#### Method
PUT

#### Endpoint
https://app.tokportal.com/api/ext/bundles/{bundle_id}/videos/{video_slot_number}

#### Parameters
##### Path Parameters
- **bundle_id** (string) - Required - The ID of the bundle.
- **video_slot_number** (integer) - Required - The sequential number of the video slot (e.g., 1 for the first video).

#### Headers
- **X-API-Key** (string) - Required - Your TokPortal API key.
- **Content-Type** (string) - Required - application/json

#### Request Body
- **video_type** (string) - Required - The type of video (e.g., "video").
- **description** (string) - Required - The caption or description for the video.
- **target_publish_date** (string) - Required - The desired publish date in YYYY-MM-DD format.
- **video_url** (string) - Required - The public URL of the uploaded video.

#### Request Example
```json
{
  "video_type": "video",
  "description": "Check out this trend! #fashion",
  "target_publish_date": "2026-03-01",
  "video_url": "{public_url}"
}
```

#### Response (Success)
- **message** (string) - Confirmation message indicating the video configuration was successful.

#### Response Example
```json
{
  "message": "Video slot configured successfully."
}
```
```

--------------------------------

### GET /api/ext/me

Source: https://developers.tokportal.com/getting-started/overview

Verify your API key and retrieve account information, including email, credit balance, plan, and creation date.

```APIDOC
## GET /api/ext/me

### Description
This endpoint allows you to verify your API key and retrieve your account information. It returns details such as your registered email, current credit balance, subscription plan, and the account creation timestamp.

### Method
GET

### Endpoint
https://app.tokportal.com/api/ext/me

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET https://app.tokportal.com/api/ext/me \
  -H "X-API-Key: tok_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the account information.
  - **email** (string) - The email address associated with the account.
  - **credits** (integer) - The current number of credits available.
  - **plan** (string) - The subscription plan level (e.g., "pro").
  - **created_at** (string) - The timestamp when the account was created (ISO 8601 format).

#### Response Example
```json
{
  "data": {
    "email": "you@example.com",
    "credits": 1250,
    "plan": "pro",
    "created_at": "2025-09-15T10:30:00Z"
  }
}
```

#### Error Response
See general error response format in the documentation.
```

--------------------------------

### Using Environment Variables for API Key

Source: https://developers.tokportal.com/getting-started/authentication

Provides examples of how to use environment variables to securely manage and utilize your TokPortal API key in shell commands.

```bash
export TOKPORTAL_API_KEY="tok_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
```

```bash
curl -X GET https://app.tokportal.com/api/ext/me \
  -H "X-API-Key: $TOKPORTAL_API_KEY"
```

--------------------------------

### Publish Bundle

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

Publish a configured bundle to go live. This initiates the process of making the content available on the target platform.

```APIDOC
## POST /api/ext/bundles/{bundle_id}/publish

### Description
Publishes a previously configured bundle, making its content live on the platform.

### Method
POST

### Endpoint
https://app.tokportal.com/api/ext/bundles/{bundle_id}/publish

### Parameters
#### Path Parameters
- **bundle_id** (string) - Required - The ID of the bundle to publish.

#### Headers
- **X-API-Key** (string) - Required - Your TokPortal API key.

### Request Example
```bash
curl -X POST https://app.tokportal.com/api/ext/bundles/{bundle_id}/publish \
  -H "X-API-Key: tok_live_your_key_here"
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the bundle has been published.

#### Response Example
```json
{
  "message": "Bundle published successfully."
}
```
```

--------------------------------

### Example: Configure Instagram Account with Link in Bio using cURL

Source: https://developers.tokportal.com/account-config/account-configuration

Demonstrates configuring an Instagram bundle account with a 'link_in_bio' using cURL. This example highlights the specific use case for Instagram and includes the required fields.

```curl
curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_d4e5f6/account \
  -H "X-API-Key: tok_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ \
    "username": "cafe.paris_", \
    "visible_name": "Caf\u00e9 Paris", \
    "biography": "Les meilleurs caf\u00e9s parisiens.", \
    "profile_picture_url": "https://cdn.example.com/profiles/cafeparis.jpg", \
    "link_in_bio": "https://cafeparis.example.com" \
  }'
```

--------------------------------

### Verify API Key

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

Verify your API key by making a request to the /api/ext/me endpoint. This confirms your key is valid and displays your account information and credit balance.

```APIDOC
## GET /api/ext/me

### Description
Verifies the provided API key and returns user profile and credit balance.

### Method
GET

### Endpoint
https://app.tokportal.com/api/ext/me

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your TokPortal API key.

### Request Example
```bash
curl https://app.tokportal.com/api/ext/me \
  -H "X-API-Key: tok_live_your_key_here"
```

### Response
#### Success Response (200)
- **user_id** (string) - The unique identifier for the user.
- **email** (string) - The email address associated with the account.
- **credits** (integer) - The remaining credits in the account.

#### Response Example
```json
{
  "user_id": "user_123",
  "email": "user@example.com",
  "credits": 100
}
```
```

--------------------------------

### Video Configuration with Uploaded URL

Source: https://developers.tokportal.com/media-upload/media-upload

Example JSON payload for configuring a video, using the 'public_url' obtained from a direct or presigned video upload.

```json
{
  "video_type": "video",
  "video_url": "https://pub-xxx.r2.dev/videos/org_xxx/bnd_a1b2c3d4/promo-1707660000.mp4",
  "description": "New product launch",
  "target_publish_date": "2026-03-15"
}
```

--------------------------------

### Create Bundle

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

Create a new bundle for TikTok content. This involves specifying the bundle type, platform, country, title, and the number of videos.

```APIDOC
## POST /api/ext/bundles

### Description
Creates a new bundle for managing TikTok content, including account and video slots.

### Method
POST

### Endpoint
https://app.tokportal.com/api/ext/bundles

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your TokPortal API key.
- **Content-Type** (string) - Required - application/json

#### Request Body
- **bundle_type** (string) - Required - The type of bundle (e.g., "account_and_videos").
- **platform** (string) - Required - The target platform (e.g., "tiktok").
- **country** (string) - Required - The target country (e.g., "USA").
- **title** (string) - Required - A descriptive title for the bundle.
- **videos_quantity** (integer) - Required - The number of video slots to include in the bundle.

### Request Example
```json
{
  "bundle_type": "account_and_videos",
  "platform": "tiktok",
  "country": "USA",
  "title": "My First Bundle",
  "videos_quantity": 5
}
```

### Response
#### Success Response (200)
- **bundle_id** (string) - The unique identifier for the created bundle.
- **status** (string) - The current status of the bundle.

#### Response Example
```json
{
  "bundle_id": "bundle_abc",
  "status": "created"
}
```
```

--------------------------------

### Get a Single Video (cURL)

Source: https://developers.tokportal.com/videos/videos

Example cURL command to retrieve a single video by its position within a bundle. This shows how to construct the request with the bundle ID and video position, along with the API key. The response provides detailed information about the specified video.

```cURL
curl -X GET https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos/1 \
  -H "X-API-Key: tok_live_xxx"
```

--------------------------------

### Upload and Configure TikTok Video using cURL

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

This sequence of cURL commands handles video configuration for a TokPortal bundle. It includes getting a presigned URL for upload, uploading the video file, and then configuring the video slot with details like description and publish date. Requires bundle_id and upload_url.

```shell
# Get a presigned upload URL
curl -X POST https://app.tokportal.com/api/ext/upload/video \
  -H "X-API-Key: tok_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"filename": "video1.mp4", "bundle_id": "{bundle_id}"}'

# Upload the file (use the upload_url from the response)
curl -X PUT "{upload_url}" \
  -H "Content-Type: video/mp4" \
  --data-binary @video1.mp4

# Configure the video slot
curl -X PUT https://app.tokportal.com/api/ext/bundles/{bundle_id}/videos/1 \
  -H "X-API-Key: tok_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ \
    "video_type": "video", \
    "description": "Check out this trend! #fashion", \
    "target_publish_date": "2026-03-01", \
    "video_url": "{public_url}"' \
}
```

--------------------------------

### Retrieve Verification Code (cURL Example)

Source: https://developers.tokportal.com/accounts/saved-accounts

Example of how to call the TokPortal API to retrieve a verification code using cURL. This includes the endpoint URL and the necessary API key header.

```cURL
curl -X POST https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/verification-code \
  -H "X-API-Key: tok_live_xxx"
```

--------------------------------

### Batch Video Configuration Response - With Errors

Source: https://developers.tokportal.com/videos/configure-videos

This JSON response illustrates a scenario where some videos in a batch configuration request fail validation. It includes the number of successfully configured videos, a detailed 'errors' array listing the specific validation failures (e.g., missing required fields), and the results for the videos that passed.

```json
{
  "data": {
    "bundle_id": "bundle_abc123",
    "configured": 2,
    "errors": [
      {
        "position": 3,
        "error": "carousel_images is required when video_type is carousel"
      }
    ],
    "results": [
      {
        "position": 1,
        "video_type": "video",
        "status": "configured"
      },
      {
        "position": 2,
        "video_type": "video",
        "status": "configured"
      }
    ]
  }
}
```

--------------------------------

### Create Bundle Request - cURL

Source: https://developers.tokportal.com/bundles/create-bundle

Example of creating a bundle for both account and videos with niche warming enabled using cURL. This demonstrates the required and optional parameters for a typical bundle creation request.

```curl
curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: tok_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ \
    "bundle_type": "account_and_videos", \
    "platform": "tiktok", \
    "country": "US", \
    "videos_quantity": 5, \
    "edits_quantity": 2, \
    "wants_niche_warming": true, \
    "niche_warming_instructions": "Focus on fitness and gym content. Follow fitness influencers, like workout videos.", \
    "auto_finalize_videos": true, \
    "external_ref": "campaign-42" \
  }'
```

--------------------------------

### Get Video Analytics using cURL

Source: https://developers.tokportal.com/analytics/analytics

This snippet demonstrates how to retrieve per-video performance metrics for an account using the TokPortal API. It utilizes a GET request with query parameters for sorting and pagination. The response includes detailed analytics for each video and pagination information.

```cURL
curl -X GET "https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/videos?sort_by=views&sort_order=desc&page=1&per_page=10" \
  -H "X-API-Key: tok_live_xxx"
```

--------------------------------

### POST /api/ext/bundles/bulk

Source: https://developers.tokportal.com/bundles/create-bulk

Creates multiple bundles across different platforms in a single request. This endpoint allows for bulk creation of accounts and associated videos with various customization options.

```APIDOC
## POST /api/ext/bundles/bulk

### Description
Creates multiple bundles across different platforms in a single request. This endpoint allows for bulk creation of accounts and associated videos with various customization options.

### Method
POST

### Endpoint
https://app.tokportal.com/api/ext/bundles/bulk

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your API key for authentication.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **accounts_count** (integer) - Required - The total number of accounts to create.
- **upload_accounts_count** (integer) - Required - The number of accounts for which videos will be uploaded.
- **platforms** (array of strings) - Required - A list of platforms to create bundles for (e.g., `["tiktok", "instagram"]`).
- **country** (string) - Required - The country code for the bundles (e.g., `"US"`).
- **videos_quantity** (integer) - Optional - The number of videos to create per account (if applicable).
- **edits_quantity** (integer) - Optional - The number of edits to perform per video (if applicable).
- **options** (object) - Optional - Configuration options for the bundles.
  - **niche_warming** (boolean) - Optional - Enables niche warming.
  - **moderation** (boolean) - Optional - Enables content moderation.
  - **editing** (boolean) - Optional - Enables video editing.
  - **deep_warming** (boolean) - Optional - Enables deep warming (only available for Instagram).
- **metadata** (object) - Optional - Additional metadata for the bundles.
  - **campaign** (string) - Optional - The campaign name.

### Request Example
```json
{
  "accounts_count": 5,
  "upload_accounts_count": 2,
  "platforms": ["tiktok", "instagram"],
  "country": "US",
  "videos_quantity": 3,
  "edits_quantity": 1,
  "options": {
    "niche_warming": true,
    "moderation": true,
    "editing": true
  },
  "metadata": {
    "campaign": "q1_2026_launch"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the created bundles and total count.
  - **bundles** (array of objects) - List of created bundles.
    - **id** (string) - Unique identifier for the bundle.
    - **type** (string) - Type of bundle (e.g., `account_and_videos`, `account_only`).
    - **platform** (string) - The platform for the bundle.
    - **country** (string) - The country for the bundle.
    - **status** (string) - The current status of the bundle (e.g., `pending_setup`).
    - **videos_quantity** (integer) - Number of videos created (if applicable).
    - **edits_quantity** (integer) - Number of edits performed (if applicable).
    - **options** (object) - Configuration options used for the bundle.
    - **metadata** (object) - Metadata associated with the bundle.
  - **total_count** (integer) - The total number of bundles created.
- **credits_charged** (integer) - The number of credits charged for the operation.
- **credits_remaining** (integer) - The number of credits remaining after the operation.
- **cost_breakdown** (object) - A breakdown of the credits charged.
  - **accounts** (integer) - Cost for creating accounts.
  - **videos** (integer) - Cost for creating videos.
  - **edits** (integer) - Cost for edits.
  - **niche_warming** (integer) - Cost for niche warming.
  - **deep_warming** (integer) - Cost for deep warming.
  - **moderation** (integer) - Cost for moderation.

#### Response Example
```json
{
  "data": {
    "bundles": [
      {
        "id": "bnd_bulk_001",
        "type": "account_and_videos",
        "platform": "tiktok",
        "country": "US",
        "status": "pending_setup",
        "videos_quantity": 3,
        "edits_quantity": 1,
        "options": {
          "niche_warming": true,
          "deep_warming": false,
          "moderation": true,
          "editing": true,
          "auto_finalize_videos": false
        },
        "metadata": { "campaign": "q1_2026_launch" }
      }
    ],
    "total_count": 10
  },
  "credits_charged": 550,
  "credits_remaining": 9450,
  "cost_breakdown": {
    "accounts": 100,
    "videos": 240,
    "edits": 40,
    "niche_warming": 100,
    "deep_warming": 0,
    "moderation": 70
  }
}
```

### Error Responses
- **400 `upload_exceeds_accounts`**: `upload_accounts_count` exceeds `accounts_count`.
- **400 `edits_exceed_videos`**: `edits_quantity` exceeds `videos_quantity`.
- **400 `country_not_enabled`**: Country is not enabled for your organization.
- **400 `warming_conflict`**: `niche_warming` and `deep_warming` cannot both be enabled.
- **400 `deep_warming_instagram_only`**: `deep_warming` requires Instagram in the platforms list.
- **402 `insufficient_credits`**: Not enough credits for the full bulk operation.
```

--------------------------------

### Create Videos-Only Bundle (cURL)

Source: https://developers.tokportal.com/bundles/create-bundle

This cURL command illustrates the creation of a 'videos_only' bundle for an existing account. It includes the number of videos required, moderation options, and an external reference. Note the recommendation to use add-video-slots for better continuity.

```cURL
curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: tok_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_type": "videos_only",
    "account_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
    "videos_quantity": 3,
    "wants_moderation": true,
    "moderation_notice": "Ensure no competitor logos are visible",
    "external_ref": "restock-wave-2"
  }'
```

--------------------------------

### Get Account

Source: https://developers.tokportal.com/account-config/account-configuration

Retrieves the current account configuration for a specified bundle.

```APIDOC
## GET /bundles/:id/account

### Description
Retrieve the current account configuration for a bundle.

### Method
GET

### Endpoint
`/bundles/:id/account`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the bundle.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET https://app.tokportal.com/api/ext/bundles/bnd_abc123/account \
  -H "X-API-Key: tok_live_xxx"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the account configuration details.
  - **username** (string) - The account username.
  - **visible_name** (string) - The display name.
  - **biography** (string) - The account biography.
  - **profile_picture_url** (string) - The URL of the profile picture.
  - **link_in_bio** (string | null) - The link in bio, if provided.
  - **niche_warming_instructions** (string | null) - Niche warming instructions, if provided.
  - **configured_at** (string) - Timestamp when the account was configured.
  - **status** (string) - The current status of the bundle.

#### Response Example
```json
{
  "data": {
    "username": "streetstyle.nyc",
    "visible_name": "Street Style NYC",
    "biography": "Daily street fashion from New York City.",
    "profile_picture_url": "https://cdn.example.com/profiles/streetstyle.jpg",
    "link_in_bio": null,
    "niche_warming_instructions": "Engage with fashion and streetwear content in NYC area.",
    "configured_at": "2026-02-10T10:00:00Z",
    "status": "configured"
  }
}
```
```

--------------------------------

### PUT /api/ext/bundles/{bundle_id}/videos/batch

Source: https://developers.tokportal.com/videos/configure-videos

Configures multiple videos within a specified bundle in a single request. The request body must be a JSON object containing a 'videos' array.

```APIDOC
## PUT /api/ext/bundles/{bundle_id}/videos/batch

### Description
Configures multiple videos in a single request. The body must be wrapped in `{ "videos": [...] }`.

### Method
PUT

### Endpoint
`/api/ext/bundles/{bundle_id}/videos/batch`

### Parameters
#### Path Parameters
- **bundle_id** (string) - Required - The ID of the bundle to which the videos belong.

#### Query Parameters
None

#### Request Body
- **videos** (array) - Required - An array of video objects to configure.
  - **position** (integer) - Required - The position of the video within the bundle.
  - **video_type** (string) - Required - The type of content (e.g., 'video', 'carousel').
  - **description** (string) - Optional - A description for the video, can include hashtags.
  - **target_publish_date** (string) - Required - The target date for publishing the video in 'YYYY-MM-DD' format.
  - **video_url** (string) - Required if `video_type` is 'video' - The public URL of the video file.
  - **carousel_images** (array) - Required if `video_type` is 'carousel' - An array of image paths for the carousel.
  - **tiktok_sound_url** (string) - Optional - A URL for a TikTok sound to be associated with the video.

### Request Example
```json
{
  "videos": [
    {
      "position": 1,
      "video_type": "video",
      "description": "Day 1 of the challenge #ad",
      "target_publish_date": "2026-03-15",
      "video_url": "https://pub-xxx.r2.dev/videos/bundle-id/day1.mp4"
    },
    {
      "position": 2,
      "video_type": "video",
      "description": "Day 2 — things are getting interesting #ad",
      "target_publish_date": "2026-03-18",
      "video_url": "https://pub-xxx.r2.dev/videos/bundle-id/day2.mp4",
      "tiktok_sound_url": "https://www.tiktok.com/music/hype-beat-101"
    },
    {
      "position": 3,
      "video_type": "carousel",
      "description": "Final results — swipe to see the transformation",
      "target_publish_date": "2026-03-21",
      "carousel_images": [
        "carousel-images/org_xxx/bundle_abc123/before.jpg",
        "carousel-images/org_xxx/bundle_abc123/after.jpg"
      ],
      "tiktok_sound_url": "https://www.tiktok.com/music/reveal-sound-202"
    }
  ]
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the results of the batch configuration.
  - **bundle_id** (string) - The ID of the bundle.
  - **configured** (integer) - The number of videos successfully configured.
  - **errors** (array) - An array of errors encountered during configuration.
  - **results** (array) - An array of objects detailing the status of each configured video.

#### Response Example
```json
{
  "data": {
    "bundle_id": "bundle_abc123",
    "configured": 3,
    "errors": [],
    "results": [
      {
        "position": 1,
        "video_type": "video",
        "status": "configured"
      },
      {
        "position": 2,
        "video_type": "video",
        "status": "configured"
      },
      {
        "position": 3,
        "video_type": "carousel",
        "status": "configured"
      }
    ]
  }
}
```

#### Error Response Example (Partial Configuration)
```json
{
  "data": {
    "bundle_id": "bundle_abc123",
    "configured": 2,
    "errors": [
      {
        "position": 3,
        "error": "carousel_images is required when video_type is carousel"
      }
    ],
    "results": [
      {
        "position": 1,
        "video_type": "video",
        "status": "configured"
      },
      {
        "position": 2,
        "video_type": "video",
        "status": "configured"
      }
    ]
  }
}
```

#### Error Response Example (Validation Error)
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "target_publish_date must be at least 3 days from today for new accounts.",
    "details": {
      "field": "target_publish_date",
      "minimum_date": "2026-02-14"
    }
  }
}
```
```

--------------------------------

### Get Account Details

Source: https://developers.tokportal.com/accounts/saved-accounts

Retrieves the full details of a specific account, including its credentials.

```APIDOC
## GET /accounts/:id

### Description
Returns full account details including credentials.

### Method
GET

### Endpoint
/accounts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the account.

### Request Example
```bash
curl -X GET https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c \
  -H "X-API-Key: tok_live_xxx"
```

### Response
#### Success Response (200)
- **data** (object) - The account details.
  - **id** (string) - Unique account identifier.
  - **platform** (string) - `tiktok` or `instagram`.
  - **username** (string) - Platform username.
  - **visible_name** (string) - Display name on the platform.
  - **biography** (string) - Account bio text.
  - **profile_picture_url** (string | null) - URL to the profile picture.
  - **country** (string) - ISO 3166-1 alpha-2 country code.
  - **link_in_bio** (string | null) - Link in bio URL.
  - **profile_url** (string) - Direct URL to the social media profile.
  - **tokmail_email** (string) - TokMail email address for this account.
  - **created_at** (string) - ISO 8601 creation timestamp.
  - **updated_at** (string) - ISO 8601 last-updated timestamp.
  - **credentials** (object) - Account login credentials.
    - **tokmail_email** (string) - TokMail email.
    - **password** (string) - TokMail password.
    - **social_credentials** (object) - Social media platform credentials.
      - **email** (string) - Social media email.
      - **password** (string) - Social media password.
  - **last_verification_code** (string) - The last verification code received for the account.
  - **current_cm_id** (string) - The current campaign manager ID associated with the account.

#### Response Example
```json
{
  "data": {
    "id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
    "platform": "tiktok",
    "username": "coolcreator99",
    "visible_name": "Cool Creator",
    "biography": "Lifestyle & trends | DM for collabs",
    "profile_picture_url": "https://pub-xxx.r2.dev/profile-pictures/pfp-abc123.jpg",
    "country": "US",
    "link_in_bio": "https://linktr.ee/coolcreator99",
    "profile_url": "https://www.tiktok.com/@coolcreator99",
    "tokmail_email": "coolcreator99@tokmail.io",
    "created_at": "2026-01-10T08:00:00Z",
    "updated_at": "2026-02-05T12:30:00Z",
    "credentials": {
      "tokmail_email": "coolcreator99@tokmail.io",
      "password": "xK9#mP2$vL7nQ4w",
      "social_credentials": {
        "email": "coolcreator99@tokmail.io",
        "password": "Tr3nd!Set_42x"
      }
    },
    "last_verification_code": "482937",
    "current_cm_id": "cm_abc123"
  }
}
```
```

--------------------------------

### POST /api/ext/bundles (Videos Only)

Source: https://developers.tokportal.com/bundles/create-bundle

Creates a 'videos_only' bundle for an existing account. This endpoint is recommended to be used with the add-video-slots endpoint for better continuity.

```APIDOC
## POST /api/ext/bundles (Videos Only)

### Description
Creates a 'videos_only' bundle for an existing account. This endpoint is recommended to be used with the add-video-slots endpoint for better continuity, as it preserves the same account manager.

### Method
POST

### Endpoint
https://app.tokportal.com/api/ext/bundles

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your API key for authentication.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **bundle_type** (string) - Required - Must be `"videos_only"`.
- **account_id** (string) - Required - The ID of the existing account.
- **videos_quantity** (integer) - Required - The number of videos to include in the bundle.
- **wants_moderation** (boolean) - Optional - Whether to enable content moderation.
- **moderation_notice** (string) - Optional - Specific instructions for moderation if `wants_moderation` is true.
- **external_ref** (string) - Optional - An external reference ID for tracking.

*Note: `platform` and `country` are derived from the saved account when using `videos_only`.*

### Request Example
```json
{
  "bundle_type": "videos_only",
  "account_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
  "videos_quantity": 3,
  "wants_moderation": true,
  "moderation_notice": "Ensure no competitor logos are visible",
  "external_ref": "restock-wave-2"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains details about the created bundle.
  - **bundle_id** (string) - The unique identifier for the bundle.
  - **bundle_type** (string) - The type of bundle created.
  - **platform** (string) - The social media platform.
  - **country** (string) - The country code.
  - **status** (string) - The current status of the bundle setup.
  - **videos_quantity** (integer) - Number of videos included.
  - **edits_quantity** (integer) - Number of edits included.
  - **external_ref** (string|null) - External reference ID.
  - **created_at** (string) - Timestamp of creation.
- **credits_charged** (integer) - The number of credits charged for this operation.
- **credits_remaining** (integer) - The number of credits remaining after the charge.
- **cost_breakdown** (object) - Breakdown of the costs.
  - **account** (integer) - Cost for the account setup.
  - **videos** (integer) - Cost for videos.
  - **edits** (integer) - Cost for edits.
  - **niche_warming** (integer) - Cost for niche warming.
  - **deep_warming** (integer) - Cost for deep warming.
  - **moderation** (integer) - Cost for moderation.

#### Response Example
```json
{
  "data": {
    "bundle_id": "bnd_i9j0k1l2",
    "bundle_type": "videos_only",
    "platform": "tiktok",
    "country": "US",
    "status": "pending_setup",
    "videos_quantity": 3,
    "edits_quantity": 0,
    "external_ref": "restock-wave-2",
    "created_at": "2026-02-10T09:10:00Z"
  },
  "credits_charged": 35,
  "credits_remaining": 355,
  "cost_breakdown": {
    "account": 0,
    "videos": 30,
    "edits": 0,
    "niche_warming": 0,
    "deep_warming": 0,
    "moderation": 5
  }
}
```
```

--------------------------------

### Success Response Example

Source: https://developers.tokportal.com/getting-started/authentication

Shows the JSON structure of a successful response from the TokPortal API after an authenticated request.

```json
{
  "data": {
    "email": "you@example.com",
    "credits": 1250
  }
}
```