### Start Debugging Session

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Dramas/Debug Your Mini Drama.md

Navigate to your project root in the terminal and run the 'minis dev' command to start the local development server.

```bash
cd path/to/your/project/
minis dev
```

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

### Clone Repository and Run Scripts

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/README.md

Quick start guide to clone the repository and execute the Python scripts to download TikTok API documentation. Requires Python 3.8+ and has no external dependencies.

```bash
git clone https://github.com/your-username/tiktok-docs-mcp
cd tiktok-docs-mcp

# TikTok Platform API (developers.tiktok.com)
python scripts/developers_tiktok_com.py

# TikTok Shop Partner API (partner.tiktokshop.com)
python scripts/partner_tiktokshop_com.py
```

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

### Navigate to Game Directory

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Games/Debug Your Mini Game.md

Use this command to enter your game project's directory before starting the debugging session.

```bash
cd path/to/your-game-project
```

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

### Start Debugging Environment

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Games/Debug Your Mini Game.md

Run this command to initiate the debugging environment. Your app's client key will be requested once and stored for future sessions.

```bash
ttmg dev
```

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

### Advertiser Query Response Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Commercial Content API/API Reference/Query Advertisers.md

This is an example of a successful response when querying for advertisers. It includes a list of advertisers with their business ID, name, and country code.

```json
{
   "data": {
      "advertisers": [
         {
            "business_id": 1755645247067185,
            "business_name": "Awesome Food Co.",
            "country_code": "US"        
         },
         {
            "business_id": 183746395837294,
            "business_name": "Awesome Drink Co.",
            "country_code": "CA"        
         }
      ]
   },
   "error": {
      "code": "ok",
      "http_status_code": 200,
      "log_id": "202207280326050102231031430C7E754E",
      "message": ""
   }
}
```

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

### Commercial Content Query Response Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Commercial Content API/API Reference/Query Commercial Content.md

This is an example of a successful response when querying commercial content. It includes a list of commercial contents, pagination information (has_more), and a search_id for resuming searches.

```json
{
   "data": {
      "commercial_contents": [
         {
            "brand_names": [
               "My Awesome Co.",
               "HelloWorld Inc."
            ],
            "create_date": "20230109",
            "create_timestamp": 1696875852,
            "creator": {
               "username": "joe1234567"
            },
            "id": "v09044g40000ce6enu3c77u36l73sp20",
            "label": "Paid partnership",
            "videos": [
               {
                  "cover_image_url": "https://asdfcdn.com/17392712.jpeg?x-expires=1679169600\u0026x-signature=asdf",
                  "url":"https://www.tiktok.com/@joe1234567/video/19384729204821234" 
               }
            ]
         }
      ],
      "has_more": "true",
      "search_id": "2837438294054038"
   },
   "error": {
      "code": "ok",
      "http_status_code": 200,
      "log_id": "202207280326050102231031430C7E754E",
      "message": ""
   }
}
```

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

### Rewarded Ad Setup

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Games/Capability Guides/In-App Ads.md

This snippet demonstrates how to create a rewarded video ad instance, set up error and close event listeners, and display the ad. Each instance can only be shown once.

```APIDOC
## Rewarded Ad Setup

### Description
This section details the process of setting up rewarded ads, which grant users in-game rewards after watching an ad. It involves obtaining a Placement ID, creating an ad instance using the SDK, and handling ad events.

### Method
`TTMinis.game.createRewardedVideoAd`

### Parameters
#### Request Body
- **adUnitId** (string) - Required - The placement ID obtained from the TikTok Ads Manager.

### Request Example
```javascript
const rewardedVideoAd = TTMinis.game.createRewardedVideoAd({
  adUnitId: 'xxx'
});
```

### Event Listeners
#### `onError`
- **Description**: Callback function that is triggered when an error occurs during ad video playback or material fetching.
- **Example**:
  ```javascript
  rewardedVideoAd.onError(() => {
    console.log('ad display error');
  });
  ```

#### `onClose`
- **Description**: Callback function that is triggered when the ad video is closed, either by the user or automatically due to an error.
- **Example**:
  ```javascript
  rewardedVideoAd.onClose(() => {
    console.log('ad closed');
  });
  ```

### Displaying the Ad
#### Method
`rewardedVideoAd.show()`

### Response
#### Success Response (Promise resolves)
- **Description**: Indicates that the ad has been successfully displayed.

#### Failure Response (Promise rejects)
- **Description**: Indicates that the ad failed to display.

### Request Example
```javascript
rewardedVideoAd.show().then(() => {
  console.log('ad displayed');
}).catch(() => {
  console.log('ad failed to display');
});
```

**Note**: Each instance of a rewarded video ad can only be shown once. After displaying, the instance is released, and a new instance must be created for subsequent ad displays.
```

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

