Menu

App API (v3)

1. Create Apps

1.1 Request URL

https://api.toponad.net/v3/apps

1.2 Request method

POST

1.3 Request params

params type required notes
items Array[Object] Y App list
items.platform Int Y

System Platfrom:

1: Android

2: iOS
items.name String Y

App name. Maximum length: 100 characters
items.store_on_sale Int Y

In App store:

1: No

2: Yes
items.store_type Int N

Store type, leave blank for apps that are not yet available, enumeration value:

1: Apple App Store
2: Google Play
3: Huawei
4: Xiaomi
5: OPPO
6: vivo
7: Tencent App Store
8: TapTap
9: Amazon Appstore
10: Samsung Galaxy Store
11: Mi App Mall (Global)
12: HUAWEI AppGallery (Global)
13: Roku
14: Samsung Smart TV
15: Microsoft
16: LG Smart TV
17: Vizio
99: Other
items.store_url String N App store link, must comply with store link specifications. If the app is not yet available, this field can be left blank.
items.package_name String Y App package name. Example: com.xxx
items.category String Y

Category. See the appendix (APP category and sub category enum).
items.sub_category String Y Sub-Category. See the appendix (APP category and sub category enum).
items.screen_orientation Int Y

Screen Orientation: 

1: Portrait

2: Landscape

3: Auto
items.coppa Int Y

Whether to comply with COPPA protocol. 

1: No

2: Yes
items.ccpa Int Y

Whether to comply with CCPA protocol.

1: No

2: Yes

1.4 Return data

params type required notes
items Array[Object] N

The list of successfully created app information, index positions, and request parameters items index positions correspond one-to-one.
items.uuid String Y

App id
items.app_key String Y

App Key (app dimension)

When integrating and initializing the TopOn SDK, you need to use the App Key. You can use the App Key for this account dimension or the App Key for the app dimension.
errs Array[Object] N Error application information list, note:
1. If the list is empty, the operation is successful.
2. If the list is not empty, the list indicates which apps failed verification, and all apps (including those that passed verification) failed.
errs.index Int Y The index position of the error item in the request parameter items, starting from 0.
errs.code Int Y Error code
errs.msg String Y Error message

1.5 Sample

Request sample:

curl --location --request POST 'https://api.toponad.net/v3/apps' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0==5b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "items": [
        {
            "platform": 2,
            "name": "xcj_openapi_v1",
            "category": "Game",
            "sub_category": "Casual",
            "store_url": "https://www.taptap.cn/app/dsdsd",
            "package_name": "xcj.vip.test1",
            "screen_orientation": 1,
            "store_on_sale":1,
            "store_type": 8,
            "coppa": 1,
            "ccpa": 2
        }
    ]
}'

Return sample:

{
    "items": [
        {
            "uuid": "a66cccsxxxx",
            "app_key": "0b9df85fb9d552ef7====b805e6b004"
        }
    ]
}

2. Update Apps

2.1 Request URL

https://api.toponad.net/v3/apps

2.2 Request method

PUT

2.3 Request params

params type required note
items Array[Object] Y App list
items.uuid String Y

App id
items.name String Y App name. Maximum length: 100 characters
items.store_on_sale Int Y

In App store:

1: No

2: Yes
items.store_type Int N

Store type, leave blank for apps that are not yet available, enumeration value:

1: Apple App Store
2: Google Play
3: Huawei
4: Xiaomi
5: OPPO
6: vivo
7: Tencent App Store
8: TapTap
9: Amazon Appstore
10: Samsung Galaxy Store
11: Mi App Mall (Global)
12: HUAWEI AppGallery (Global)
13: Roku
14: Samsung Smart TV
15: Microsoft
16: LG Smart TV
17: Vizio
99: Other
items.store_url String N App store link, must comply with store link specifications. If the app is not yet available, this field can be left blank.
items.package_name String Y App package name. Example: com.xxx
items.category String Y

Category. See the appendix (APP category and sub category enum).
items.sub_category String Y Sub-Category. See the appendix (APP category and sub category enum).
items.screen_orientation Int Y

Screen Orientation: 

1: Portrait

2: Landscape

3: Auto
items.coppa Int Y

Whether to comply with COPPA protocol. 

1: No

2: Yes
items.ccpa Int Y

Whether to comply with CCPA protocol.

1: No

2: Yes

2.4 Return data

params type required notes
errs Array[Object] N Error application information list, note:
1. If the list is empty, the operation is successful.
2. If the list is not empty, the list indicates which apps failed verification, and all apps (including those that passed verification) failed.
errs.index Int Y The index position of the error item in the request parameter items, starting from 0.
errs.code Int Y Error code
errs.msg String Y Error message

2.5 Sample

Request sample:

curl --location --request PUT 'https://api.toponad.net/v3/apps' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0==5b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "items": [
        {
            "uuid": "a1ftn3doaefj15",
            "name": "xcj_openapi_v122",
            "category": "Game",
            "sub_category": "Casual",
            "package_name": "aieku.vip.test122",
            "screen_orientation": 2,
            "store_on_sale": 1,
            "store_type": 8,
            "store_url": "https://www.viziozzz22==.com/smart-tv-apps?appName=topon&appId=vizio.topon",
            "coppa": 1,
            "ccpa": 1
           
        }
    ]
}'

Return sample:

{}

3. Get Apps

Note: Currently still v1, may be upgraded to v3 in the future.

3.1 Request URL

https://api.toponad.net/v1/apps

3.2 Request method

POST

3.3 Request params

params type required notes
app_ids Array[String] N App ID list, default to all app IDs, maximum limit of 100. Note: When used with the start and limit params, the number of apps obtained based on the start+limit condition shall prevail.
start Int N Starting offset, default 0
limit Int N Get the number of items, default 100, maximum 100 items at a time.

3.4 Return data

params type required notes
- Array[Object] Y App list
-.app_id String Y App id
-.app_name String Y App name
-.app_key String Y

App Key (app dimension)

When integrating and initializing the TopOn SDK, you need to use the App Key. You can use the App Key for this account dimension or the App Key for the app dimension.
-.platform Int Y

System Platfrom:

1: Android

2: iOS
-.market_url String N App store link
-.screen_orientation Int Y

Screen Orientation: 

1: Portrait

2: Landscape

3: Auto
-.package_name String N App package name
-.category String N

Category
-.sub-category String N Sub-Category
-.coppa String N

Whether to comply with COPPA protocol. 

1: No

2: Yes
-.ccpa Int N

Whether to comply with CCPA protocol.

1: No

2: Yes
-.status Int N

Application status (e.g., enabled, disabled)

1: Disabled

3: Enabled
-.store_on_sale Int N

In App store:

1: No

2: Yes
-.errors Int N

Error messages (returned when an error occurs), with some error descriptions as follows: 1. “No apps could be matched”: The request parameters app_ids and start, limit are used incorrectly.

3.5 Sample

Request sample: 

curl --location --request POST 'https://api.toponad.net/v1/apps' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0==5b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "limit":1
}'

Return sample: 

[
    {
        "app_name": "uparputest",
        "app_id": "a5bc9921f7fdb4",
        "app_key": "aed37b858b3a7ecc54e1ecf4634399fxx",
        "platform": 2,
        "market_url": "https://itunes.apple.com/cn/app/%E7%A5%9E%E5%9B%9E%E9%81%BF/id1435756371?mt=8",
        "category": "Game",
        "sub_category": "Action",
        "screen_orientation": 3
    }
]

Previous
App API (Expired)
Next
Placement API
Last modified: 2025-08-21Powered by