### Access Token Response Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/TikTok GO/Obtain Access Token for APIs.md

This is an example of the JSON response you will receive upon successfully obtaining an access token. It includes the access token itself, its expiration time, and the refresh token with its expiration.

```json
{
    "access_token": "xxx",
    "expires_in": 1749368707,
    "refresh_expires_in": 1906616707,
    "refresh_token": "xxx"
}
```

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

### Embed URL with Customization Parameters

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Embed/Embed.md

Example of an embed URL with parameters to display music information and the description. Customize the player by appending query parameters.

```html
https://www.tiktok.com/player/v1/6718335390845095173?music_info=1&description=1
```

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

### Get Ad Details Request Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Commercial Content API/API Reference/Get Ad Details.md

This cURL command demonstrates how to request detailed information for a specific ad ID, specifying the desired fields in the query parameters and providing the ad ID in the request body.

```curl
curl -L -X POST 'https://open.tiktokapis.com/v2/research/adlib/ad/detail/?fields=ad.id,ad.first_shown_date,ad.last_shown_date' \
-H 'Authorization: Bearer clt.example12345Example12345Example' \
-H 'Content-Type: application/json' \
--data-raw '{ \
   "ad_id": 104836593772645 \
}'
```

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

### Configure package.json Scripts

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Dramas/Debug Your Mini Drama.md

Ensure your package.json includes 'dev' or 'start' scripts for the debugging tool to launch your TikTok Minis application.

```json
{
  "scripts": {
    "dev": "..." // or "start"
  }
}
```

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

### User Info Response Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Research Tools/API Reference/Query User Info.md

This JSON object shows a successful response from the Query User Info endpoint, containing various details about the requested user.

```json
{
    "data": {
        "bio_description": "my_bio",
        "is_verified": false,
        "likes_count": 27155089,
        "video_count": 44,
        "avatar_url": "https://some_cdn.com/my_avatar",
        "follower_count": 232,
        "following_count": 45,
        "display_name": "my nick name"
    },
    "error": {
        "code": "ok",
        "message": "",
        "log_id": "202207280326050102231031430C7E754E"
    }
}
```

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

### Query User Info Request Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Research Tools/API Reference/Query User Info.md

This cURL command demonstrates how to request user information, specifying the desired fields in the query parameters and providing the username in the JSON body.

```curl
curl -L 'https://open.tiktokapis.com/v2/research/user/info/?fields=display_name,bio_description,avatar_url,is_verified,follower_count,following_count,likes_count,video_count' \
-H 'Authorization: Bearer clt.example12345Example12345Example' \
-H 'Content-Type:application/json' \
-d '{"username": "joe123456"}'
```

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

### Data Request Status Response Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Data Portability API/API Reference/Check Status of Data Request.md

This is an example of a successful response when checking the status of a data request. It includes details such as the request ID, application time, collection time, current status, data format, and the categories selected for the data request.

```json
{
    "data": {
        "apply_time": 1703186989,
        "category_selection_list": [
            "profile",
            "video",
            "direct_messages"
        ],
        "collect_time": 1703187862,
        "data_format": "text",
        "request_id": 123451234512345,
        "status": "downloading"
    },
    "error": {
        "code": "ok",
        "message": "",
        "log_id": "2023242526272829300000000000001111"
    }
}
```

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

### Review Info Response Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Research Tools/API Reference/Query TikTok Shop Reviews.md

This is an example of a successful response from the TikTok Shop Reviews API. It includes a 'data' object containing an array of 'review_data', where each item represents a product review with its associated details.

```json
{
    "data": {
        "review_data": [
            {
                "create_time": 1722879716021,
                "product_name": "Test Product Name",
                "review_like_count": 1,
                "review_rating": "FIVE",
                "review_text": " test Text"
            }
        ]
    }
}
```

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

### Query Playlist Info Request Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Research Tools/API Reference/Query Playlist Info.md

Use this cURL command to send a POST request to the API to retrieve playlist information. Ensure you include the necessary Authorization header and Content-Type.

```curl
curl --location 'https://open.tiktokapis.com/v2/research/playlist/info/?fields=playlist_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer abcdefghijklmn' \
--data '{ 
   "playlist_id": 12345677654321, 
    "max_count":100, 
    "cursor":0 
}'
```

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

### Initiate Payment with Mini Games SDK

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Games/Capability Guides/In-App Purchases.md

Call the `TTMinis.game.pay` endpoint from the Mini Games SDK to start the payment process after creating an order. Implement success, fail, and complete callbacks to handle the payment outcome.

```javascript
TTMinis.game.pay({
  trade_order_id: "{your_trade_order_id}",
  success: () => {
  // Do something if succeeded
  },
  fail: (error) => {
  // Do something if failed
  },
  complete: () => {
  // Do something if completed
  }
})
```

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

### Get Access Token

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/TikTok GO/Obtain Access Token for APIs.md

Use this endpoint to obtain an access token bundle for the first time after merchant approval for specific scopes.

```APIDOC
## POST https://open.tiktokapis.com/merchant/oauth/token/

### Description
Obtain an access token bundle after merchant approval for specific scopes.

### Method
POST

### Endpoint
https://open.tiktokapis.com/merchant/oauth/token/

### Headers
- Content-Type: application/x-www-form-urlencoded
- x-tt-target-idc: alisg

### Request Body
- **client_key** (string) - Required - Unique identification key provisioned to the partner
- **client_secret** (string) - Required - Unique identification secret provisioned to the partner
- **merchant_id** (string) - Required - Unique identification of merchant that partner applied for
- **grant_type** (string) - Required - Action type such as `access_token` to retrieve access token

### Request Example
```curl
curl --location 'https://open.tiktokapis.com/merchant/oauth/token/' \
--header 'x-tt-target-idc: alisg' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_key=xxxxxxx' \
--data-urlencode 'client_secret=xxxxxxxx' \
--data-urlencode 'grant_type=access_token' \
--data-urlencode 'merchant_id=xxxxxx'
```

### Response
#### Success Response (200)
- **access_token** (string) - Access token used for API call self identification
- **expires_in** (int64) - Unix timestamp indicating when the access token expires
- **refresh_token** (string) - Refresh token used to request a new access token when the current one expires
- **refresh_expires_in** (int64) - Unix timestamp indicating when the refresh token expires

#### Response Example
```json
{
    "access_token": "xxx",
    "expires_in": 1749368707,
    "refresh_expires_in": 1906616707,
    "refresh_token": "xxx"
}
```
```

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

### Interstitial Ad Setup

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Games/Capability Guides/In-App Ads.md

This section refers to the general process for setting up interstitial ads, indicating that it follows the same procedure as rewarded ads but utilizes the interstitial ad JavaScript APIs.

```APIDOC
## Interstitial Ad Setup

### Description
To set up interstitial ads for your mini games, follow the same process as described for rewarded ads, but use the interstitial ad JavaScript APIs instead. Refer to the provided link for specific API details.

### Reference
[See the full list of JavaScript APIs for IAA](https://developers.tiktok.com/doc/mini-games-sdk-iaa#interstitial-ads)
```

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

### Query Creator Info

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Content Posting API/Content Posting API.md

To initiate a direct post to a creator's account, you must first use the Query Creator Info endpoint to get the target creator's latest information.

```APIDOC
## POST /v2/post/publish/creator_info/query/

### Description
Retrieves the latest information for a target creator account, which is necessary to initiate a direct post.

### Method
POST

### Endpoint
https://open.tiktokapis.com/v2/post/publish/creator_info/query/

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - application/json; charset=UTF-8

### Request Example
```json
{
  "example": "curl --location --request POST 'https://open.tiktokapis.com/v2/post/publish/creator_info/query/\n--header 'Authorization: Bearer act.example12345Example12345Example' \n--header 'Content-Type: application/json; charset=UTF-8'"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains creator information.
  - **creator_avatar_url** (string) - URL of the creator's avatar.
  - **creator_username** (string) - The creator's username.
  - **creator_nickname** (string) - The creator's nickname.
  - **privacy_level_options** (array) - Available privacy settings for posts.
  - **comment_disabled** (boolean) - Indicates if comments are disabled.
  - **duet_disabled** (boolean) - Indicates if duets are disabled.
  - **stitch_disabled** (boolean) - Indicates if stitches are disabled.
  - **max_video_post_duration_sec** (integer) - Maximum allowed video duration in seconds.
- **error** (object) - Contains error details.
  - **code** (string) - Error code.
  - **message** (string) - Error message.
  - **log_id** (string) - Unique log ID for the request.

#### Response Example
```json
{
   "data":{
      "creator_avatar_url": "https://lf16-tt4d.tiktokcdn.com/obj/tiktok-open-platform/8d5740ac3844be417beeacd0df75aef1",
      "creator_username": "tiktok",
      "creator_nickname": "TikTok Official",
      "privacy_level_options": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY"]
      "comment_disabled": false,
      "duet_disabled": false,
      "stitch_disabled": true,
      "max_video_post_duration_sec": 300
   },
    "error": {
         "code": "ok",
         "message": "",
         "log_id": "202210112248442CB9319E1FB30C1073F3"
     }
}
```
```

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

### Query User Followers Request Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Research Tools/API Reference/Query User Followers.md

This cURL command demonstrates how to make a POST request to the Query User Followers API. Ensure you replace placeholders with your actual access token and desired parameters.

```curl
curl --location 'https://platform.tiktokapis.com/v2/research/user/followers/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer clt.test123test123test123' \
--data '{
    "username": "test_user",
    "max_count":3,
    "cursor": 12347764
}'
```

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

### Get Ad Details Response Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Commercial Content API/API Reference/Get Ad Details.md

This JSON object represents a successful response from the Get Ad Details API, containing detailed information about the ad, its ad group targeting, and the advertiser.

```json
{
   "data": {
      "ad": {
         "first_shown_date": 20210101,
         "id": 1923845247192304,
         "image_urls": [
            "https://asdfcdn.com/17392712.jpeg?x-expires=1679169600\u0026x-signature=asdf"
         ],
         "last_shown_date": 20210101,
         "status": "active",
         "videos": [
            {"url": "https://asdfcdn.com/..../127364jmdfjsa93d8cn30dm2di/?mime_type=video_mp4"},
            {"url": "https://asdfcdn.com/..../1kmeidhfb38u21nd82hsk389fd/?mime_type=video_mp4"}
         ],
         "reach": {
            "unique_users_seen": "30K",
            "unique_users_seen_by_country": {
               "GB": "18K",
               "IT": "12K"
            }
         },
         "rejection_info": {
             "affected_countries": ["FR", "IT"]
         }
      },
      "ad_group": {
         "target" {
            "number_of_users_targeted": "50K",
            "country": ["IT", "GB"],
            "age": {
               "13-17": false,
               "18-24": false,
               "25-34": false,
               "35-44": true,
               "35-44": true,
               "55+": true,
            },
            "gender": {
               "female": true,
               "male": true,
               "other_genders": true
            },
            "audience_targeting": "No",
            "video_interactions": "Entertainment",
            "creator_interactions": "Talent",
            "interest": "News & Entertainment, Business Services"
         }
      },
      "advertiser": {
          "business_id": 1755645247067185,
          "business_name": "Awesome Co.",
          "country_code": "US",
          "paid_by": "Awesome Co.",
          "tiktok_account": {
            "avatar_url": "https://asdf.tiktokcdn.com/1736254.jpeg?x-expires=1679169600\u0026x-signature=asdf",
            "follower_count": 26374,
            "profile_url": "https://www.tiktok.com/@awesome_co"
          }
      }
   },
   "error": {
      "code": "ok",
      "http_status_code": 200,
      "log_id": "202207280326050102231031430C7E754E",
      "message": ""
   }
}
```

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

### Get Ad Report Request Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Commercial Content API/API Reference/Get Ad Report.md

This cURL command demonstrates how to request an ad report, specifying the date range, country code, and advertiser business IDs.

```curl
curl -L -X POST 'https://open.tiktokapis.com/v2/research/adlib/ad/report/?fields=count_time_series_by_country' \
-H 'Authorization: Bearer clt.example12345Example12345Example' \
-H 'Content-Type: application/json' \
--data-raw '{
   "filters":{
       "ad_published_date_range": {
            "min": "20230102",
            "max": "20230109"
       },
       "country_code":"ALL",
       "advertiser_business_ids":[21836478203048,3484763562784]
   }
}'
```

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

### Ad Report Response Example

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Commercial Content API/API Reference/Get Ad Report.md

This JSON object shows a sample response from the Get Ad Report API, including the ad count time series by country and error details.

```json
{
   "data": {
      "count_time_series_by_country": {
          "IT": [{"date": "20210109", "count": 45}, {"date": "20210108", "count": 24}],
          "ES": [{"date": "20210109", "count": 48}, {"date": "20210108", "count": 22}],
          ...
    }
   },
   "error": {
      "code": "ok",
      "http_status_code": 200,
      "log_id": "202207280326050102231031430C7E754E",
      "message": ""
   }
}
```

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

### Initialize TikTok Minis SDK

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Dramas/Capability Guides/Capability Guides.md

Include this script in the head of your HTML to initialize the TikTok Minis SDK. Ensure your clientKey is correctly configured.

```html
<head>
  <script src="https://connect.tiktok-minis.com/drama/sdk.js"></script>
  <script>
    TTMinis.init({
      clientKey: 'your_client_key',
    });
  </script>
</head>
```

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

### Manually Configure minis.config.json

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Dramas/Debug Your Mini Drama.md

Create a 'minis.config.json' file in your project root and define your development and build environment settings, including port, host, output directory, and HTML entry point.

```json
{
  "dev": {
    "port": "3000",        // The port your local dev server uses
    "host": "localhost"    // Your local host (optional)
  },
  "build": {
    "outputDir": "dist",          // The output directory after building (e.g., dist, build)
    "htmlEntry": "public/index.html" // The relative path to your index.html
  }
}
```

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

### Initialize TikTok Minis SDK

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Dramas/Develop Your Mini Drama.md

Include this JavaScript code in your index.html to load the SDK asynchronously and initialize it with your project's client key.

```html
<head>
  <script src="https://connect.tiktok-minis.com/drama/sdk.js"></script>
  <script>
    TTMinis.init({
      clientKey: "your_client_key_here",
    });
  </script>
</head>
```

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

### Initialize TikTok Minis SDK

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Dramas/Debug Your Mini Drama.md

Integrate the TikTok Minis SDK in your entry HTML file and initialize it with your client key. Ensure the client key matches the one used for local debugging.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <script src="https://connect.tiktok-minis.com/drama/sdk.js"></script>
    <script>
      TTMinis.init({
        clientKey: "YOUR_CLIENT_KEY", // Replace with your actual client key
      });
    </script>
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>tiktok-minis-demo</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

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

### Generate minis.config.json via CLI

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Dramas/Debug Your Mini Drama.md

Use the 'minis init' command in your project root to automatically generate the configuration file for development and build environments.

```bash
cd path/to/your/project
minis init
```

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

### Get User Pinned Videos

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Research Tools/API Reference/Query User Pinned Videos.md

Retrieves a list of pinned videos for a specified TikTok user. Requires the 'research.data.basic' scope.

```APIDOC
## POST /v2/research/user/pinned_videos/

### Description
Retrieves a list of pinned videos for a specified TikTok user.

### Method
POST

### Endpoint
https://open.tiktokapis.com/v2/research/user/pinned_videos/

### Headers
- **Authorization** (string) - Required - The client access token obtained from /v2/oauth/token/.
- **Content-Type** (string) - Required - The original media type of the resource (application/json).

### Query Parameters
- **fields** (string) - Required - Field names for desired data to be returned. It is a comma-separated list. See Video Object for a full list of values.

### Request Body
- **username** (string) - Required - The username as the unique identifier.

### Request Example
```curl
curl --location 'https://open.tiktokapis.com/v2/research/user/pinned_videos/?fields=id,share_count,view_count,comment_count,like_count' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer clt.testtemp123test123test123' \
--data '{
    "username": "test_username"
    }'
```

### Response
#### Success Response (200)
- **data** (PinnedVideosData) - The returned pinned videos list.
- **error** (ErrorStructV2) - Error object.

### PinnedVideosData
- **pinned_videos_list** (list<Video>) - A list of video objects that match the query.

### Video Object
- **id** (int64) - The unique identifier of the TikTok video.
- **create_time** (int64) - UTC Unix epoch (in seconds) of when the TikTok video was posted.
- **username** (string) - The username as the unique identifier of the video creator.
- **region_code** (string) - A two digit code for the country where the video creator registered their account.
- **video_description** (string) - The description of the pinned video.
- **music_id** (int64) - The music ID used in the video.
- **like_count** (int64) - The number of likes the video has received.
- **comment_count** (int64) - The number of comments the video has received.
- **share_count** (int64) - The number of shares the video has received.
- **view_count** (int64) - The number of views the video has received.
- **hashtag_names** (list<string>) - The list of hashtags used in the video.
- **hashtag_info_list** (Struct) - "hashtag_id" and "hashtag_description". Returns all the unique hashtag_ids for each hashtag_name and a "hashtag_description" when one exists.
- **sticker_info_list** (Struct) - "sticker_id" and "sticker_name". Returns the interactive sticker details when available for a video.
- **effect_info_list** (Struct) - "effect_id", "effect_name" and "effect_photo_URI". Returns further details of effects when used in a video.
- **video_mention_list** (list<string>) - Returns other users tagged in a video.
- **video_label** (Struct) - Returns any information and labels associated with a video.
- **video_duration** (int64) - The duration of the video, in seconds.
- **is_stem_verified** (bool) - Whether the video has been verified as being high quality STEM content.
- **favorites_count** (int64) - The number of favorites that a video receives.
- **video_tag** (Struct) - "video_tag_type" and "video_tag_number" returned here Definitions: "video_tag_number" = 2, and "video_tag_type" = AIGC Type indicates "Creator Labelled as AI-Generated" "video_tag_number" = 1, and "video_tag_type" = AIGC Type indicates "AI-Generated" "video_tag_number" = 7, and "video_tag_type" = Branded Type indicates "Creator Earns Commission" "video_tag_number" = 1, and "video_tag_type" = Branded Type indicates "Paid Partnership"
```

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

### Initialize TikTok Minis SDK

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Dramas/Develop Your Mini Drama.md

Initialize the TikTok Minis SDK by including a script in your HTML and calling TTMinis.init() with your client key. This enables access to TikTok's client-side JavaScript APIs.

```APIDOC
## Initialize TikTok Minis SDK

First, you must initialize the TikTok Minis SDK to access all of TikTok's client-side JavaScript APIs.
To use TikTok Minis SDK, include a piece of JavaScript code in your HTML to asynchronously load the SDK into your pages. This will not block other elements from loading on your page. TikTok Minis SDK does not require standalone files or downloads.
Add the TikTok Minis SDK to your `index.html` file and initialize it with your project's unique client key:
```html
<!-- index.html -->
<head>
  <script src="https://connect.tiktok-minis.com/drama/sdk.js"></script>
  <script>
    TTMinis.init({
      clientKey: "your_client_key_here",
    });
  </script>
</head>
```
```

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

### Get Active Subscriptions

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/TikTok Minis Platform/TikTok Minis Server APIs/Subscription APIs.md

Retrieves a list of active subscriptions for a user. This endpoint is useful for checking the current subscription status and details.

```APIDOC
## GET /v2/minis/subscription/get_active_list

### Description
Retrieves a list of active subscriptions for a user.

### Method
GET

### Endpoint
https://open.tiktokapis.com/v2/minis/subscription/get_active_list

### Request Example
```
curl --location 'https://open.tiktokapis.com/v2/minis/subscription/get_active_list' \
--header 'Authorization: Bearer {AccessToken}' \
--header 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **data** (object) - Contains subscription data.
  - **subscriptions** (array) - List of active subscriptions.
    - **subscription_id** (string) - Unique identifier for the subscription.
    - **tier_id** (string) - Identifier for the subscription tier.
    - **is_subscription_rights_valid** (boolean) - Indicates if the subscription rights are currently valid.
    - **is_renewal_normal** (boolean) - Indicates if the subscription is renewing normally.
    - **trade_order_id** (string) - The ID of the trade order associated with the subscription.
    - **is_sandbox** (boolean) - Indicates if the subscription is part of a sandbox environment.
    - **begin_time** (integer) - Timestamp when the subscription began.
    - **end_time** (integer) - Timestamp when the subscription ends.
    - **next_duduct_time** (integer) - Timestamp for the next deduction.
    - **pay_type** (string) - The payment type (e.g., 'IAP').

#### Response Example
```json
{
    "data": {
        "subscriptions": [
            {
                "subscription_id": "tb4ML0ZVim",
                "tier_id": "xohs4Jojay",
                "is_subscription_rights_valid": true,
                "is_renewal_normal": false,
                "trade_order_id": "ggG7luEdWt",
                "is_sandbox": true,
                "begin_time": 8054018414209391465,
                "end_time": 1061662930613089341,
                "next_duduct_time": 2184276991229817160,
                "pay_type": "IAP"
            }
        ]
    },
    "error": {
        "code": "ok",
        "message": "",
        "log_id": "20241125114034036EE8AEADBAF91D5E93"
    }
}
```
```

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

### Get active subscription list

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/TikTok Minis Platform/TikTok Minis Server APIs/Subscription APIs.md

Retrieves a list of all active subscriptions for a user. This endpoint returns detailed information about each active subscription.

```APIDOC
## POST https://open.tiktokapis.com/v2/minis/subscription/get_active_list/

### Description
Retrieves a list of all active subscriptions for a user. This endpoint returns detailed information about each active subscription.

### Method
POST

### Endpoint
https://open.tiktokapis.com/v2/minis/subscription/get_active_list/

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - The token that bears the authorization of the TikTok user, which is obtained through /oauth/access_token/.

### Response
#### Success Response (200)
- **subscriptions** (list<ThirdPartyUserSubscriptionObject>) - List of active subscriptions

**ThirdPartyUserSubscriptionObject**
- **subscription_id** (string) - Required - ID of the subscription
- **tier_id** (string) - Required - ID of the subscription product
- **is_subscription_rights_valid** (bool) - Required - indicate whether this right is still valid
- **is_renewal_normal** (bool) - Required - indicate whether the renew is normal, false if renew is failed/onold
- **trade_order_id** (string) - Required - the latest trade_order_id related to this subscription
- **begine_time** (int64) - Optional - beginning time of this subscription
- **end_time** (int64) - Optional - end time of this subscription
- **next_duduct_time** (int64) - Optional - time of the next deduct
- **pay_type** (string) - Optional - IAP or WEB; IAP=Google/Apple Store, WEB=PayPal
```

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

### Create WebAudioContext

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Games/Mini Games SDK/Media.md

Creates a WebAudioContext instance for advanced audio processing.

```APIDOC
## .createWebAudioContext

Creates a `WebAudioContext` instance for advanced audio processing.

### Return Value

| Object |
| --- |
| WebAudioContext | A `WebAudioContext` object instance. |

### Example

```javascript
const webAudioContext = tt.createWebAudioContext();
```
```

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

### Get QR Code

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Login Kit/QR Code Authorization.md

Requests a QR code from TikTok for user authorization. This endpoint is used to initiate the QR code login flow.

```APIDOC
## POST https://open.tiktokapis.com/v2/oauth/get_qrcode/

### Description
Request a QR code from TikTok.

### Header

| **Key** | **Value** |
| --- | --- |
| Content-Type | application/x-www-form-urlencoded |

### Parameters

#### Request

| **Key** | **Type** | **Description** | **Example** | **Required** |
| --- | --- | --- | --- | --- |
| client_key | string | The unique identification key provisioned to the partner | aw7nk86b7czitwc9 | true |
| scope | string | A comma-separated list (,) of the scopes the user has agreed to authorize | user.info.basic,video.list | true |
| state | string | The state is used to maintain the state of your request and callback. This value will be included when redirecting the user back to the client. Check if the state returned in the callback matches what you sent earlier to prevent cross-site request forgery. The state can also include customized parameters that you want TikTok service to return. | key%3Dabc%26key2%3Ddef | false |

### Example request
```curl
curl --location --request POST 'https://open.tiktokapis.com/v2/oauth/get_qrcode/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_key=aw7nk86b7czitwc9' \
--data-urlencode 'scope=user.info.basic,user.info.username' \
--data-urlencode 'state=key%3Dabc%26key2%3Ddef'
```
```

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

### Get Initial Access Token using cURL

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/TikTok GO/Obtain Access Token for APIs.md

Use this cURL command to make the initial request for an access token bundle after a merchant approves your scope requests. Ensure you replace placeholder values with your actual credentials and merchant ID.

```curl
curl --location 'https://open.tiktokapis.com/merchant/oauth/token/' \
--header 'x-tt-target-idc: alisg' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_key=xxxxxxx' \
--data-urlencode 'client_secret=xxxxxxxx' \
--data-urlencode 'grant_type=access_token' \
--data-urlencode 'merchant_id=xxxxxx'
```

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

### Query Video Data - First Request

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Research Tools/Getting Started - Research API.md

Use this cURL command for the initial request to query video data. Do not include `search_id` or `cursor` in the request body. The response will contain these values for subsequent requests.

```bash
curl --location 'https://open.tiktokapis.com/v2/research/video/query/?fields=id%2Clike_count' \
--header 'authorization: bearer abcdefg' \
--header 'Content-Type: application/json' \
--data '{ 
  "query": { 
              "and": [ 
                   { "operation": "IN", "field_name": "region_code", "field_values": ["US", "CA"] }, 
                   { "operation": "EQ", "field_name": "keyword", "field_values": ["hello world"] } 
               ] 
          }, 
  "max_count": 100, 
    "cursor": 0, 
    "start_date": "20181207", 
    "end_date": "20181207", 
    "is_random": false}'
```

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

### Handle Payment Success Webhook

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Games/Capability Guides/In-App Purchases.md

This is an example of a webhook payload received when an order payment is successful. Register a callback URL in the Developer Portal to receive these notifications.

```json
{
    "client_key": "your_client_key",
    "event": "minis.trade_order.redeem.success",
    "create_time": 1615338610,
    "user_openid": "",
    "content": "{\"trade_order_id\":\"TOID667700996\",\"order_id\":\"order_id_as_in_your_system\",\"is_sandbox\":true}"
}
```

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

### Get Active Subscriptions List

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/TikTok Minis Platform/TikTok Minis Server APIs/Subscription APIs.md

Retrieves a list of active subscriptions for a user. This endpoint is useful for displaying a user's current subscriptions within your mini-program.

```curl
curl --location 'https://open.tiktokapis.com/v2/minis/subscription/get_active_list' \
--header 'Authorization: Bearer {AccessToken}' \
--header 'Content-Type: application/json'
```

```json
{
    "data": {
        "subscriptions": [
            {
                "subscription_id": "tb4ML0ZVim",
                "tier_id": "xohs4Jojay",
                "is_subscription_rights_valid": true,
                "is_renewal_normal": false,
                "trade_order_id": "ggG7luEdWt",
                "is_sandbox": true,
                "begin_time": 8054018414209391465,
                "end_time": 1061662930613089341,
                "next_duduct_time": 2184276991229817160,
                "pay_type": "IAP"
            }
        ]
    },
    "error": {
        "code": "ok",
        "message": "",
        "log_id": "20241125114034036EE8AEADBAF91D5E93"
    }
}
```

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

### Create WebAudioContext

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Games/Mini Games SDK/Media.md

Creates a WebAudioContext instance for advanced audio processing.

```javascript
const webAudioContext = tt.createWebAudioContext();
```

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

### Query User Followers

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Research Tools/API Reference/Query User Followers.md

Use this endpoint to get a list of users who follow a specific TikTok user. You can control the number of results and paginate through the follower list.

```APIDOC
## POST https://open.tiktokapis.com/v2/research/user/followers/

### Description
Retrieves a list of followers for a specified TikTok user.

### Method
POST

### Endpoint
https://open.tiktokapis.com/v2/research/user/followers/

### Headers
- **Authorization** (string) - Required - The client access token obtained from /v2/oauth/token/.
- **Content-Type** (string) - Required - application/json

### Parameters
#### Request Body
- **username** (string) - Required - The username as the unique identifier.
- **max_count** (int64) - Optional - The maximum number of followers that can be returned in this response. Default is 20; max is 100.
- **cursor** (int64) - Optional - Followers followed on or before this time will be returned. It is a Unix timestamp in UTC seconds. Default value is set as the time this request was made.

### Request Example
```json
{
    "username": "test_user",
    "max_count": 3,
    "cursor": 12347764
}
```

### Response
#### Success Response (200)
- **data** (UserFollowerData) - The list of the followers of the user.
- **error** (ErrorStructV2) - Error object.

### UserFollowerData
- **user_followers** (list<UserInfo>) - A list of user info objects that match the query.
- **cursor** (int64) - Followers that followed this user on or before this time will be returned. It is a Unix timestamp in UTC seconds. Default value is set as the time this request was made.
- **has_more** (bool) - Whether this user has more followers or not.

### User Info Object
- **display_name** (string) - The profile name of the follower of this user.
- **username** (string) - The username of the follower of this user.

### Response Example
```json
{
    "data": {
        "cursor": 1706837834,
        "has_more": true,
        "user_followers": [
            {
                "display_name": "test user",
                "username": "test_username"
            },
            {
                "username": "test user 2",
                "display_name": "test_username2"
            }
        ]
    },
    "error": {
        "code": "ok",
        "message": "ok",
        "log_id": "123499999999999999999999999999"
    }
}
```
```

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

### Create Rewarded Ad Instance

Source: https://github.com/rioanandaputra-bot/tiktok-docs-mcp/blob/main/docs/developers_tiktok_com/Docs/Mini Games/Capability Guides/In-App Ads.md

Use this to create an instance of a rewarded video ad. Ensure the ad placement is active and obtain its Placement ID.

```javascript
const rewardedVideoAd = TTMinis.game.createRewardedVideoAd({
  adUnitId: 'xxx';
});
```