{"components":{"schemas":{"APIError":{"properties":{"code":{"type":"string"},"docs_url":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","request_id"],"type":"object"},"APIResponse":{"properties":{"data":{"description":"Response data (endpoint-specific)","type":"object"},"page":{"type":"integer"},"page_size":{"type":"integer"},"request_id":{"type":"string"},"total":{"description":"Total count (list endpoints)","type":"integer"},"usage":{"$ref":"#/components/schemas/UsageInfo"},"warnings":{"items":{"type":"string"},"type":"array"}},"required":["data","request_id"],"type":"object"},"UsageInfo":{"properties":{"credits_balance":{"description":"Remaining credits balance after this request","type":"integer"},"credits_cost":{"description":"Credits consumed for this request","type":"integer"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"X-API-Key","type":"apiKey"},"BearerAuth":{"scheme":"bearer","type":"http"}}},"info":{"contact":{"email":"support@trenz.ai","name":"Trenz"},"description":"Trenz Open Platform API for cross-border e-commerce data, content creation, social media management and advertising.\n\n## Authentication\n\nAll requests must include `X-API-Key` header or `Authorization: Bearer \u003cAPI-Key\u003e`.\n\n## Platform Error Baseline\n\nThese errors are produced by the Open Platform. For endpoint-specific business errors, the operation's Responses are authoritative.\n\n| HTTP | Code | Description |\n|------|------|-------------|\n| 400 | BAD_REQUEST | Malformed request |\n| 400 | INVALID_PARAM | Invalid parameter |\n| 400 | MISSING_PARAM | Required parameter missing |\n| 400 | INVALID_SORT_FIELD | Invalid sort field |\n| 400 | INVALID_INCLUDE | Invalid include parameter |\n| 400 | PAGE_SIZE_EXCEEDED | Page size exceeded |\n| 401 | AUTH_MISSING_KEY | API Key missing |\n| 401 | AUTH_INVALID_KEY | API Key invalid |\n| 401 | AUTH_KEY_REVOKED | API Key revoked |\n| 401 | AUTH_KEY_SUSPENDED | API Key suspended |\n| 402 | INSUFFICIENT_CREDITS | Insufficient credits |\n| 403 | FORBIDDEN_SCOPE | No permission to access this resource |\n| 404 | ROUTE_NOT_FOUND | Endpoint not found |\n| 404 | TASK_NOT_FOUND | Async task not found |\n| 429 | RATE_LIMITED | Rate limit exceeded |\n| 429 | QUOTA_EXCEEDED | Quota exceeded |\n| 500 | INTERNAL_ERROR | Internal server error |\n| 502 | BACKEND_ERROR | Upstream service error |\n| 503 | BACKEND_UNAVAILABLE | Upstream service unavailable |\n| 504 | BACKEND_TIMEOUT | Upstream service timeout |","title":"Trenz Open Platform API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/open/v1/ad-creatives/{id}":{"get":{"description":"Get TikTok ad creative details.","operationId":"trenz-ad-creative-detail","parameters":[{"description":"Ad creative ID","in":"path","name":"entity_id","required":true,"schema":{"type":"string"}},{"description":"Region code","in":"query","name":"country","required":true,"schema":{"enum":["us","th","my","vn","mx","it","fr","de","es","jp","br","gb","ph","sg","id"],"type":"string"}},{"description":"Included sub-resources, comma-separated: calendar,core,trend,products,similar","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Include related resources, comma-separated (values: core(Core Metrics))","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"ad_cover":{"description":"Ad cover image","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"ad_create_time":{"description":"Ad creation time","type":"integer"},"ad_title":{"description":"Ad title","type":"string"},"ad_url":{"description":"Ad URL","type":"string"},"advertiser_avatar":{"description":"Advertiser avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"advertiser_id":{"description":"Advertiser ID","type":"string"},"advertiser_name":{"description":"Advertiser name","type":"string"},"button_text":{"description":"CTA button text","type":"string"},"create_time":{"description":"Created at (ms timestamp)","type":"integer"},"duration":{"description":"Duration (ms)","type":"integer"},"id":{"description":"Unique identifier","type":"string"},"last_update_time":{"description":"Last updated (ms timestamp)","type":"integer"},"web_url":{"description":"Product page URL","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"TikTok Ad Creative Detail","tags":["Data/5.Ads \u0026 Creatives"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ad-creatives/{id}/products":{"get":{"description":"Get the products promoted or associated with this TikTok ad creative — useful for analyzing what the ad is selling.","operationId":"trenz-ad-creative-products","parameters":[{"description":"Ad Creative ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_ads_detail_product_country_code":{"description":"Country code","type":"string"},"tiktok_ads_detail_product_id":{"description":"Unique identifier","type":"string"},"tiktok_ads_detail_product_launch_time":{"description":"Published at (ms timestamp)","type":"integer"},"tiktok_ads_detail_product_total_gmv":{"description":"Total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_ads_detail_product_total_sold_count":{"description":"Total units sold","type":"integer"},"tiktok_ads_detail_video_30d_gmv":{"description":"Video 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_ads_detail_video_30d_sold_count":{"description":"Video 30D Sold Count","type":"integer"},"tiktok_ads_detail_video_id":{"description":"Video ID","type":"string"},"tiktok_product_detail_ceiling_price":{"description":"Max price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_commission_rate":{"description":"Commission rate","type":"number"},"tiktok_product_detail_floor_price":{"description":"Min price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_l1_category":{"description":"Level-1 category","type":"string"},"tiktok_product_detail_l2_category":{"description":"Level-2 category","type":"string"},"tiktok_product_detail_l3_category":{"description":"Level-3 category","type":"string"},"tiktok_product_detail_product_images":{"description":"Product images","items":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_name":{"description":"Product name","type":"string"},"tiktok_product_detail_product_rating":{"description":"Product rating (0-5)","type":"number"},"tiktok_product_detail_product_sku_props":{"description":"SKU properties","items":{"properties":{"has_image":{"description":"Has image","type":"boolean"},"prop_id":{"description":"Property ID","type":"string"},"prop_name":{"description":"Property name","type":"string"},"sale_prop_values":{"description":"Property values","items":{"properties":{"image":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"prop_value":{"description":"Property value","type":"string"},"prop_value_id":{"description":"Property value ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_skus":{"description":"SKU list","items":{"properties":{"is_hot":{"description":"Is hot selling","type":"boolean"},"price":{"properties":{"discount":{"description":"Discount info","type":"string"},"original_price":{"description":"Original price","type":"string"},"original_price_value":{"description":"Original price value","type":"string"},"real_price":{"description":"Actual price","type":"number"},"unit_price_desc":{"description":"Unit price description","type":"string"}},"type":"object"},"sale_prop_value_ids":{"description":"Property value ID combination","type":"string"},"sku_id":{"description":"SKU ID","type":"string"},"sku_sale_props":{"description":"SKU properties","items":{"properties":{"prop_id":{"description":"Property ID","type":"string"},"prop_name":{"description":"Property name (e.g. Color)","type":"string"},"prop_value":{"description":"Property value","type":"string"},"prop_value_id":{"description":"Property value ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"Status (1=active)","type":"integer"},"stock":{"description":"Stock","type":"integer"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_status":{"description":"Product status","type":"integer"},"tiktok_product_detail_region":{"description":"Region code","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Ad Creative Related Products","tags":["Data/5.Ads \u0026 Creatives"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ad-creatives/{id}/similar":{"get":{"description":"Get ads similar to this TikTok ad creative — for competitor and similar top-seller research.","operationId":"trenz-ad-creative-similar","parameters":[{"description":"Ad Creative ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_ads_detail_similar_ad_cover":{"description":"Ad cover image","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_ads_detail_similar_ad_create_time":{"description":"Ad creation time","type":"integer"},"tiktok_ads_detail_similar_ad_day_count":{"description":"Days running","type":"integer"},"tiktok_ads_detail_similar_ad_title":{"description":"Ad title","type":"string"},"tiktok_ads_detail_similar_ad_type":{"description":"Ad type","type":"integer"},"tiktok_ads_detail_similar_ad_url":{"description":"Ad URL","type":"string"},"tiktok_ads_detail_similar_advertiser_avatar":{"description":"Advertiser avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_ads_detail_similar_advertiser_id":{"description":"Advertiser ID","type":"string"},"tiktok_ads_detail_similar_advertiser_name":{"description":"Advertiser name","type":"string"},"tiktok_ads_detail_similar_button_text":{"description":"CTA button text","type":"string"},"tiktok_ads_detail_similar_country_code":{"description":"Country code","type":"string"},"tiktok_ads_detail_similar_creative_id":{"description":"Creative ID","type":"string"},"tiktok_ads_detail_similar_duration":{"description":"Duration (ms)","type":"integer"},"tiktok_ads_detail_similar_last_update_time":{"description":"Last updated (ms timestamp)","type":"integer"},"tiktok_ads_detail_similar_objective_type":{"description":"Ad objective type","type":"integer"},"tiktok_ads_detail_similar_product_id":{"description":"Product ID","type":"string"},"tiktok_ads_detail_similar_product_images":{"description":"Product images","items":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"type":"array"},"tiktok_ads_detail_similar_product_l1_category":{"description":"Product L1 Category","type":"string"},"tiktok_ads_detail_similar_product_l2_category":{"description":"Product L2 Category","type":"string"},"tiktok_ads_detail_similar_product_l3_category":{"description":"Product L3 Category","type":"string"},"tiktok_ads_detail_similar_product_title":{"description":"Product title","type":"string"},"tiktok_ads_detail_similar_total_gmv":{"description":"Total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_ads_detail_similar_video_id":{"description":"Video ID","type":"string"},"tiktok_ads_detail_similar_video_play_count":{"description":"View count","type":"integer"},"tiktok_ads_detail_similar_video_popularity":{"description":"Video popularity","type":"integer"},"tiktok_ads_detail_similar_web_url":{"description":"Product page URL","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Similar Ad Creatives","tags":["Data/5.Ads \u0026 Creatives"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ads/accounts":{"post":{"description":"List ad accounts with platform filtering; returns account info and statistics.\n\nTo bind your account, please go to Trenz to complete the binding.","operationId":"trenz-ads-account-list","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"page":{"description":"Page number","type":"integer"},"page_size":{"default":10,"description":"Page size, default 10, max 100","maximum":100,"type":"integer"},"platforms":{"description":"Platform type list, default [\"tiktok-advertiser\"]","items":{"type":"string"},"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"accounts":{"description":"Account list","items":{"properties":{"account_id":{"description":"Account ID","type":"string"},"advertiser_id":{"description":"Advertiser ID","type":"string"},"advertiser_name":{"description":"Advertiser name","type":"string"},"platform":{"description":"Platform type","type":"string"},"remark":{"description":"Remark","type":"string"},"status":{"description":"Status","type":"string"}},"type":"object"},"type":"array"},"page_info":{"description":"Pagination","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total_number":{"type":"integer"},"total_page":{"type":"integer"}},"type":"object"},"stats":{"description":"Account statistics","type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Ad Account List","tags":["Ads/1.Accounts"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ads/gmv-max/campaigns":{"post":{"description":"List GMV MAX (semi-managed) campaigns with performance metrics such as gross_revenue, ROAS, and orders. Supports filtering by advertiser or store. Note: store_ids/campaign_ids must be passed as a JSON array string, e.g. [\"id1\",\"id2\"]. The advertiser and store must first be bound in Trenz.","operationId":"trenz-ads-gmvmax-campaigns","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Internal account ID (optional; if omitted, returns per current user's permission scope)","type":"string"},"advertiser_id":{"description":"TikTok advertiser ID (optional when querying by store)","type":"string"},"campaign_ids":{"description":"Campaign ID list, JSON array string","type":"string"},"campaign_name":{"description":"Campaign name fuzzy search","type":"string"},"end_date":{"description":"Performance metrics end date YYYY-MM-DD","type":"string"},"gmv_max_promotion_types":{"description":"GMV MAX promotion type filter","type":"string"},"page":{"default":1,"description":"Page number, default 1","type":"integer"},"page_size":{"description":"Page size","type":"integer"},"primary_status":{"description":"Primary status filter","type":"string"},"start_date":{"description":"Performance metrics start date YYYY-MM-DD","type":"string"},"store_ids":{"description":"Store ID list, JSON array string, e.g. \"[\\\"store1\\\"]\"","type":"string"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"GMV MAX campaign list","items":{"properties":{"advertiser_id":{"description":"Advertiser ID","type":"string"},"campaign_id":{"description":"Campaign ID","type":"string"},"campaign_name":{"description":"Campaign name","type":"string"},"cpa":{"description":"Conversion cost (CPA)","type":"number"},"create_time":{"description":"Create time","type":"string"},"currency":{"description":"Currency code","type":"string"},"gross_revenue":{"description":"Gross revenue (GMV MAX gross_revenue)","type":"number"},"modify_time":{"description":"Update time","type":"string"},"objective_type":{"description":"Promotion objective","type":"string"},"operation_status":{"description":"Toggle status: ENABLE / DISABLE / DELETE","type":"string"},"orders":{"description":"Order count","type":"integer"},"promotion_type":{"description":"Promotion type: PRODUCT_GMV_MAX (product) / LIVE_GMV_MAX (live) (cached list may be empty)","type":"string"},"report_date":{"description":"Report date YYYY-MM-DD","type":"string"},"roas":{"description":"Paid ROAS","type":"number"},"secondary_status":{"description":"Actual delivery status (same enum as campaign)","type":"string"},"spend":{"description":"Spend","type":"number"}},"type":"object"},"type":"array"},"page_info":{"description":"Pagination info","properties":{"page":{"description":"Current page number","type":"integer"},"page_size":{"description":"Page size","type":"integer"},"total_number":{"description":"Total count","type":"integer"},"total_page":{"description":"Total pages","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"GMV MAX Campaign List","tags":["Ads/3.GMV MAX"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ads/gmv-max/report/campaign":{"post":{"description":"Query GMV MAX campaign-level report data by dimensions and metrics, supporting aggregation over campaign_id/item_group_id/item_id/stat_time_day with custom metrics. account_id, advertiser_id, dimensions, metrics, start_date, end_date, and store_ids are all required. store_ids is a true array (not a string). The advertiser and store must first be bound in Trenz.","operationId":"trenz-ads-gmvmax-report-campaign","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Internal account ID (required)","type":"string"},"advertiser_id":{"description":"TikTok advertiser ID (required)","type":"string"},"campaign_ids":{"description":"Filter by campaign","items":{"type":"string"},"type":"array"},"dimensions":{"description":"Aggregation dimension (required): campaign_id / item_group_id / item_id / stat_time_day","items":{"type":"string"},"type":"array"},"end_date":{"description":"Stats end date YYYY-MM-DD (required)","type":"string"},"gmv_max_promotion_type":{"description":"Promotion type: PRODUCT / LIVE","type":"string"},"item_group_ids":{"description":"Filter by item group","items":{"type":"string"},"type":"array"},"metrics":{"description":"Metrics list (required)","items":{"type":"string"},"type":"array"},"page":{"description":"Page number","type":"integer"},"page_size":{"description":"Page size, max 1000","maximum":1000,"type":"integer"},"start_date":{"description":"Stats start date YYYY-MM-DD (required)","type":"string"},"store_ids":{"description":"Store ID list (required, true array)","items":{"type":"string"},"type":"array"}},"required":["account_id","advertiser_id","dimensions","metrics","start_date","end_date","store_ids"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":5}},"schema":{"properties":{"data":{"properties":{"list":{"description":"Campaign-level report data","items":{"properties":{"average_video_play":{"description":"Average play duration","type":"string"},"campaign_id":{"description":"Dimension: campaign ID","type":"string"},"cost":{"description":"Spend","type":"string"},"cost_per_order":{"description":"Cost per order","type":"string"},"currency":{"description":"Currency code","type":"string"},"delivery_status":{"description":"Delivery status","type":"string"},"gross_revenue":{"description":"Gross revenue (correct GMV MAX campaign-level metric name)","type":"string"},"identity_type":{"description":"Identity type","type":"string"},"item_group_id":{"description":"Dimension: item group ID","type":"string"},"item_id":{"description":"Dimension: product ID","type":"string"},"orders":{"description":"Order count","type":"string"},"product_clicks":{"description":"Product clicks","type":"string"},"product_impressions":{"description":"Product impressions","type":"string"},"roi":{"description":"ROI","type":"string"},"stat_time_day":{"description":"Dimension: stat day","type":"string"},"title":{"description":"Title","type":"string"},"tt_account_name":{"description":"TikTok account name","type":"string"},"video_views_p100":{"description":"100% completion count","type":"string"},"video_views_p25":{"description":"25% completion count","type":"string"},"video_views_p50":{"description":"50% completion count","type":"string"},"video_views_p75":{"description":"75% completion count","type":"string"},"video_watched_2s":{"description":"2-second play count","type":"string"},"video_watched_6s":{"description":"6-second play count","type":"string"}},"type":"object"},"type":"array"},"page_info":{"description":"Pagination info","properties":{"page":{"description":"Current page number","type":"integer"},"page_size":{"description":"Page size","type":"integer"},"total_number":{"description":"Total count","type":"integer"},"total_page":{"description":"Total pages","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"GMV MAX Campaign Report","tags":["Ads/3.GMV MAX"],"x-billing-mode":"per_call","x-coin-cost":5,"x-scope":"trenz.ads.read"}},"/open/v1/ads/gmv-max/report/creative":{"post":{"description":"Query GMV MAX creative-level report data with creative performance metrics such as CTR, conversion rate, Hook rate (2-second play rate), and completion rate. account_id, advertiser_id, start_date, end_date, store_ids, and item_group_ids are all required (store_ids/item_group_ids are true arrays); dimensions/metrics are not needed. The advertiser and store must first be bound in Trenz.","operationId":"trenz-ads-gmvmax-report-creative","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Internal account ID (required)","type":"string"},"advertiser_id":{"description":"TikTok advertiser ID (required)","type":"string"},"campaign_ids":{"description":"Filter by campaign","items":{"type":"string"},"type":"array"},"end_date":{"description":"Stats end date YYYY-MM-DD (required)","type":"string"},"gmv_max_promotion_type":{"description":"Promotion type: PRODUCT / LIVE","type":"string"},"item_group_ids":{"description":"Item group ID list (required, true array)","items":{"type":"string"},"type":"array"},"page":{"description":"Page number","type":"integer"},"page_size":{"description":"Page size","type":"integer"},"start_date":{"description":"Stats start date YYYY-MM-DD (required)","type":"string"},"store_ids":{"description":"Store ID list (required, true array)","items":{"type":"string"},"type":"array"}},"required":["account_id","advertiser_id","start_date","end_date","store_ids","item_group_ids"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":5}},"schema":{"properties":{"data":{"properties":{"list":{"description":"Creative-level report data","items":{"properties":{"ad_click_rate":{"description":"Ad CTR (creative-level actual CTR)","type":"string"},"ad_conversion_rate":{"description":"Ad conversion rate (actual CVR)","type":"string"},"ad_video_view_rate_2s":{"description":"2-second play rate (Hook rate)","type":"string"},"ad_video_view_rate_6s":{"description":"6-second play rate","type":"string"},"ad_video_view_rate_p100":{"description":"100% completion rate","type":"string"},"ad_video_view_rate_p25":{"description":"25% completion rate","type":"string"},"ad_video_view_rate_p50":{"description":"50% completion rate","type":"string"},"ad_video_view_rate_p75":{"description":"75% completion rate","type":"string"},"cost":{"description":"Spend","type":"string"},"creative_delivery_status":{"description":"Creative delivery status","type":"string"},"currency":{"description":"Currency code","type":"string"},"gross_revenue":{"description":"Gross revenue","type":"string"},"item_id":{"description":"Dimension: creative/product ID","type":"string"},"orders":{"description":"Order count","type":"string"},"product_click_rate":{"description":"Product CTR","type":"string"},"roi":{"description":"ROI","type":"string"},"shop_content_type":{"description":"Store content type","type":"string"},"title":{"description":"Creative title","type":"string"},"tt_account_authorization_type":{"description":"Creative source: AFFILIATE/AUTH_CODE (creator) / TTS_TT/TT_USER (self-operated) / BC_AUTH_TT (BC authorized)","type":"string"},"tt_account_name":{"description":"TikTok account name","type":"string"},"tt_account_profile_image_url":{"description":"TikTok account avatar URL","type":"string"}},"type":"object"},"type":"array"},"page_info":{"description":"Pagination info","properties":{"page":{"description":"Current page number","type":"integer"},"page_size":{"description":"Page size","type":"integer"},"total_number":{"description":"Total count","type":"integer"},"total_page":{"description":"Total pages","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"GMV MAX Creative Report","tags":["Ads/3.GMV MAX"],"x-billing-mode":"per_call","x-coin-cost":5,"x-scope":"trenz.ads.read"}},"/open/v1/ads/gmv-max/stores":{"post":{"description":"List TikTok Shop stores under the current advertiser. Pass is_gmv_max=true to return only stores eligible for GMV MAX; omit or false to return all stores. account_id is required; use \"Ad Account List\" to find it. The store must first be bound in Trenz.","operationId":"trenz-ads-gmvmax-stores","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Internal account ID (required, used for data permission filtering)","type":"string"},"advertiser_id":{"description":"TikTok advertiser ID (optional; if omitted, returns stores that have GMV MAX campaigns under this account)","type":"string"},"is_gmv_max":{"description":"Whether to return only stores eligible for GMV MAX; true = only eligible, omit or false = all stores","type":"boolean"}},"required":["account_id"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"Store list","items":{"properties":{"account_id":{"description":"Internal account ID this store belongs to","type":"string"},"advertiser_id":{"description":"Advertiser that owns this store's GMV MAX authorization","type":"string"},"is_gmv_max_available":{"description":"Whether eligible for GMV MAX","type":"boolean"},"is_owner_bc":{"description":"Whether owner BC","type":"boolean"},"store_authorized_bc_id":{"description":"Store-authorized BC ID","type":"string"},"store_code":{"description":"Store code","type":"string"},"store_id":{"description":"Store ID","type":"string"},"store_name":{"description":"Store name","type":"string"},"store_role":{"description":"Store role","type":"string"},"store_status":{"description":"Store status","type":"string"},"targeting_region_codes":{"description":"Available region code","items":{"type":"string"},"type":"array"},"thumbnail_signed_url":{"description":"Store thumbnail (S3 signed URL)","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Store List","tags":["Ads/3.GMV MAX"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ads/gmv-max/stores/products":{"post":{"description":"List products (SPU) in a specified TikTok Shop store, including price range, historical sales, GMV MAX ad status, and availability. account_id and store_id are required; use \"Store List\" to find the store_id. The store must first be bound in Trenz.","operationId":"trenz-ads-gmvmax-store-products","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Internal account ID (required, used for data permission filtering)","type":"string"},"keyword":{"description":"Product name keyword search","type":"string"},"page":{"default":1,"description":"Page number, default 1","type":"integer"},"page_size":{"description":"Page size","type":"integer"},"store_id":{"description":"Store ID (required)","type":"string"}},"required":["account_id","store_id"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"Store product list","items":{"properties":{"currency":{"description":"Currency code (USD/THB, etc.)","type":"string"},"gmv_max_ads_status":{"description":"GMV MAX ad status of this product","type":"string"},"historical_sales":{"description":"Historical sales","type":"integer"},"is_running_custom_shop_ads":{"description":"Whether running custom store ads","type":"boolean"},"item_group_id":{"description":"Item group ID (SPU ID)","type":"string"},"max_price":{"description":"Ceiling price","type":"string"},"min_price":{"description":"Floor price (lower bound of the price range across SKUs under an SPU)","type":"string"},"product_image_signed_url":{"description":"Product image (S3 signed URL)","type":"string"},"product_name":{"description":"Product name","type":"string"},"status":{"description":"TikTok Shop availability status: AVAILABLE / NOT_AVAILABLE","type":"string"},"store_id":{"description":"Store ID","type":"string"}},"type":"object"},"type":"array"},"page_info":{"description":"Pagination info","properties":{"page":{"description":"Current page number","type":"integer"},"page_size":{"description":"Page size","type":"integer"},"total_number":{"description":"Total count","type":"integer"},"total_page":{"description":"Total pages","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Store Product List","tags":["Ads/3.GMV MAX"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ads/search":{"get":{"description":"Search TikTok ad creatives with filters on delivery days, estimated GMV, engagement rate, etc.","operationId":"trenz-ads-search","parameters":[{"description":"Search keyword","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"Ad category ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Ad type: 1=TikTok Shop, 2=Independent Site, 3=App, 4=Game, 5=Brand, 6=Lead, 7=Engagement","example":"spark","in":"query","name":"ad_type","required":false,"schema":{"type":"string"}},{"description":"Exclude Spark Ads","example":false,"in":"query","name":"exclude_spark_ads","required":false,"schema":{"type":"boolean"}},{"description":"Min views","example":1000,"in":"query","name":"min_views","required":false,"schema":{"type":"number"}},{"description":"Max views","example":1000000,"in":"query","name":"max_views","required":false,"schema":{"type":"number"}},{"description":"Min GMV (USD)","example":1000,"in":"query","name":"min_gmv","required":false,"schema":{"type":"number"}},{"description":"Max GMV (USD)","example":100000,"in":"query","name":"max_gmv","required":false,"schema":{"type":"number"}},{"description":"Min delivery days","example":1,"in":"query","name":"min_days","required":false,"schema":{"type":"number"}},{"description":"Max delivery days","example":30,"in":"query","name":"max_days","required":false,"schema":{"type":"number"}},{"description":"Sort, format: field:asc|desc. Allowed: cost, days, engagement, gmv, views. Default: gmv:desc","example":"gmv:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv:desc","enum":["cost","days","engagement","gmv","views"],"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"ad_create_time":{"description":"Ad creation time","type":"integer"},"ad_day_count":{"description":"Days running","type":"integer"},"ad_maximum_cost":{"description":"Ad max spend","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"ad_roas":{"description":"Ad ROAS","type":"number"},"ad_title":{"description":"Ad title","type":"string"},"ad_url":{"description":"Ad URL","type":"string"},"advertiser_id":{"description":"Advertiser ID","type":"string"},"advertiser_name":{"description":"Advertiser name","type":"string"},"advertiser_url":{"description":"Advertiser URL","type":"string"},"button_text":{"description":"CTA button text","type":"string"},"country_code":{"description":"Country code","type":"string"},"create_time":{"description":"Created at (ms timestamp)","type":"integer"},"duration":{"description":"Duration (ms)","type":"integer"},"id":{"description":"Unique identifier","type":"string"},"last_update_time":{"description":"Last updated (ms timestamp)","type":"integer"},"product_id":{"description":"Product ID","type":"string"},"product_l1_category":{"description":"Product L1 category","type":"string"},"product_l2_category":{"description":"Product L2 category","type":"string"},"product_l3_category":{"description":"Product L3 category","type":"string"},"product_title":{"description":"Product title","type":"string"},"total_gmv":{"description":"Total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"total_sc":{"description":"Total sales","type":"integer"},"video_engagement_rate":{"description":"Engagement rate (0-1)","type":"number"},"video_gpm_30d":{"description":"30-day video GPM","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"video_id":{"description":"Video ID","type":"string"},"video_like_count":{"description":"Like count","type":"integer"},"video_like_rate":{"description":"Like rate","type":"number"},"video_play_count":{"description":"View count","type":"integer"},"video_popularity":{"description":"Video popularity","type":"integer"},"web_url":{"description":"Product page URL","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Ad Search","tags":["Data/5.Ads \u0026 Creatives"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ads/tiktok/adgroups":{"post":{"description":"List TikTok ad groups with budget, optimization goal, bid, live delivery status, and performance metrics (spend/CTR/CPC). Supports filtering by advertiser, parent campaign, name, and date range. The advertiser must first be bound in Trenz.","operationId":"trenz-ads-adgroups","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Internal account ID (optional; if omitted, returns per current user's permission scope)","type":"string"},"advertiser_id":{"description":"TikTok advertiser ID","type":"string"},"campaign_id":{"description":"Filter ad groups under a specified campaign","type":"string"},"end_date":{"description":"Performance metrics end date YYYY-MM-DD","type":"string"},"keyword":{"description":"Ad group name fuzzy search","type":"string"},"operation_status":{"description":"Toggle status filter: ENABLE / DISABLE","type":"string"},"page":{"default":1,"description":"Page number, starts from 1, default 1","type":"integer"},"page_size":{"default":20,"description":"Page size, default 20, max 100","maximum":100,"type":"integer"},"start_date":{"description":"Performance metrics start date YYYY-MM-DD","type":"string"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"Ad group list","items":{"properties":{"adgroup_id":{"description":"Ad group ID (TikTok)","type":"string"},"adgroup_name":{"description":"Ad group name","type":"string"},"advertiser_id":{"description":"Advertiser ID","type":"string"},"bid_price":{"description":"Bid amount (effective only for custom bidding)","type":"number"},"bid_type":{"description":"Bid type: BID_TYPE_NO_BID (auto) / BID_TYPE_CUSTOM (custom)","type":"string"},"billing_event":{"description":"Billing method: CPC / CPM / CPV / OCPM","type":"string"},"budget":{"description":"Budget amount","type":"number"},"budget_mode":{"description":"Budget mode: BUDGET_MODE_DAY / BUDGET_MODE_TOTAL","type":"string"},"campaign_id":{"description":"Parent campaign ID","type":"string"},"campaign_name":{"description":"Parent campaign name","type":"string"},"clicks":{"description":"Clicks","type":"integer"},"conversion_rate":{"description":"Conversion rate","type":"number"},"conversions":{"description":"Conversions","type":"integer"},"cost_per_conversion":{"description":"Conversion cost","type":"number"},"cpc":{"description":"Cost per click (CPC)","type":"number"},"cpm":{"description":"Cost per mille (CPM)","type":"number"},"ctr":{"description":"CTR","type":"number"},"currency":{"description":"Currency code","type":"string"},"impressions":{"description":"Impressions","type":"integer"},"operation_status":{"description":"Toggle status: ENABLE / DISABLE","type":"string"},"optimization_goal":{"description":"Optimization goal: CLICK / CONVERT / SHOW / REACH","type":"string"},"report_date":{"description":"Latest report date YYYY-MM-DD","type":"string"},"schedule_end_time":{"description":"Delivery end time (Unix seconds)","type":"integer"},"schedule_start_time":{"description":"Delivery start time (Unix seconds)","type":"integer"},"secondary_status":{"description":"Actual delivery status: ADGROUP_STATUS_DELIVERY_OK (delivering) / _NOT_DELIVER (not delivering) / _TIME_DONE (ended) / _AUDIT (under review) / _DISABLE (paused) / _BALANCE_EXCEED (insufficient balance), etc.","type":"string"},"spend":{"description":"Spend","type":"number"}},"type":"object"},"type":"array"},"page_info":{"description":"Pagination info","properties":{"page":{"description":"Current page number","type":"integer"},"page_size":{"description":"Page size","type":"integer"},"total_number":{"description":"Total count","type":"integer"},"total_page":{"description":"Total pages","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Ad Group List","tags":["Ads/2.Delivery"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ads/tiktok/ads":{"post":{"description":"List TikTok ads with field selection, filter conditions, and metrics.","operationId":"trenz-ads-list","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Advertiser account ID","type":"string"},"advertiser_id":{"description":"Advertiser account ID","type":"string"},"exclude_field_types_in_response":{"description":"Excluded field types","items":{"type":"string"},"type":"array"},"fields":{"description":"Fields to return","items":{"type":"string"},"type":"array"},"filtering":{"description":"Filter (click to expand for details)","properties":{"ad_ids":{"description":"Ad ID list","items":{"type":"string"},"type":"array"},"ad_name":{"description":"Ad name (fuzzy search)","type":"string"},"adgroup_ids":{"description":"Ad group ID list","items":{"type":"string"},"type":"array"},"campaign_ids":{"description":"Ad campaign ID list","items":{"type":"string"},"type":"array"},"objective_type":{"description":"Delivery objective type","type":"string"},"primary_status":{"description":"Primary status","type":"string"},"secondary_status":{"description":"Sub-status","type":"string"}},"type":"object"},"force_refresh":{"description":"Whether to force refresh","type":"boolean"},"page":{"description":"Page number","type":"integer"},"page_size":{"default":20,"description":"Page size, default 20, max 100","maximum":100,"type":"integer"},"with_metrics":{"description":"Whether to include metric data","type":"boolean"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"Ad list","items":{"properties":{"ad_id":{"type":"string"},"ad_name":{"type":"string"},"adgroup_id":{"type":"string"},"advertiser_id":{"type":"string"},"campaign_id":{"type":"string"},"create_time":{"type":"string"},"operation_status":{"type":"string"},"status":{"type":"string"}},"type":"object"},"type":"array"},"page_info":{"description":"Pagination","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total_number":{"type":"integer"},"total_page":{"type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Ad List","tags":["Ads/2.Delivery"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ads/tiktok/ads/detail":{"post":{"description":"Get full details of a single TikTok ad, including targeting, budget/bid, and performance data.","operationId":"trenz-ads-detail","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ad_id":{"description":"Ad ID","type":"string"}},"required":["ad_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"ad_id":{"description":"Ad ID","type":"string"},"ad_name":{"description":"Ad name","type":"string"},"ad_text":{"description":"Ad copy","type":"string"},"adgroup_id":{"description":"Ad group ID","type":"string"},"adgroup_name":{"description":"Ad group name","type":"string"},"advertiser_id":{"description":"Advertiser account ID","type":"string"},"advertiser_name":{"description":"Advertiser account name","type":"string"},"bid_price":{"description":"Bid","type":"number"},"budget":{"description":"Budget amount","type":"number"},"campaign_id":{"description":"Campaign ID","type":"string"},"campaign_name":{"description":"Campaign name","type":"string"},"currency":{"description":"Currency","type":"string"},"data_items":{"description":"Performance data","items":{"type":"object"},"type":"array"},"images":{"description":"Image file","items":{"properties":{"file_name":{"type":"string"},"url":{"type":"string"}},"type":"object"},"type":"array"},"objective_type_desc":{"description":"Promotion objective description","type":"string"},"operation_status":{"description":"Operation status","type":"string"},"schedule_end_time":{"description":"Delivery end time","type":"string"},"schedule_start_time":{"description":"Delivery start time","type":"string"},"state_desc":{"description":"Status description","type":"string"},"videos":{"description":"Video file","items":{"properties":{"file_name":{"type":"string"},"url":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Ad Detail","tags":["Ads/2.Delivery"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ads/tiktok/ads/insight":{"post":{"description":"Get TikTok ad performance data, including dashboard summary and daily breakdown.","operationId":"trenz-ads-insight-data","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ad_id":{"description":"Ad ID","type":"string"},"end_date":{"description":"Query end date, format YYYY-MM-DD, omit for all-time","type":"string"},"start_date":{"description":"Query start date, format YYYY-MM-DD, omit for all-time","type":"string"}},"required":["ad_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"board_items":{"description":"Dashboard summary","items":{"properties":{"key":{"type":"string"},"label":{"type":"string"},"trend":{"type":"number"},"value":{"type":"number"}},"type":"object"},"type":"array"},"detail_items":{"description":"Daily detail data","items":{"properties":{"date":{"type":"string"},"metrics":{"type":"object"}},"type":"object"},"type":"array"},"metrics":{"description":"Available metric definition list","items":{"properties":{"key":{"type":"string"},"label":{"type":"string"},"unit":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Ad Insight Data","tags":["Ads/2.Delivery"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/ads/tiktok/campaigns":{"post":{"description":"List TikTok ad campaigns with budget, live delivery status, and performance metrics (spend/ROAS/CTR/CPC). Supports filtering by advertiser, campaign type, name, and date range. The advertiser must first be bound in Trenz; use \"Ad Account List\" to find the advertiser_id.","operationId":"trenz-ads-campaigns","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Internal account ID (optional; if omitted, returns per current user's permission scope)","type":"string"},"advertiser_id":{"description":"TikTok advertiser ID","type":"string"},"campaign_type":{"description":"Campaign type: regular / gmv_max","type":"string"},"end_date":{"description":"Performance metrics end date YYYY-MM-DD","type":"string"},"keyword":{"description":"Campaign name fuzzy search","type":"string"},"operation_status":{"description":"Toggle status filter: ENABLE / DISABLE","type":"string"},"page":{"default":1,"description":"Page number, starts from 1, default 1","type":"integer"},"page_size":{"default":20,"description":"Page size, default 20, max 100","maximum":100,"type":"integer"},"start_date":{"description":"Performance metrics start date YYYY-MM-DD","type":"string"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"Campaign list","items":{"properties":{"advertiser_id":{"description":"Advertiser ID","type":"string"},"budget":{"description":"Budget amount","type":"number"},"budget_mode":{"description":"Budget mode: BUDGET_MODE_DAY (daily budget) / BUDGET_MODE_TOTAL (total budget)","type":"string"},"campaign_id":{"description":"Campaign ID (TikTok)","type":"string"},"campaign_name":{"description":"Campaign name","type":"string"},"campaign_type":{"description":"Campaign type: REGULAR / GMV_MAX","type":"string"},"clicks":{"description":"Clicks","type":"integer"},"conversion_rate":{"description":"Conversion rate","type":"number"},"conversions":{"description":"Conversions","type":"integer"},"cost_per_conversion":{"description":"Conversion cost","type":"number"},"cpa":{"description":"Conversion cost (CPA)","type":"number"},"cpc":{"description":"Cost per click (CPC)","type":"number"},"cpm":{"description":"Cost per mille (CPM)","type":"number"},"ctr":{"description":"CTR","type":"number"},"currency":{"description":"Currency code","type":"string"},"impressions":{"description":"Impressions","type":"integer"},"is_cbo":{"description":"Whether campaign budget optimization (CBO) is enabled","type":"boolean"},"objective_type":{"description":"Promotion objective, e.g. LEAD_GENERATION / TRAFFIC / PRODUCT_SALES","type":"string"},"offsite_project_id":{"description":"Associated Amazon off-site Project ID (off-site campaigns only)","type":"integer"},"offsite_project_name":{"description":"Associated off-site Project name","type":"string"},"operation_status":{"description":"Toggle status: ENABLE / DISABLE / DELETE","type":"string"},"orders":{"description":"Order count (in-store purchase count)","type":"integer"},"report_date":{"description":"Latest report date YYYY-MM-DD","type":"string"},"roas":{"description":"Paid ROAS","type":"number"},"secondary_status":{"description":"Actual delivery status (authoritative for the badge): CAMPAIGN_STATUS_ENABLE (delivering) / _DISABLE (paused) / _BUDGET_EXCEED (budget exceeded) / _ADVERTISER_AUDIT_DENY (audit rejected), etc.","type":"string"},"spend":{"description":"Spend","type":"number"},"total_onsite_shopping_amount":{"description":"Total in-store shopping amount (gross revenue)","type":"number"}},"type":"object"},"type":"array"},"page_info":{"description":"Pagination info","properties":{"page":{"description":"Current page number","type":"integer"},"page_size":{"description":"Page size","type":"integer"},"total_number":{"description":"Total count","type":"integer"},"total_page":{"description":"Total pages","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Campaign List","tags":["Ads/2.Delivery"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.ads.read"}},"/open/v1/agent/chat":{"post":{"description":"Call the AI conversational agent and receive a Server-Sent Events (SSE) stream. **The gateway entry costs 0 credits**; the real charge is settled per output token internally by the agent (see \"Billing\").\n\n**Protocol** — The response is a chunked SSE stream (**not** a single JSON payload). Each event is an `event:` line + a `data:` line + one blank line, per the SSE spec:\n\n```text\nevent: \u003cevent_type\u003e\ndata: \u003cJSON object\u003e\n\n```\n\n- The `data` line is standard JSON; non-ASCII characters are `\\uXXXX`-escaped. Read each `data:` line and JSON-parse it to recover the values.\n- Every event carries a monotonically increasing `seq`; process events in `seq` order, and stitch `content` text fragments by `seq` to reconstruct the full reply.\n- The stream interleaves heartbeat comment lines `: ping - \u003ctimestamp\u003e` (starting with `:`, a valid SSE comment). These are **not events — ignore them**; they only keep the long-lived connection alive.\n\n**Billing** — AI conversation is billed per **output token**, settled internally by the agent (not at the gateway entry):\n\n| codename | description | price (per output token) |\n|---|---|---|\n| `core` | Platform **default** model, strongest overall | about **$166.70 / 1M** ($0.167 / 1K) |\n\n- **Only output tokens are billed; input and cache read / write are all free.** The per-token rate looks high precisely because of this — cost is folded into output only: a turn's input (system prompt + tool results + history, often tens of thousands up to 100K+ tokens, much of it served from cache) usually far exceeds the output, yet **none of it is billed**, so the all-in cost comes out lower.\n- Capabilities triggered during the conversation (video / image generation) are billed **separately** per their async-task rules.\n- When credits hit 0 the **current turn completes**; the next request is rejected (surfaced in-stream as `event: error`, `code: INSUFFICIENT_CREDITS`).\n\n**model parameter** — Opaque codename. Trenz exposes a single model, `core` (default). Empty / omitted → `core`; an invalid value silently falls back to `core`.\n\n**attachments parameter** — Object-storage references (product images / model reference images / videos uploaded by the user). Each must include `os_bucket` + `os_key`; those two alone are enough for downstream image / video tools to reference by key. For direct LLM fetch (e.g. `recognize_image`) provide a pre-signed `url` (open-platform callers must sign it themselves). See the request body schema and example.\n\n**Inline XML tags in the assistant text** — Beyond Markdown, the reconstructed `content` text inlines the following tags, and they **may be split across multiple `content` events** — accumulate the full text (by `seq`) before parsing:\n\n| tag | form | meaning |\n|---|---|---|\n| `\u003creport\u003e` | paired | The core artifact: an analysis report; title attr is the title, body is standard Markdown, render in a dedicated panel |\n| `\u003centity\u003e` | self-closing | Entity reference (product / creator / shop / video, etc.); type / id etc. in attributes |\n| `\u003cchart\u003e` | paired | In-report chart; type (bar/line/pie), title attrs, body is JSON, data is self-contained |\n| `\u003ctask-result\u003e` | self-closing | Image / video generation result; result_type (image/video), image_url in attributes |\n| `\u003cvideo-scripts\u003e` | paired | Video script options; body is a JSON array, each item has `scenes` |\n| `\u003cselect\u003e` | paired | A choice control the user must answer; always outside `\u003c/report\u003e` |\n| `\u003csuggestions\u003e` | paired | Informational follow-up suggestions (Markdown list), does not pause the turn |\n| `\u003cconnect\u003e` | self-closing | OAuth authorization button; platform attr specifies the platform |\n\n- `\u003creport\u003e` — usually one per turn; body is Markdown, extract and render as the \"report\". The trailing `\u003cselect\u003e` / `\u003csuggestions\u003e` sit outside the report and must be extracted separately. The full report text is already in this turn's `content` stream — no extra fetch needed.\n\n### How to extract the report from the stream\n\nThe full report is already in the `content` event stream — **no extra endpoint needed**. Three steps:\n\n1. **Accumulate text**: collect `data.text` from every `event: content` into the full text (content is pushed in `seq` order; concatenating in arrival order is fine).\n2. **Wait for close**: a report is long and spans multiple `content` chunks; the simplest approach is to extract once after `event: done` (for streaming render, wait until `\u003c/report\u003e` appears).\n3. **Regex extract**: pull the title and body of `\u003creport\u003e` (the body is standard Markdown — hand it straight to your Markdown renderer).\n\n```js\nlet full = \"\"\nes.addEventListener(\"content\", e =\u003e { full += JSON.parse(e.data).text })\nes.addEventListener(\"done\", () =\u003e {\n  const m = full.match(/\u003creport\\s+[^\u003e]*\u003e([\\s\\S]*?)\u003c\\/report\u003e/)\n  if (m) {\n    const title    = m[0].match(/title=\"([^\"]*)\"/)?.[1] ?? \"\"\n    const markdown = m[1].trim()   // report body (Markdown)\n    renderReport(title, markdown)  // render in a dedicated panel\n  }\n}, { once: true })\n```\n\nThe report body may inline `\u003centity\u003e` / `\u003cchart\u003e` tags — post-process per the tag descriptions above; the remaining plain text (outside `\u003creport\u003e`) is the chat-bubble content.\n\nThe full report text comes from the `content` stream (the method above); to merely reference this turn's report, `event: done`'s `report_ids` already provides the persisted report ids — no need to parse them out of the full text.\n\n- `\u003cselect\u003e` — requires a user choice; when present, that turn's `event: done` reports `stop_reason: \"awaiting_user_input\"` (vs. `\"end_turn\"`). Format:\n\n```xml\n\u003cselect id=\"choice_xxx\" question=\"What would you like to do?\" multi=\"false\"\u003e\n  \u003coption value=\"option_a\"\u003eDisplay text A\u003c/option\u003e\n  \u003coption value=\"option_b\"\u003eDisplay text B\u003c/option\u003e\n\u003c/select\u003e\n```\n\n  Handling: render a selection UI (a `multi=\"true\"` attribute means multi-select) → POST the chosen option's **`value` attribute** (not the display text) as the next request's `message` (same `session_id`).\n\n- `\u003csuggestions\u003e` — informational follow-up suggestions (a Markdown list); does **not** pause the conversation (`stop_reason` stays `end_turn`). Render as clickable suggestions; on click, send that item's text as the next `message`.\n\n- `\u003centity\u003e` — the tag is only a *reference*: it carries no name / image / metrics, just `type` / `id` / `region` / `platform`. To render a rich card, fetch by `id` from the matching open-platform detail endpoint (product / creator / shop / video each have their own). `category` and sourcing entities (`platform=\"1688\"` / `\"web\"`) already carry their info in attributes — no fetch needed. **Detail endpoints are billed per call**; a report often contains many entities, so lazy-load and cache by id rather than fetching all at once.\n\n- `\u003cchart\u003e` — `type`: `bar` (comparison) / `line` (trend) / `pie` (share); `title` is required. Body is a JSON array — the first string field is the x-axis, the first numeric field is the y-axis (if an object has multiple numeric fields, only the first is rendered, not stacked).\n\n**Async task hand-off** — When the agent triggers a long-running capability (video / image generation), it emits an `event: task` (with a `task_id`), also listed in `event: done`'s `pending_tasks`. Poll the final result via `GET /open/v1/tasks/{task_id}`.","operationId":"agentChat","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"attachments":[{"media_type":"image/jpeg","name":"product.jpg","os_bucket":"trenz-uploads","os_key":"u/123/2026-05/product_xxx.jpg"},{"media_type":"model","name":"model_reference.jpg","os_bucket":"trenz-uploads","os_key":"u/123/2026-05/model_yyy.jpg"}],"message":"Generate a product video from the images I just uploaded, shown worn by the model","model":"core","session_id":"454bb2c9-f972-4371-8525-d26cda19eedc"},"schema":{"properties":{"attachments":{"description":"Optional. Object-storage references (images / model reference images / videos). Each must include `os_bucket` + `os_key`.","items":{"properties":{"media_type":{"description":"Optional, defaults to `image/jpeg`. Allowed: `image/png`, `image/jpeg`, `video/mp4`, `model` (special: a fashion model reference image, routed to the product-video tool's `model_images` argument rather than `images`).","type":"string"},"name":{"description":"Optional. Filename — a semantic label for the LLM.","type":"string"},"os_bucket":{"description":"Required. Object-storage bucket name (e.g. `trenz-uploads`).","type":"string"},"os_key":{"description":"Required. Object-storage object key (e.g. `u/123/2026-05/product_xxx.jpg`).","type":"string"},"url":{"description":"Optional. Pre-signed URL (for direct LLM fetch, e.g. `recognize_image`). Open-platform callers must sign it themselves; `os_bucket` + `os_key` alone is enough for downstream tools.","type":"string"}},"required":["os_bucket","os_key"],"type":"object"},"type":"array"},"message":{"description":"User message content. When responding to a `\u003cselect\u003e` widget from the prior turn, send the chosen option's `value` attribute as the message text.","type":"string"},"model":{"description":"Optional. Model codename: `core` (default, ~$166.70/1M output tokens). Empty = `core`.","enum":["core"],"type":"string"},"session_id":{"description":"Optional. Continue an existing chat session. Omit to start a new session; the response's `event: init` payload includes the assigned `session_id`.","format":"uuid","type":"string"}},"required":["message"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"text/event-stream":{"example":"event: init\ndata: {\"session_id\": \"c3f1e8a2-7b14-4f9d-8c3a-1d4e5f6a7b8c\", \"agent_id\": \"trenzer\", \"estimated_seconds\": 5}\n\nevent: content\ndata: {\"text\": \"\\u597d\\u7684\\uff0c\\u6b63\\u5728\\u4e3a\\u4f60\\u751f\\u6210\\u4ea7\\u54c1\\u89c6\\u9891\\u3002\", \"seq\": 1}\n\nevent: tool\ndata: {\"name\": \"submit_product_video\", \"status\": \"calling\", \"display_name\": \"\\u4ea7\\u54c1\\u89c6\\u9891\\u751f\\u6210\", \"seq\": 2}\n\nevent: tool\ndata: {\"name\": \"submit_product_video\", \"status\": \"done\", \"duration_ms\": 412, \"summary\": \"\\u4efb\\u52a1\\u5df2\\u63d0\\u4ea4\", \"seq\": 3}\n\nevent: task\ndata: {\"task_id\": \"9f8e7d6c-5b4a-3c2d-1e0f-a1b2c3d4e5f6\", \"tool_name\": \"submit_product_video\", \"display_name\": \"\\u4ea7\\u54c1\\u89c6\\u9891\\u751f\\u6210\", \"seq\": 4}\n\nevent: done\ndata: {\"stop_reason\": \"end_turn\", \"model\": \"core\", \"usage\": {\"input_tokens\": 142, \"output_tokens\": 38}, \"pending_tasks\": [{\"task_id\": \"9f8e7d6c-5b4a-3c2d-1e0f-a1b2c3d4e5f6\", \"tool_name\": \"submit_product_video\"}], \"report_ids\": [], \"message_id\": \"a7b8c9d0-1234-5678-9abc-def012345678\", \"seq\": 5}\n","schema":{"description":"Server-Sent Events stream. The HTTP response body is a sequence of events:\n\n    event: \u003cevent_type\u003e\n    data: \u003cJSON object\u003e\n    (blank line)\n\n`data` is standard JSON with non-ASCII `\\uXXXX`-escaped. **Event types**:\n\n- `init` — Stream start (always first).\n    `data: { session_id: string, agent_id: string, estimated_seconds?: int }`\n\n- `agent` — Switched to a specialist agent (e.g. `market-analyst`); status hint only.\n    `data: { agent_id: string, seq: int }`\n\n- `content` — Streamed assistant text (zero or more).\n    `data: { text: string, seq: int }`\n\n  Note: text may contain inline XML tags (`\u003creport\u003e`, `\u003centity\u003e`, `\u003cchart\u003e`, `\u003ctask-result\u003e`, `\u003cvideo-scripts\u003e`, `\u003cselect\u003e`, `\u003csuggestions\u003e`, `\u003cconnect\u003e`) and may be split across multiple content events — accumulate the full text (by `seq`) before parsing (see the operation description for each tag's semantics).\n\n- `tool` — Tool call lifecycle event (zero or more).\n    `data: { name: string, status: \"calling\" | \"done\" | \"error\", display_name?: string, summary?: string, duration_ms?: int, seq: int }`\n\n- `task` — An async task was created (long-running capability, e.g. video / image generation). Poll it via `GET /open/v1/tasks/{task_id}`.\n    `data: { task_id: string, tool_name: string, display_name?: string, seq: int }`\n\n- `done` — Stream end (always last on successful completion).\n    `data: { stop_reason: string, model?: string, usage?: { input_tokens: int, output_tokens: int }, pending_tasks?: array, report_ids?: array, message_id?: string, seq?: int }`\n\n    Note: `usage` here is **LLM token counts** (the billing dimension, based on `output_tokens`), distinct from the HTTP envelope's `usage.credits_cost` / `usage.credits_balance`. `model` echoes the codename used for this turn. `report_ids` are the report ids generated / updated this turn (already server-persisted); the full report text is in the `content` stream, so this does not imply a separate fetch.\n\n    `stop_reason` values:\n    - `end_turn` — Turn complete.\n    - `awaiting_user_input` — Turn paused; `content` text contains a `\u003cselect\u003e` widget requiring a user reply.\n    - `max_tokens` — LLM token budget exhausted; response truncated.\n    - `max_turns` — Reached the per-request maximum agent turn limit.\n    - `error` — Generation failed (detail typically also surfaces as a preceding `event: error`).\n    - `abort` — Client closed the connection or upstream aborted.\n\n- `error` — In-stream error event (may appear before or instead of `done`).\n    `data: { message: string, code?: string }`\n    Common `code`: `INSUFFICIENT_CREDITS` (balance is 0).\n\n**Keep-alive** — The stream periodically emits SSE comment lines starting with `:` (e.g. `: ping - \u003ctimestamp\u003e`, roughly every 15s). These are standard SSE comments (not events); clients must ignore them.\n\n**Stream termination** — Stream ends after `done` or `error` (no recovery path). Connection close is definitive.\n\n**Session continuation** — Pass the `session_id` from `init` in the next request. Omitting `session_id` always starts a new session.","type":"string"}}},"description":"SSE event stream (agent response)."},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Stream AI agent response (Server-Sent Events)","tags":["Trenz Agent/1.Chat"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/ai/gpt-image-2/image/generation":{"post":{"description":"GPT-Image-2 AI image generation (powered by OpenAI GPT-Image-2), with reference-image guidance.\n\n\u003e 💡 **About reference images**\n\u003e\n\u003e Simply pass publicly accessible image URLs via the `images` field. This endpoint already wraps the upstream asset-library compliance flow internally — callers do NOT need to invoke the Asset Library API separately.\n\nAsync endpoint, returns `task_id`. Use `GET /open/v1/tasks/{task_id}` to poll task status and result.","operationId":"trenz-ai-gpt-image-2-generate","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"function_type":{"default":"general_edit","description":"Function type: general_edit, ai_clothing, product_image, digital_avatar, handheld_product","enum":["general_edit","ai_clothing","product_image","digital_avatar","handheld_product"],"type":"string"},"image_size":{"default":"1K","description":"Output image resolution","enum":["1K","2K","4K"],"type":"string"},"images":{"description":"Reference image list (recommended unified input field)","items":{"properties":{"url":{"description":"Image URL (any publicly accessible image link)","type":"string"}},"type":"object"},"type":"array"},"prompt":{"description":"Image generation prompt, 1-5000 characters","type":"string"},"ratio":{"default":"9:16","description":"Output image aspect ratio","enum":["1:1","9:16","16:9"],"type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":20}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"Async task ID for status polling","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"GPT-Image-2 Image Generation","tags":["Content/2.AI Image"],"x-billing-mode":"async_on_complete","x-coin-cost":20,"x-pricing":{"default_quantity":1,"default_tier":"1K","fallback_coin_cost":20,"mode":"per_unit","quantity_param":"","tier_param":"image_size","unit_price_map":{"1K":15,"2K":15,"4K":20}},"x-scope":"trenz.ai_image.write"}},"/open/v1/ai/nanobanana/image/generation":{"post":{"description":"Nanobanana AI image generation (powered by Google Gemini multimodal models with SWRR multi-provider dispatch), with reference-image guidance.\n\n\u003e 💡 **About reference images**\n\u003e\n\u003e Simply pass publicly accessible image URLs via the `images` field. This endpoint already wraps the upstream asset-library compliance flow internally — callers do NOT need to invoke the Asset Library API separately.\n\nAsync endpoint, returns `task_id`. Use `GET /open/v1/tasks/{task_id}` to poll task status and result.","operationId":"trenz-ai-nanobanana-generate","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"function_type":{"default":"general_edit","description":"Function type: general_edit, ai_clothing, product_image, digital_avatar, handheld_product","enum":["general_edit","ai_clothing","product_image","digital_avatar","handheld_product"],"type":"string"},"image_size":{"default":"1K","description":"Output image resolution","enum":["1K","2K","4K"],"type":"string"},"images":{"description":"Reference image list (recommended unified input field)","items":{"properties":{"url":{"description":"Image URL (any publicly accessible image link)","type":"string"}},"type":"object"},"type":"array"},"prompt":{"description":"Image generation prompt, 1-5000 characters","type":"string"},"ratio":{"default":"9:16","description":"Output image aspect ratio","enum":["1:1","9:16","16:9"],"type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":20}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"Async task ID for status polling","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Nanobanana Image Generation","tags":["Content/2.AI Image"],"x-billing-mode":"async_on_complete","x-coin-cost":20,"x-pricing":{"default_quantity":1,"default_tier":"1K","fallback_coin_cost":20,"mode":"per_unit","quantity_param":"","tier_param":"image_size","unit_price_map":{"1K":15,"2K":15,"4K":20}},"x-scope":"trenz.ai_image.write"}},"/open/v1/ai/products/review-analysis":{"post":{"description":"AI analysis of product user reviews.\n\nAsync endpoint, returns `task_id`. Use `GET /open/v1/tasks/{task_id}` to poll task status and result.","operationId":"trenz-product-review-analysis","parameters":[{"description":"Country code","in":"query","name":"country_code","schema":{"default":"us","type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"is_regenerate":{"default":false,"description":"Whether to force re-analysis","type":"boolean"},"product_id":{"description":"Product ID","type":"string"}},"required":["product_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":20}},"schema":{"properties":{"data":{"properties":{"product_id":{"description":"Product ID","type":"string"},"task_id":{"description":"Async task ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Product Review Analysis","tags":["Content/3.AI Copywriting"],"x-billing-mode":"async_on_complete","x-coin-cost":20,"x-scope":"trenz.ai.write"}},"/open/v1/ai/sd-pro-fast/video/generation":{"post":{"description":"SeeDance2.0 Fast AI video generation with multi-image, reference video/audio, frame mode and other advanced features; faster generation.\n\n\u003e 💡 **Real-person reference images / videos**\n\u003e\n\u003e The upstream \"Asset Library API\" is used for compliance verification of real-person images / videos.\n\u003e\n\u003e **🎯 This endpoint already wraps that flow internally — callers do NOT need to invoke the Asset Library API separately.**\n\u003e\n\u003e Simply pass publicly accessible image / video URLs via the `images` or `reference_videos` fields.\n\nAsync endpoint, returns `task_id`. Use `GET /open/v1/tasks/{task_id}` to poll task status and result.","operationId":"trenz-ai-sd-pro-fast-generate","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"aspect_ratio":{"default":"9:16","enum":["9:16","16:9","1:1","4:3","3:4","21:9"],"type":"string"},"audio":{"default":true,"type":"boolean"},"country_code":{"default":"us","type":"string"},"duration":{"default":5,"maximum":15,"minimum":4,"type":"integer"},"images":{"description":"Multiple reference image list","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"language":{"type":"string"},"prompt":{"description":"Video generation prompt, 1-5000 characters","type":"string"},"reference_audios":{"description":"Reference audio list","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"reference_videos":{"description":"Reference video list","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"resolution":{"default":"720p","enum":["720p"],"type":"string"},"role_mode":{"default":"reference","enum":["reference","frame"],"type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":300}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"Async task ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"SeeDance2.0 Pro Fast Video Generation","tags":["Content/1.AI Video"],"x-billing-mode":"async_on_complete","x-coin-cost":300,"x-pricing":{"default_quantity":5,"default_tier":"720p","fallback_coin_cost":300,"mode":"per_unit","quantity_param":"duration","tier_param":"resolution","unit_price_map":{"720p":20}},"x-scope":"trenz.ai_video.write"}},"/open/v1/ai/sd-pro/video/generation":{"post":{"description":"SeeDance2.0 Pro AI video generation with multi-image, reference video/audio, frame mode and other advanced features.\n\n\u003e 💡 **Real-person reference images / videos**\n\u003e\n\u003e The upstream \"Asset Library API\" is used for compliance verification of real-person images / videos.\n\u003e\n\u003e **🎯 This endpoint already wraps that flow internally — callers do NOT need to invoke the Asset Library API separately.**\n\u003e\n\u003e Simply pass publicly accessible image / video URLs via the `images` or `reference_videos` fields.\n\nAsync endpoint, returns `task_id`. Use `GET /open/v1/tasks/{task_id}` to poll task status and result.","operationId":"trenz-ai-sd-pro-generate","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"aspect_ratio":{"default":"9:16","enum":["9:16","16:9","1:1","4:3","3:4","21:9"],"type":"string"},"audio":{"default":true,"type":"boolean"},"country_code":{"default":"us","type":"string"},"duration":{"default":5,"maximum":15,"minimum":4,"type":"integer"},"images":{"description":"Multiple reference image list","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"language":{"type":"string"},"prompt":{"description":"Video generation prompt, 1-5000 characters","type":"string"},"reference_audios":{"description":"Reference audio list","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"reference_videos":{"description":"Reference video list","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"resolution":{"default":"720p","enum":["720p","1080p"],"type":"string"},"role_mode":{"default":"reference","enum":["reference","frame"],"type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":450}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"Async task ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"SeeDance2.0 Video Generation","tags":["Content/1.AI Video"],"x-billing-mode":"async_on_complete","x-coin-cost":450,"x-pricing":{"default_quantity":5,"default_tier":"720p","fallback_coin_cost":450,"mode":"per_unit","quantity_param":"duration","tier_param":"resolution","unit_price_map":{"1080p":45,"720p":30}},"x-scope":"trenz.ai_video.write"}},"/open/v1/ai/videos/grok/generate":{"post":{"description":"Grok 1.5 video generation, supporting both text-to-video and image-to-video. Duration must be 6, 10 or 15 seconds: 6/10s work without a reference image (text-to-video); duration=15 requires a reference image. Output resolution is 720p; 9:16 and 16:9 aspect ratios are supported.\n\nAsync endpoint, returns `task_id`. Use `GET /open/v1/tasks/{task_id}` to poll task status and result.","operationId":"trenz-ai-grok-generate","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"aspect_ratio":{"default":"9:16","description":"Aspect ratio","enum":["9:16","16:9"],"type":"string"},"duration":{"default":6,"description":"Video duration in seconds; only 6, 10 or 15 are supported. 6/10s work without a reference image (text-to-video); duration=15 requires a reference image","enum":[6,10,15],"type":"integer"},"image":{"description":"Image info (reference image for image-to-video; optional for 6/10s — text-to-video, required for 15s. Click to expand for details)","properties":{"url":{"description":"Image URL (any publicly accessible image URL is supported)","type":"string"}},"type":"object"},"language":{"default":"default","description":"Language","type":"string"},"prompt":{"description":"Video generation prompt","type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":210}},"schema":{"properties":{"data":{"properties":{"job_id":{"description":"Async task ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Grok Video Generation","tags":["Content/1.AI Video"],"x-billing-mode":"async_on_complete","x-coin-cost":210,"x-pricing":{"default_quantity":6,"default_tier":"_default","fallback_coin_cost":210,"mode":"per_unit","quantity_param":"duration","tier_param":"","unit_price_map":{"_default":15}},"x-scope":"trenz.ai.write"}},"/open/v1/ai/videos/happyhorse/generate":{"post":{"description":"Happy Horse AI Video Generation\n\nAsync endpoint, returns `task_id`. Use `GET /open/v1/tasks/{task_id}` to poll task status and result.","operationId":"trenz-ai-happyhorse-generate","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"aspect_ratio":{"default":"9:16","enum":["9:16","16:9","1:1","4:3","3:4"],"type":"string"},"duration":{"default":5,"maximum":15,"minimum":3,"type":"integer"},"images":{"description":"Multiple reference image list，max 5 images","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"language":{"default":"default","type":"string"},"prompt":{"description":"Video generation prompt","type":"string"},"resolution":{"default":"720p","enum":["720p","1080p"],"type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":675}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"Async task ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Happy Horse Video Generation","tags":["Content/1.AI Video"],"x-billing-mode":"async_on_complete","x-coin-cost":675,"x-pricing":{"default_quantity":5,"default_tier":"720p","fallback_coin_cost":675,"mode":"per_unit","quantity_param":"duration","tier_param":"resolution","unit_price_map":{"1080p":45,"720p":18}},"x-scope":"trenz.ai.write"}},"/open/v1/ai/videos/scripts/breakdown-v2":{"post":{"description":"Structured breakdown of a video script (V2, enhanced).\n\nAsync endpoint, returns `task_id`. Use `GET /open/v1/tasks/{task_id}` to poll task status and result.","operationId":"trenz-video-scripts-breakdown-v2","parameters":[{"description":"Language","in":"query","name":"language","schema":{"default":"en","type":"string"}},{"description":"Country code","in":"query","name":"country_code","schema":{"default":"us","type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"is_regenerate":{"default":false,"description":"Whether to force regeneration","type":"boolean"},"video_id":{"description":"Video ID","type":"string"}},"required":["video_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":20}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"Async task ID","type":"string"},"video_id":{"description":"Video ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Video Script Breakdown V2","tags":["Content/4.AI Analysis"],"x-billing-mode":"async_on_complete","x-coin-cost":20,"x-scope":"trenz.ai.write"}},"/open/v1/ai/videos/veo3/generate":{"post":{"description":"Veo 3.1-model video generation with multi-image input support.\n\nAsync endpoint, returns `task_id`. Use `GET /open/v1/tasks/{task_id}` to poll task status and result.","operationId":"trenz-ai-veo3-generate","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"aspect_ratio":{"default":"portrait","description":"Video ratio","type":"string"},"duration":{"default":8,"description":"Video duration (seconds)","enum":[5,8],"type":"integer"},"image":{"description":"Single image (optional, legacy format, click to expand for details)","properties":{"url":{"description":"Image URL (any publicly accessible image URL is supported)","type":"string"}},"type":"object"},"images":{"description":"Image info array (optional, multi-image)","items":{"properties":{"url":{"description":"Image URL (any publicly accessible image URL is supported)","type":"string"}},"type":"object"},"type":"array"},"language":{"default":"default","description":"Language","type":"string"},"prompt":{"description":"Video generation prompt","type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":210}},"schema":{"properties":{"data":{"properties":{"job_id":{"description":"Async task ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Veo3 Video Generation","tags":["Content/1.AI Video"],"x-billing-mode":"async_on_complete","x-coin-cost":210,"x-pricing":{"default_quantity":8,"default_tier":"_default","fallback_coin_cost":210,"mode":"per_unit","quantity_param":"duration","tier_param":"","unit_price_map":{"_default":15}},"x-scope":"trenz.ai.write"}},"/open/v1/ai/videos/wan26/generate":{"post":{"description":"Wan2.6-model image-to-video generation, supporting 720p / 1080p.\n\nAsync endpoint, returns `task_id`. Use `GET /open/v1/tasks/{task_id}` to poll task status and result.","operationId":"trenz-ai-wan26-generate","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"duration":{"default":15,"description":"Video duration (seconds)","enum":[5,10,15],"type":"integer"},"image":{"description":"Image info (required, image-to-video, click to expand for details)","properties":{"url":{"description":"Image URL (any publicly accessible image URL is supported)","type":"string"}},"type":"object"},"language":{"default":"default","description":"Language","type":"string"},"prompt":{"description":"Video generation prompt","type":"string"},"resolution":{"default":"720p","description":"Video resolution","enum":["720p","1080p"],"type":"string"}},"required":["image","prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":210}},"schema":{"properties":{"data":{"properties":{"job_id":{"description":"Async task ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Wan2.6 Video Generation","tags":["Content/1.AI Video"],"x-billing-mode":"async_on_complete","x-coin-cost":210,"x-pricing":{"default_quantity":15,"default_tier":"720p","fallback_coin_cost":210,"mode":"per_unit","quantity_param":"duration","tier_param":"resolution","unit_price_map":{"1080p":15,"720p":15}},"x-scope":"trenz.ai.write"}},"/open/v1/auth/verify":{"get":{"description":"Query basic account information for the current API Key: user / app, pricing tier, credits balance and account status. Free endpoint — does not consume credits.","operationId":"auth-verify","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"app_id":1024,"credits_balance":12450,"status":"active","tier":"payg","user_id":"u_abc123"},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"app_id":{"description":"Application ID","format":"int64","type":"integer"},"credits_balance":{"description":"Remaining credits balance","format":"int64","type":"integer"},"status":{"description":"Account status: `active` / `suspended` / `revoked` / `deleted`","type":"string"},"tier":{"description":"Pricing tier (defined by the control plane, e.g. `payg` / `tenant_basic`)","type":"string"},"user_id":{"description":"User ID","type":"string"}},"required":["user_id","app_id","tier","credits_balance","status"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Query account status and credits balance","tags":["Account"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/creatives/search":{"get":{"description":"Search TikTok ad creatives / video creatives, with filters and sort on category, region, AIGC flag and more.","operationId":"trenz-creatives-search","parameters":[{"description":"Search keyword","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"Creative category ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Whether has linked products","example":true,"in":"query","name":"has_product","required":false,"schema":{"type":"boolean"}},{"description":"Whether is sponsored content","example":false,"in":"query","name":"is_sponsored","required":false,"schema":{"type":"boolean"}},{"description":"Whether is AI-generated content","example":false,"in":"query","name":"is_aigc","required":false,"schema":{"type":"boolean"}},{"description":"Sort, format: field:asc|desc. Allowed: engagement, gmv, gpm, likes, plays. Default: gmv:desc","example":"gmv:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv:desc","enum":["engagement","gmv","gpm","likes","plays"],"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"author_nickname":{"description":"Author name","type":"string"},"author_uid":{"description":"Author user ID","type":"string"},"author_unique_id":{"description":"Author TikTok username","type":"string"},"content_intent":{"description":"Content intent","type":"string"},"content_tag_v2":{"description":"Content tags","items":{"type":"string"},"type":"array"},"country_code":{"description":"Country code","type":"string"},"follower_cnt":{"description":"Follower count","type":"integer"},"id":{"description":"Unique identifier","type":"string"},"is_aigc_video":{"description":"Is AI-generated video","type":"boolean"},"platform":{"description":"Platform","type":"string"},"product_id":{"description":"Product ID","type":"string"},"user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"video_30d_gmv":{"description":"30-day video GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"video_30d_gpm":{"description":"30-day video GPM","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"video_collect_count":{"description":"Save count","type":"integer"},"video_comment_count":{"description":"Comment count","type":"integer"},"video_date":{"description":"Video date","type":"string"},"video_desc":{"description":"Video description","type":"string"},"video_duration":{"description":"Duration (ms)","type":"integer"},"video_engagement_rate":{"description":"Engagement rate (0-1)","type":"number"},"video_gmv":{"description":"Video GMV","type":"string"},"video_id":{"description":"Video ID","type":"string"},"video_launch_time":{"description":"Published at (ms timestamp)","type":"integer"},"video_like_count":{"description":"Like count","type":"integer"},"video_play_count":{"description":"View count","type":"integer"},"video_share_count":{"description":"Share count","type":"integer"},"video_total_gmv":{"description":"Video total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"video_total_gpm":{"description":"Video total GPM","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Creative Search","tags":["Data/5.Ads \u0026 Creatives"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.creative.read"}},"/open/v1/creatives/{id}":{"get":{"description":"Get TikTok creative details with video metrics, creator info, linked products, and optional content analysis and embedding.","operationId":"trenz-creative-detail","parameters":[{"description":"Creative video ID","in":"path","name":"entity_id","required":true,"schema":{"type":"string"}},{"description":"Region code","in":"query","name":"country","required":true,"schema":{"enum":["us","th","my","vn","mx","de","fr","it","es","jp","br","gb","ph","sg","id"],"type":"string"}},{"description":"Included sub-resources, comma-separated: analysis,embedding","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Include related resources, comma-separated (values: analysis(Analytics data), embedding(Embedding data))","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"ceiling_price":{"description":"Max price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"commission_rate":{"description":"Commission rate","type":"number"},"country_code":{"description":"Country code","type":"string"},"floor_price":{"description":"Min price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"follower_count":{"description":"Follower count","type":"integer"},"id":{"description":"Unique identifier","type":"string"},"l1_category":{"description":"L1 category","type":"string"},"l2_category":{"description":"L2 category","type":"string"},"l3_category":{"description":"L3 category","type":"string"},"nickname":{"description":"Display name","type":"string"},"product_country_code":{"description":"Product country","type":"string"},"product_id":{"description":"Product ID","type":"string"},"product_images":{"description":"Product images","items":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"type":"array"},"product_launch_time":{"description":"Product listing time (ms timestamp)","type":"integer"},"product_name":{"description":"Product name","type":"string"},"product_rating":{"description":"Product rating (0-5)","type":"number"},"product_status":{"description":"Product status","type":"integer"},"product_total_gmv":{"description":"Product total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"product_total_sold_count":{"description":"Product total sales","type":"integer"},"share_url":{"description":"TikTok share URL","type":"string"},"uid":{"description":"User ID","type":"string"},"unique_id":{"description":"TikTok username","type":"string"},"user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"video_30d_gmv":{"description":"30-day video GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"video_30d_gpm":{"description":"30-day video GPM","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"video_30d_sold_count":{"description":"30-day video sales","type":"integer"},"video_collect_count":{"description":"Save count","type":"integer"},"video_comment_count":{"description":"Comment count","type":"integer"},"video_engagement_rate":{"description":"Engagement rate (0-1)","type":"number"},"video_id":{"description":"Video ID","type":"string"},"video_like_count":{"description":"Like count","type":"integer"},"video_play_count":{"description":"View count","type":"integer"},"video_share_count":{"description":"Share count","type":"integer"},"video_total_gmv":{"description":"Video total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Creative Detail","tags":["Data/5.Ads \u0026 Creatives"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.creative.read"}},"/open/v1/creators/rankings/agencies":{"get":{"description":"Query TikTok creator agencies by 30-day GMV, sales, and related-resource performance.","operationId":"trenz-creators-ranking-agencies","parameters":[{"description":"Agency primary product category ID","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Sort as field:asc|desc; fields: avg_commission_rate, creator_count, follower_count, gmv_30d, product_count, seller_count, sold_count_30d, video_count","example":"gmv_30d:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv_30d:desc","type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 10, maximum 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Ranking results with internal field prefixes removed","items":{"additionalProperties":true,"properties":{"id":{"description":"Unique identifier of the ranked entity","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total number of records matching the filters","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Creator Agency Ranking","tags":["Data/2.Creators"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.creators.read"}},"/open/v1/creators/rankings/commercial":{"get":{"description":"Query TikTok creators leading in video and live ecommerce performance for a period.","operationId":"trenz-creators-ranking-commercial","parameters":[{"description":"Statistics date in YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Granularity: daily/0, weekly/1, or monthly/2","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"Creator content category ID","in":"query","name":"creator_category","required":false,"schema":{"type":"string"}},{"description":"Creator aggregated level-1 product category ID","in":"query","name":"product_category","required":false,"schema":{"type":"string"}},{"description":"Sort as field:asc|desc; fields: live_gmv, live_user_count, product_count, total_gmv, video_gmv, video_play_growth","example":"total_gmv:desc","in":"query","name":"sort","required":false,"schema":{"default":"total_gmv:desc","type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 10, maximum 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Ranking results with internal field prefixes removed","items":{"additionalProperties":true,"properties":{"id":{"description":"Unique identifier of the ranked entity","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total number of records matching the filters","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Ecommerce Creator Ranking","tags":["Data/2.Creators"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.creators.read"}},"/open/v1/creators/rankings/growth":{"get":{"description":"Query TikTok creators with the strongest follower growth for a period.","operationId":"trenz-creators-ranking-growth","parameters":[{"description":"Statistics date in YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Granularity: daily/0, weekly/1, or monthly/2","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"Creator content category ID","in":"query","name":"creator_category","required":false,"schema":{"type":"string"}},{"description":"Creator product category ID","in":"query","name":"product_category","required":false,"schema":{"type":"string"}},{"description":"Sort as field:asc|desc; fields: follower_count, new_follower_count, new_follower_rate, video_count","example":"new_follower_count:desc","in":"query","name":"sort","required":false,"schema":{"default":"new_follower_count:desc","type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 10, maximum 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Ranking results with internal field prefixes removed","items":{"additionalProperties":true,"properties":{"id":{"description":"Unique identifier of the ranked entity","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total number of records matching the filters","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Creator Growth Ranking","tags":["Data/2.Creators"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.creators.read"}},"/open/v1/creators/search":{"get":{"description":"Search TikTok creators with multi-dimensional filters on followers, GMV, engagement rate, etc.","operationId":"trenz-creators-search","parameters":[{"description":"Search keyword","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"Creator category ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Min followers","example":10000,"in":"query","name":"min_followers","required":false,"schema":{"type":"number"}},{"description":"Max followers","example":1000000,"in":"query","name":"max_followers","required":false,"schema":{"type":"number"}},{"description":"30-day min GMV (USD)","example":1000,"in":"query","name":"min_gmv_30d","required":false,"schema":{"type":"number"}},{"description":"30-day max GMV (USD)","example":100000,"in":"query","name":"max_gmv_30d","required":false,"schema":{"type":"number"}},{"description":"Min average views","example":1000,"in":"query","name":"min_avg_views","required":false,"schema":{"type":"number"}},{"description":"Max average views","example":100000,"in":"query","name":"max_avg_views","required":false,"schema":{"type":"number"}},{"description":"Min engagement rate (0-1)","example":0.01,"in":"query","name":"min_engagement","required":false,"schema":{"type":"number"}},{"description":"Max engagement rate (0-1)","example":0.1,"in":"query","name":"max_engagement","required":false,"schema":{"type":"number"}},{"description":"Whether has contact info","example":true,"in":"query","name":"has_contact","required":false,"schema":{"type":"boolean"}},{"description":"Sort, format: field:asc|desc. Allowed: avg_views, engagement, follower_growth_7d, followers, gmv_30d, video_gmv_30d. Default: gmv_30d:desc","example":"gmv_30d:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv_30d:desc","enum":["avg_views","engagement","follower_growth_7d","followers","gmv_30d","video_gmv_30d"],"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"account_type":{"description":"Account type","type":"integer"},"author_avg_engagement_rate":{"description":"Avg engagement rate (0-1)","type":"number"},"bio_email":{"description":"Bio email","type":"string"},"category_label":{"description":"Creator category label","type":"string"},"country_code":{"description":"Country code","type":"string"},"ecom_video_avg_play_count":{"description":"Avg e-commerce video views","type":"number"},"facebook_url":{"description":"Facebook URL","type":"string"},"follower_count":{"description":"Follower count","type":"integer"},"follower_count_growth_for_last_7_days":{"description":"7-day follower growth","type":"integer"},"has_live_product":{"description":"Has live commerce","type":"boolean"},"has_shop_product":{"description":"Has shop products","type":"boolean"},"has_video_product":{"description":"Has video commerce","type":"boolean"},"id":{"description":"Unique identifier","type":"string"},"ins_id":{"description":"Instagram ID","type":"string"},"linkedin_url":{"description":"LinkedIn URL","type":"string"},"live_30d_gmv":{"description":"30-day live GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"live_30d_gpm":{"description":"30-day live GPM","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"nickname":{"description":"Display name","type":"string"},"product_category_label_list":{"description":"Product category labels","items":{"type":"string"},"type":"array"},"telegram_url":{"description":"Telegram URL","type":"string"},"total_favorited":{"description":"Total likes received","type":"integer"},"total_video_live_30d_gmv":{"description":"30-day video+live total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"twitter_id":{"description":"Twitter/X ID","type":"string"},"unique_id":{"description":"TikTok username","type":"string"},"user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"user_sell_product_l3_category":{"description":"Selling product L3 categories","items":{"type":"string"},"type":"array"},"video_30d_gmv":{"description":"30-day video GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"video_30d_gpm":{"description":"30-day video GPM","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"video_avg_like_count":{"description":"Avg video likes","type":"number"},"video_avg_play_count":{"description":"Avg video views","type":"number"},"video_total_like_count_to_follower_count_ratio":{"description":"Likes to followers ratio","type":"number"},"whatsapp_url":{"description":"WhatsApp URL","type":"string"},"youtube_channel_id":{"description":"YouTube channel ID","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Creator Search","tags":["Data/2.Creators"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.creators.read"}},"/open/v1/creators/{id}":{"get":{"description":"Get TikTok creator details with video list and shoppable products.","operationId":"trenz-creators-detail","parameters":[{"description":"Creator ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Include related resources, comma-separated (values: channel(Sales Channels), core(Core Metrics), portrait(Audience Profile))","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"bio_email":{"description":"Bio email","type":"string"},"bio_url":{"description":"Bio URL","type":"string"},"category_label":{"description":"Creator category label","type":"string"},"enterprise_verify_reason":{"description":"Enterprise verification","type":"string"},"facebook_url":{"description":"Facebook URL","type":"string"},"has_live_product":{"description":"Has live commerce products","type":"boolean"},"has_shop_product":{"description":"Has shop products","type":"boolean"},"has_video_product":{"description":"Has video commerce products","type":"boolean"},"id":{"description":"Unique identifier","type":"string"},"ins_id":{"description":"Instagram ID","type":"string"},"last_update_time":{"description":"Last updated (ms timestamp)","type":"integer"},"linkedin_url":{"description":"LinkedIn URL","type":"string"},"nickname":{"description":"Display name","type":"string"},"partnered_brand":{"description":"Partnered brands","items":{"properties":{"id":{"description":"Brand ID","type":"string"},"name":{"description":"Brand name","type":"string"}},"type":"object"},"type":"array"},"product_category_label_list":{"description":"Product category labels","items":{"type":"string"},"type":"array"},"seller_avatar":{"description":"Shop avatar","type":"string"},"shop_main_category":{"description":"Main category","type":"string"},"shop_name":{"description":"Shop name","type":"string"},"shop_rating":{"description":"Shop rating","type":"string"},"signature":{"description":"Bio description","type":"string"},"telegram_url":{"description":"Telegram URL","type":"string"},"total_gmv":{"description":"Total GMV","type":"string"},"total_sold_count":{"description":"Total units sold","type":"string"},"twitter_id":{"description":"Twitter/X ID","type":"string"},"unique_id":{"description":"TikTok username","type":"string"},"user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"website":{"description":"Website","type":"string"},"wechat":{"description":"WeChat","type":"string"},"whatsapp_url":{"description":"WhatsApp URL","type":"string"},"youtube_channel_id":{"description":"YouTube channel ID","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Creator Detail","tags":["Data/2.Creators"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.creators.read"}},"/open/v1/creators/{id}/lives":{"get":{"description":"","operationId":"trenz-creators-lives","parameters":[{"description":"Creator ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_creator_detail_live_country_code":{"description":"Country code","type":"string"},"tiktok_creator_detail_live_cover":{"description":"Live cover","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_creator_detail_live_end_time":{"description":"End time (ms timestamp)","type":"integer"},"tiktok_creator_detail_live_gmv":{"description":"GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_creator_detail_live_gpm":{"description":"GPM (GMV per 1K views)","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_creator_detail_live_max_user_count":{"description":"Peak viewers","type":"integer"},"tiktok_creator_detail_live_most_product_category_label":{"description":"Main product category","type":"string"},"tiktok_creator_detail_live_new_follow_count":{"description":"New followers","type":"integer"},"tiktok_creator_detail_live_opm":{"description":"OPM (orders per 1K views)","type":"number"},"tiktok_creator_detail_live_product_count":{"description":"Product count","type":"integer"},"tiktok_creator_detail_live_room_id":{"description":"Live room ID","type":"string"},"tiktok_creator_detail_live_room_link":{"description":"Live room URL","type":"string"},"tiktok_creator_detail_live_start_time":{"description":"Start time (ms timestamp)","type":"integer"},"tiktok_creator_detail_live_title":{"description":"Live title","type":"string"},"tiktok_creator_detail_live_total_sold_count":{"description":"Total units sold","type":"integer"},"tiktok_creator_detail_live_total_user":{"description":"Total viewers","type":"integer"},"tiktok_creator_detail_live_user_follower_count":{"description":"User follower count","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Creator Related Lives","tags":["Data/2.Creators"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.creators.read"}},"/open/v1/creators/{id}/products":{"get":{"description":"","operationId":"trenz-creators-products","parameters":[{"description":"Creator ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_creator_detail_by_live":{"description":"Sells via live commerce","type":"boolean"},"tiktok_creator_detail_by_shop":{"description":"Sells via shop","type":"boolean"},"tiktok_creator_detail_by_video":{"description":"Sells via video commerce","type":"boolean"},"tiktok_creator_detail_live_30d_gmv":{"description":"30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_creator_detail_live_30d_sold_count":{"description":"30D Sold Count","type":"integer"},"tiktok_creator_detail_product_country_code":{"description":"Product country","type":"string"},"tiktok_creator_detail_product_id":{"description":"Product ID","type":"string"},"tiktok_creator_detail_product_launch_time":{"description":"Product listing time (ms timestamp)","type":"integer"},"tiktok_creator_detail_total_video_live_30d_gmv":{"description":"Total Video Live 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_creator_detail_total_video_live_30d_sold_count":{"description":"Total Video Live 30D Sold Count","type":"integer"},"tiktok_creator_detail_user_id":{"description":"User ID","type":"string"},"tiktok_creator_detail_video_30d_gmv":{"description":"30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_creator_detail_video_30d_sold_count":{"description":"30D Sold Count","type":"integer"},"tiktok_product_detail_ceiling_price":{"description":"Max price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_commission_rate":{"description":"Commission rate","type":"string"},"tiktok_product_detail_floor_price":{"description":"Min price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_l1_category":{"description":"Level-1 category","type":"string"},"tiktok_product_detail_l2_category":{"description":"Level-2 category","type":"string"},"tiktok_product_detail_l3_category":{"description":"Level-3 category","type":"string"},"tiktok_product_detail_product_images":{"description":"Product images","items":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_name":{"description":"Product name","type":"string"},"tiktok_product_detail_product_rating":{"description":"Product rating (0-5)","type":"number"},"tiktok_product_detail_product_sku_props":{"description":"SKU properties","items":{"properties":{"has_image":{"description":"Has image","type":"boolean"},"prop_id":{"description":"Property ID","type":"string"},"prop_name":{"description":"Property name","type":"string"},"sale_prop_values":{"description":"Property values","items":{"properties":{"image":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"prop_value":{"description":"Property value","type":"string"},"prop_value_id":{"description":"Property value ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_skus":{"description":"SKU list","items":{"properties":{"is_hot":{"description":"Is hot selling","type":"boolean"},"price":{"properties":{"discount":{"description":"Discount info","type":"string"},"original_price":{"description":"Original price","type":"string"},"original_price_value":{"description":"Original price value","type":"string"},"real_price":{"description":"Actual price","type":"number"},"unit_price_desc":{"description":"Unit price description","type":"string"}},"type":"object"},"sale_prop_value_ids":{"description":"Property value ID combination","type":"string"},"sku_id":{"description":"SKU ID","type":"string"},"sku_sale_props":{"description":"SKU properties","items":{"properties":{"prop_id":{"description":"Property ID","type":"string"},"prop_name":{"description":"Property name (e.g. Color)","type":"string"},"prop_value":{"description":"Property value","type":"string"},"prop_value_id":{"description":"Property value ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"Status (1=active)","type":"integer"},"stock":{"description":"Stock","type":"integer"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_status":{"description":"Product status","type":"integer"},"tiktok_product_detail_region":{"description":"Region code","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Creator Products","tags":["Data/2.Creators"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.creators.read"}},"/open/v1/creators/{id}/similar":{"get":{"description":"","operationId":"trenz-creators-similar","parameters":[{"description":"Creator ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_creator_detail_similar_category_label":{"description":"Creator category label","type":"string"},"tiktok_creator_detail_similar_country_code":{"description":"Country code","type":"string"},"tiktok_creator_detail_similar_follower_count":{"description":"Follower count","type":"integer"},"tiktok_creator_detail_similar_nickname":{"description":"Display name","type":"string"},"tiktok_creator_detail_similar_total_video_live_30d_gmv":{"description":"Total Video Live 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_creator_detail_similar_uid":{"description":"User ID","type":"string"},"tiktok_creator_detail_similar_user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Similar Creators","tags":["Data/2.Creators"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.creators.read"}},"/open/v1/creators/{id}/videos":{"get":{"description":"","operationId":"trenz-creators-videos","parameters":[{"description":"Creator ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_creator_detail_is_ad":{"description":"Is advertisement","type":"boolean"},"tiktok_creator_detail_is_aigc_video":{"description":"Is AI-generated video","type":"boolean"},"tiktok_creator_detail_video_30d_gmv":{"description":"30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_creator_detail_video_30d_sold_count":{"description":"30D Sold Count","type":"integer"},"tiktok_creator_detail_video_ad_source":{"description":"Ad source (1=has ad)","type":"string"},"tiktok_creator_detail_video_author_category_label":{"description":"Author category label","type":"string"},"tiktok_creator_detail_video_author_nickname":{"description":"Author display name","type":"string"},"tiktok_creator_detail_video_author_uid":{"description":"Author user ID","type":"string"},"tiktok_creator_detail_video_author_unique_id":{"description":"Author TikTok username","type":"string"},"tiktok_creator_detail_video_collect_count":{"description":"Save count","type":"integer"},"tiktok_creator_detail_video_comment_count":{"description":"Comment count","type":"integer"},"tiktok_creator_detail_video_country_code":{"description":"Country code","type":"string"},"tiktok_creator_detail_video_cover":{"description":"Live cover","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_creator_detail_video_desc":{"description":"Description","type":"string"},"tiktok_creator_detail_video_duration":{"description":"Duration (ms)","type":"integer"},"tiktok_creator_detail_video_engagement_rate":{"description":"Engagement rate (0-1)","type":"number"},"tiktok_creator_detail_video_id":{"description":"Unique identifier","type":"string"},"tiktok_creator_detail_video_launch_time":{"description":"Published at (ms timestamp)","type":"integer"},"tiktok_creator_detail_video_like_count":{"description":"Like count","type":"integer"},"tiktok_creator_detail_video_play_count":{"description":"View count","type":"integer"},"tiktok_creator_detail_video_product_id":{"description":"Product ID","type":"string"},"tiktok_creator_detail_video_product_images":{"description":"Product images","items":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"type":"array"},"tiktok_creator_detail_video_product_l1_category":{"description":"Product L1 Category","type":"string"},"tiktok_creator_detail_video_product_l2_category":{"description":"Product L2 Category","type":"string"},"tiktok_creator_detail_video_product_l3_category":{"description":"Product L3 Category","type":"string"},"tiktok_creator_detail_video_product_title":{"description":"Product title","type":"string"},"tiktok_creator_detail_video_share_count":{"description":"Share count","type":"integer"},"tiktok_creator_detail_video_share_url":{"description":"TikTok share URL","type":"string"},"tiktok_creator_detail_video_total_like_count_to_follower_count_ratio":{"description":"Total likes to followers ratio","type":"number"},"tiktok_creator_detail_video_user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Creator Videos","tags":["Data/2.Creators"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.creators.read"}},"/open/v1/dashboards/categories/heatmap":{"get":{"description":"Query the category heatmap for GMV, units sold, growth rates, and blue-ocean index.","operationId":"trenz-dashboards-categories-heatmap","parameters":[{"description":"Statistics date in YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Granularity: daily/0, weekly/1, or monthly/2","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Heatmap result container","items":{"properties":{"graph":{"description":"Category heatmap tree","items":{"additionalProperties":true,"properties":{"category_data":{"description":"Category metrics (click to expand for field details)","properties":{"interval_blue_ocean_index":{"description":"Blue Ocean Index","type":"number"},"interval_product_count":{"description":"Number of products with sales","type":"number"},"interval_product_gmv":{"description":"GMV","type":"number"},"interval_product_gmv_growth_rate":{"description":"GMV growth rate","type":"number"},"interval_product_sold_count":{"description":"Units sold","type":"number"},"interval_product_sold_count_growth_rate":{"description":"Units-sold growth rate","type":"number"}},"type":"object"},"category_label":{"description":"Category ID","type":"string"},"children":{"description":"Subcategory nodes","items":{"additionalProperties":true,"type":"object"},"type":"array"},"parent_category":{"description":"Parent category ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"total_count":{"description":"Number of result containers","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Category Heatmap","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.products.read"}},"/open/v1/dashboards/categories/metrics":{"get":{"description":"Query category-level GMV, units sold, active products, average price, and creator count.","operationId":"trenz-dashboards-categories-metrics","parameters":[{"description":"Statistics date in YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Granularity: daily/0, weekly/1, or monthly/2","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Core metrics result, typically one item","items":{"properties":{"core_category_label":{"description":"Category ID; all_category when no category filter is applied","type":"string"},"interval_avg_product_price":{"description":"Average product price (click to expand for field details)","properties":{"unit":{"description":"Currency or marketplace unit","type":"string"},"value":{"description":"Monetary value","type":"number"}},"type":"object"},"interval_product_count":{"description":"Number of products with sales","type":"number"},"interval_product_gmv":{"description":"GMV (click to expand for field details)","properties":{"unit":{"description":"Currency or marketplace unit","type":"string"},"value":{"description":"Monetary value","type":"number"}},"type":"object"},"interval_product_sold_count":{"description":"Units sold","type":"number"},"interval_total_related_creator_count":{"description":"Number of related ecommerce creators","type":"number"}},"type":"object"},"type":"array"},"total_count":{"description":"Result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Category Core Metrics","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.products.read"}},"/open/v1/dashboards/products/category-share":{"post":{"description":"Query category GMV values and shares in the product dashboard.","operationId":"trenz-dashboards-products-category-share","parameters":[{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"Ranking or dashboard query filters (click to expand for field details)","properties":{"field_filter":{"description":"Business filters. Use the parent-category key tiktok_product_dashboard_category; omit this field to return top-level categories.","items":{"description":"A single filter condition (click to expand for field details)","properties":{"exclude_values":{"description":"Values to exclude","items":{"type":"string"},"type":"array"},"filter_key":{"description":"hertz_data filter field key","type":"string"},"include_values":{"description":"Values to include","items":{"type":"string"},"type":"array"},"left_date_time":{"description":"Lower bound of the date range, usually in YYYYMMDD format","type":"string"},"left_value":{"description":"Lower bound of the numeric range","type":"number"},"quick_option_name":{"description":"Quick option value, such as a category ID or seller-type option","type":"string"},"right_date_time":{"description":"Upper bound of the date range, usually in YYYYMMDD format","type":"string"},"right_value":{"description":"Upper bound of the numeric range","type":"number"},"value":{"description":"Exact-match value","type":"string"}},"required":["filter_key"],"type":"object"},"type":"array"},"time_filter":{"description":"Statistics period (click to expand for field details)","properties":{"end_date_time":{"description":"End date of the custom date range in YYYYMMDD format","pattern":"^\\d{8}$","type":"string"},"granularity":{"description":"Granularity: 0=daily, 1=weekly, 2=monthly","enum":[0,1,2],"example":0,"type":"integer"},"is_customized":{"description":"Whether to use a custom date range","type":"boolean"},"start_date_time":{"description":"Statistics date in YYYYMMDD format","example":"20260803","pattern":"^\\d{8}$","type":"string"}},"required":["granularity","start_date_time"],"type":"object"}},"required":["time_filter"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"filter_list":{"description":"Category GMV distribution","items":{"properties":{"filter_key":{"description":"Filter field key","type":"string"},"quick_option_list":{"description":"Category list","items":{"additionalProperties":true,"properties":{"children":{"description":"Subcategory distribution","items":{"additionalProperties":true,"type":"object"},"type":"array"},"distribute":{"description":"GMV and share (click to expand for field details)","properties":{"percentage":{"description":"Category GMV share","type":"string"},"value":{"description":"Category GMV","type":"number"}},"type":"object"},"option_id":{"description":"Category ID","type":"string"},"option_name":{"description":"Category name or ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Product Category GMV Share","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.products.read"}},"/open/v1/dashboards/products/metrics":{"get":{"description":"Query product-dashboard GMV, units sold, active products, average price, and creator count.","operationId":"trenz-dashboards-products-metrics","parameters":[{"description":"Statistics date in YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Granularity: daily/0, weekly/1, or monthly/2","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"Product category ID; omit for overall metrics","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Core metrics result, typically one item","items":{"properties":{"core_category_label":{"description":"Category ID; all_category when no category filter is applied","type":"string"},"interval_avg_product_price":{"description":"Average product price (click to expand for field details)","properties":{"unit":{"description":"Currency or marketplace unit","type":"string"},"value":{"description":"Monetary value","type":"number"}},"type":"object"},"interval_product_count":{"description":"Number of products with sales","type":"number"},"interval_product_gmv":{"description":"GMV (click to expand for field details)","properties":{"unit":{"description":"Currency or marketplace unit","type":"string"},"value":{"description":"Monetary value","type":"number"}},"type":"object"},"interval_product_sold_count":{"description":"Units sold","type":"number"},"interval_total_related_creator_count":{"description":"Number of related ecommerce creators","type":"number"}},"type":"object"},"type":"array"},"total_count":{"description":"Result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Product Core Metrics","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.products.read"}},"/open/v1/dashboards/sellers/concentration":{"get":{"description":"Query top sellers and concentration ratios for all, local, overseas, and managed shop types.","operationId":"trenz-dashboards-sellers-concentration","parameters":[{"description":"Statistics date in YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Granularity: daily/0, weekly/1, or monthly/2","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"Product category ID; omit for overall seller concentration","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Seller concentration result, typically one item","items":{"properties":{"all_type_seller_list":{"description":"Top seller list","items":{"additionalProperties":true,"properties":{"concentration_ratio":{"description":"Concentration ratio","type":"number"},"interval_seller_gmv":{"description":"GMV for the selected period (click to expand for field details)","properties":{"unit":{"description":"Currency or marketplace unit","type":"string"},"value":{"description":"Monetary value","type":"number"}},"type":"object"},"interval_seller_sold_count":{"description":"Units sold in the selected period","type":"number"},"rn":{"description":"Rank","type":"number"},"seller_id":{"description":"Seller ID","type":"string"}},"type":"object"},"type":"array"},"category_label":{"description":"Category ID","type":"string"},"local_seller_list":{"description":"Top seller list","items":{"additionalProperties":true,"properties":{"concentration_ratio":{"description":"Concentration ratio","type":"number"},"interval_seller_gmv":{"description":"GMV for the selected period (click to expand for field details)","properties":{"unit":{"description":"Currency or marketplace unit","type":"string"},"value":{"description":"Monetary value","type":"number"}},"type":"object"},"interval_seller_sold_count":{"description":"Units sold in the selected period","type":"number"},"rn":{"description":"Rank","type":"number"},"seller_id":{"description":"Seller ID","type":"string"}},"type":"object"},"type":"array"},"managed_seller_list":{"description":"Top seller list","items":{"additionalProperties":true,"properties":{"concentration_ratio":{"description":"Concentration ratio","type":"number"},"interval_seller_gmv":{"description":"GMV for the selected period (click to expand for field details)","properties":{"unit":{"description":"Currency or marketplace unit","type":"string"},"value":{"description":"Monetary value","type":"number"}},"type":"object"},"interval_seller_sold_count":{"description":"Units sold in the selected period","type":"number"},"rn":{"description":"Rank","type":"number"},"seller_id":{"description":"Seller ID","type":"string"}},"type":"object"},"type":"array"},"overseas_seller_list":{"description":"Top seller list","items":{"additionalProperties":true,"properties":{"concentration_ratio":{"description":"Concentration ratio","type":"number"},"interval_seller_gmv":{"description":"GMV for the selected period (click to expand for field details)","properties":{"unit":{"description":"Currency or marketplace unit","type":"string"},"value":{"description":"Monetary value","type":"number"}},"type":"object"},"interval_seller_sold_count":{"description":"Units sold in the selected period","type":"number"},"rn":{"description":"Rank","type":"number"},"seller_id":{"description":"Seller ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"total_count":{"description":"Result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Seller Concentration","tags":["Data/4.Sellers"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.sellers.read"}},"/open/v1/dashboards/sellers/metrics":{"get":{"description":"Query seller count, average GMV, and GMV shares for local, overseas, and managed shops.","operationId":"trenz-dashboards-sellers-metrics","parameters":[{"description":"Statistics date in YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Granularity: daily/0, weekly/1, or monthly/2","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"Product category ID; omit for overall seller metrics","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Seller core metrics, typically one item","items":{"properties":{"category_label":{"description":"Category ID","type":"string"},"interval_avg_seller_gmv":{"description":"Average GMV per seller (click to expand for field details)","properties":{"unit":{"description":"Currency or marketplace unit","type":"string"},"value":{"description":"Monetary value","type":"number"}},"type":"object"},"interval_local_shop_rate":{"description":"Local seller GMV share","type":"number"},"interval_managed_shop_rate":{"description":"Fully managed seller GMV share","type":"number"},"interval_overseas_shop_rate":{"description":"Overseas seller GMV share","type":"number"},"interval_product_gmv":{"description":"Product GMV (click to expand for field details)","properties":{"unit":{"description":"Currency or marketplace unit","type":"string"},"value":{"description":"Monetary value","type":"number"}},"type":"object"},"interval_product_sold_count":{"description":"Product units sold","type":"number"},"interval_seller_count":{"description":"Number of sellers with sales","type":"number"}},"type":"object"},"type":"array"},"total_count":{"description":"Result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Seller Core Metrics","tags":["Data/4.Sellers"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.sellers.read"}},"/open/v1/lives/search":{"get":{"description":"Search TikTok commerce live streams with filters on sales, GMV, audience count, etc.","operationId":"trenz-lives-search","parameters":[{"description":"Search keyword","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"Streamer category ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Product category ID","example":"100001","in":"query","name":"product_category","required":false,"schema":{"type":"string"}},{"description":"Whether currently live-streaming","example":false,"in":"query","name":"is_living","required":false,"schema":{"type":"boolean"}},{"description":"Whether is a commerce live","example":false,"in":"query","name":"is_commercial","required":false,"schema":{"type":"boolean"}},{"description":"Min sales","example":100,"in":"query","name":"min_sold","required":false,"schema":{"type":"number"}},{"description":"Max sales","example":10000,"in":"query","name":"max_sold","required":false,"schema":{"type":"number"}},{"description":"Min GMV (USD)","example":1000,"in":"query","name":"min_gmv","required":false,"schema":{"type":"number"}},{"description":"Max GMV (USD)","example":100000,"in":"query","name":"max_gmv","required":false,"schema":{"type":"number"}},{"description":"Min audience","example":100,"in":"query","name":"min_audience","required":false,"schema":{"type":"number"}},{"description":"Max audience","example":100000,"in":"query","name":"max_audience","required":false,"schema":{"type":"number"}},{"description":"Sort, format: field:asc|desc. Allowed: audience, gmv, peak_audience, sold, start_time. Default: gmv:desc","example":"gmv:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv:desc","enum":["audience","gmv","peak_audience","sold","start_time"],"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"country_code":{"description":"Country code","type":"string"},"cover":{"description":"Live cover","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"end_time":{"description":"End time (ms timestamp)","type":"integer"},"gmv":{"description":"GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"gpm":{"description":"GPM (GMV per 1K views)","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"id":{"description":"Unique identifier","type":"string"},"max_user_count":{"description":"Peak viewers","type":"integer"},"most_product_category_label":{"description":"Main product category","type":"string"},"new_follow_count":{"description":"New followers","type":"integer"},"opm":{"description":"OPM (orders per 1K views)","type":"number"},"product_count":{"description":"Product count","type":"integer"},"room_link":{"description":"Live room URL","type":"string"},"start_time":{"description":"Start time (ms timestamp)","type":"integer"},"title":{"description":"Live title","type":"string"},"total_sold_count":{"description":"Total units sold","type":"integer"},"total_user":{"description":"Total viewers","type":"integer"},"user_category_label":{"description":"User category label","type":"string"},"user_id":{"description":"User ID","type":"string"},"user_nickname":{"description":"User display name","type":"string"},"user_unique_id":{"description":"User TikTok username","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Live Search","tags":["Data/6.Lives"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.lives.read"}},"/open/v1/lives/{id}":{"get":{"description":"Get TikTok live stream details, including basics, core metrics, trends, linked products, and similar lives.","operationId":"trenz-lives-detail","parameters":[{"description":"Live ID","in":"path","name":"entity_id","required":true,"schema":{"type":"string"}},{"description":"Region code","in":"query","name":"country","required":true,"schema":{"enum":["us","th","my","vn","mx","it","fr","de","es","jp","br","gb","ph","sg","id"],"type":"string"}},{"description":"Included sub-resources, comma-separated: core,trend,products,similar","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Include related resources, comma-separated (values: core(Core Metrics))","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"country_code":{"description":"Country code","type":"string"},"cover":{"description":"Live cover","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"end_time":{"description":"End time (ms timestamp)","type":"integer"},"id":{"description":"Unique identifier","type":"string"},"most_product_category_label":{"description":"Main product category","type":"string"},"room_link":{"description":"Live room URL","type":"string"},"start_time":{"description":"Start time (ms timestamp)","type":"integer"},"title":{"description":"Live title","type":"string"},"user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"user_avg_audience_count":{"description":"Avg audience count","type":"number"},"user_avg_max_audience_count":{"description":"Avg peak viewers","type":"number"},"user_follower_count":{"description":"User follower count","type":"integer"},"user_id":{"description":"User ID","type":"string"},"user_live_count":{"description":"Total live count","type":"integer"},"user_nickname":{"description":"User display name","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Live Detail","tags":["Data/6.Lives"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.lives.read"}},"/open/v1/lives/{id}/products":{"get":{"description":"","operationId":"trenz-lives-products","parameters":[{"description":"Live ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_live_detail_product_ceiling_price":{"description":"Max price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_live_detail_product_commission_rate_num":{"description":"Commission rate","type":"string"},"tiktok_live_detail_product_conversion_rate":{"description":"Conversion rate","type":"number"},"tiktok_live_detail_product_country_code":{"description":"Country code","type":"string"},"tiktok_live_detail_product_floor_price":{"description":"Min price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_live_detail_product_gmv":{"description":"GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_live_detail_product_id":{"description":"Unique identifier","type":"string"},"tiktok_live_detail_product_images":{"description":"Image list","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_live_detail_product_l1_category":{"description":"Level-1 category","type":"string"},"tiktok_live_detail_product_l2_category":{"description":"Level-2 category","type":"string"},"tiktok_live_detail_product_l3_category":{"description":"Level-3 category","type":"string"},"tiktok_live_detail_product_rating":{"description":"Rating","type":"string"},"tiktok_live_detail_product_seller_avatar":{"description":"Shop avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_live_detail_product_seller_category_name_label":{"description":"Seller category label","type":"string"},"tiktok_live_detail_product_seller_id":{"description":"Shop ID","type":"string"},"tiktok_live_detail_product_seller_info":{"description":"Seller info","items":{"type":"string"},"type":"array"},"tiktok_live_detail_product_seller_name":{"description":"Seller name","type":"string"},"tiktok_live_detail_product_sold_count":{"description":"Units sold","type":"integer"},"tiktok_live_detail_product_title":{"description":"Live title","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Live Related Products","tags":["Data/6.Lives"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.lives.read"}},"/open/v1/lives/{id}/similar":{"get":{"description":"","operationId":"trenz-lives-similar","parameters":[{"description":"Live ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_live_detail_similar_country_code":{"description":"Country code","type":"string"},"tiktok_live_detail_similar_cover":{"description":"Live cover","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_live_detail_similar_gmv":{"description":"GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_live_detail_similar_max_user_count":{"description":"Peak viewers","type":"integer"},"tiktok_live_detail_similar_most_product_category_label":{"description":"Main product category","type":"string"},"tiktok_live_detail_similar_room_id":{"description":"Live room ID","type":"string"},"tiktok_live_detail_similar_title":{"description":"Live title","type":"string"},"tiktok_live_detail_similar_user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_live_detail_similar_user_id":{"description":"User ID","type":"string"},"tiktok_live_detail_similar_user_nickname":{"description":"User display name","type":"string"},"tiktok_live_detail_similar_user_unique_id":{"description":"User TikTok username","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Similar Lives","tags":["Data/6.Lives"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.lives.read"}},"/open/v1/products/rankings/most-promoted":{"get":{"description":"Query TikTok products most promoted by creators, videos, and live streams for a period.","operationId":"trenz-products-ranking-most-promoted","parameters":[{"description":"Statistics date in YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Granularity: daily/0, weekly/1, or monthly/2","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"Product category ID","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Seller type: 1=overseas, 2=local, 3=brand, 4=non-brand","in":"query","name":"seller_type","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"Sort as field:asc|desc; fields: interval_gmv, interval_sold_count, live_count, live_user_count, related_creator_count, video_play_count","example":"related_creator_count:desc","in":"query","name":"sort","required":false,"schema":{"default":"related_creator_count:desc","type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 10, maximum 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Ranking results with internal field prefixes removed","items":{"additionalProperties":true,"properties":{"id":{"description":"Unique identifier of the ranked entity","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total number of records matching the filters","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Most Promoted Products","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.products.read"}},"/open/v1/products/rankings/new-arrivals":{"get":{"description":"Query newly listed TikTok products gaining traction, with filters, sorting, and pagination.","operationId":"trenz-products-ranking-new-arrivals","parameters":[{"description":"Product category ID","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Seller type: 1=overseas, 2=local, 3=brand, 4=non-brand","in":"query","name":"seller_type","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"Listing date range start in YYYYMMDD","in":"query","name":"listed_from","required":false,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Listing date range end in YYYYMMDD","in":"query","name":"listed_to","required":false,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Product status option ID: 1, 2, 3, or 4","in":"query","name":"product_status","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"Sort as field:asc|desc; fields: gmv_3d, sold_count_3d, total_gmv, total_sold_count","example":"gmv_3d:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv_3d:desc","type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 10, maximum 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Ranking results with internal field prefixes removed","items":{"additionalProperties":true,"properties":{"id":{"description":"Unique identifier of the ranked entity","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total number of records matching the filters","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"New Arrival Products","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.products.read"}},"/open/v1/products/rankings/top-selling":{"get":{"description":"Query the TikTok product top-selling ranking by period with filters, sorting, and pagination.","operationId":"trenz-products-ranking-top-selling","parameters":[{"description":"Statistics date in YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Granularity: daily/0, weekly/1, or monthly/2","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"Product category ID","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Seller type: 1=overseas, 2=local, 3=brand, 4=non-brand","in":"query","name":"seller_type","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"Sort as field:asc|desc; fields: gmv_growth_rate, interval_gmv, interval_sold_count, sold_count_growth_rate, total_gmv, total_sold_count","example":"interval_sold_count:desc","in":"query","name":"sort","required":false,"schema":{"default":"interval_sold_count:desc","type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 10, maximum 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Ranking results with internal field prefixes removed","items":{"additionalProperties":true,"properties":{"id":{"description":"Unique identifier of the ranked entity","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total number of records matching the filters","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Product Top Selling","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.products.read"}},"/open/v1/products/search":{"get":{"description":"Search TikTok products with multi-dimensional filters on keyword, category, price, sales, etc.","operationId":"trenz-products-search","parameters":[{"description":"Search keyword","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"Product category ID (numeric), can be obtained from the `l1_category` field in search results","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Seller type: 1=Overseas Non-brand, 2=Local, 3=Brand, 4=Non-brand","example":"local","in":"query","name":"seller_type","required":false,"schema":{"type":"string"}},{"description":"Min price (USD)","example":1,"in":"query","name":"min_price","required":false,"schema":{"type":"number"}},{"description":"Max price (USD)","example":100,"in":"query","name":"max_price","required":false,"schema":{"type":"number"}},{"description":"Min rating (0-5)","example":4,"in":"query","name":"min_rating","required":false,"schema":{"type":"number"}},{"description":"Max rating (0-5)","example":5,"in":"query","name":"max_rating","required":false,"schema":{"type":"number"}},{"description":"7-day min sales","example":100,"in":"query","name":"min_sold_7d","required":false,"schema":{"type":"number"}},{"description":"7-day max sales","example":10000,"in":"query","name":"max_sold_7d","required":false,"schema":{"type":"number"}},{"description":"30-day min sales","example":500,"in":"query","name":"min_sold_30d","required":false,"schema":{"type":"number"}},{"description":"30-day max sales","example":50000,"in":"query","name":"max_sold_30d","required":false,"schema":{"type":"number"}},{"description":"Whether has free shipping","example":true,"in":"query","name":"free_shipping","required":false,"schema":{"type":"boolean"}},{"description":"Sort, format: field:asc|desc. Allowed: daily_sold, gmv_30d, gmv_7d, price, rating, sold_30d, sold_7d. Default: gmv_7d:desc","example":"gmv_7d:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv_7d:desc","enum":["daily_sold","gmv_30d","gmv_7d","price","rating","sold_30d","sold_7d"],"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"category_monthly_gmv":{"description":"Category monthly GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"category_opportunity":{"description":"Category opportunity index","type":"number"},"category_seller_count":{"description":"Category seller count","type":"integer"},"ceiling_price":{"description":"Max price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"commission_rate":{"description":"Commission rate","type":"number"},"create_time":{"description":"Created at (ms timestamp)","type":"integer"},"creator_sold_rate":{"description":"Creator conversion rate (0-1)","type":"number"},"creator_total_play_count":{"description":"Creator total views","type":"integer"},"cross_platform_amazon_est_monthly_sales_max":{"description":"Amazon est. monthly sales (max)","type":"integer"},"cross_platform_amazon_est_monthly_sales_min":{"description":"Amazon est. monthly sales (min)","type":"integer"},"cross_platform_amazon_product_count":{"description":"Amazon product count","type":"integer"},"cross_platform_shopify_product_count":{"description":"Shopify product count","type":"integer"},"cross_platform_shopify_site_count":{"description":"Shopify site count","type":"integer"},"floor_price":{"description":"Min price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"id":{"description":"Unique identifier","type":"string"},"l1_category":{"description":"L1 category","type":"string"},"original_ceiling_price":{"description":"Original max price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"original_floor_price":{"description":"Original min price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"product_daily_gmv":{"description":"Daily GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"product_daily_sold_count":{"description":"Daily sales","type":"integer"},"product_gmv":{"description":"Total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"product_gmv_for_last_30_days":{"description":"30-day GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"product_gmv_for_last_3_days":{"description":"3-day GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"product_gmv_for_last_7_days":{"description":"7-day GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"product_images":{"description":"Product images","items":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"type":"array"},"product_name":{"description":"Product name","type":"string"},"product_rating":{"description":"Product rating (0-5)","type":"number"},"product_sold_count":{"description":"Total sales","type":"integer"},"product_sold_count_for_last_30_days":{"description":"30-day sales","type":"integer"},"product_sold_count_for_last_3_days":{"description":"3-day sales","type":"integer"},"product_sold_count_for_last_7_days":{"description":"7-day sales","type":"integer"},"region":{"description":"Region code","type":"string"},"review_count":{"description":"Review count","type":"integer"},"seasonal_signal":{"description":"Seasonal signal","properties":{"month_range":{"description":"Seasonal month range","type":"string"},"peak_month":{"description":"Peak month","type":"string"},"peak_month_gmv":{"description":"Peak month GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"total_gmv":{"description":"Seasonal total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"total_sold":{"description":"Seasonal total sales","type":"integer"}},"type":"object"},"seller_avatar":{"description":"Seller avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"seller_business_info":{"description":"Business entity info","items":{"type":"string"},"type":"array"},"seller_id":{"description":"Seller ID","type":"string"},"shipping_fee":{"description":"Shipping fee","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"shop_name":{"description":"Shop name","type":"string"},"shop_total_sold_count":{"description":"Shop total sales","type":"integer"},"signal_description":{"description":"Signal description","type":"string"},"signal_type":{"description":"Signal type","type":"string"},"sold_count_trend":{"description":"Sales trend (7-day)","items":{"properties":{"timestamp":{"description":"Timestamp (ms)","type":"integer"},"value":{"description":"Value","type":"number"}},"type":"object"},"type":"array"},"spike_pct":{"description":"Spike percentage","type":"number"},"total_related_creator_count":{"description":"Related creator count","type":"integer"},"total_related_video_count":{"description":"Related video count","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Product Search","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.products.read"}},"/open/v1/products/{id}":{"get":{"description":"Get TikTok product details with linked videos, creators, and reviews.","operationId":"trenz-products-detail","parameters":[{"description":"Product ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Include related resources, comma-separated (values: channel(Sales Channels), core(Core Metrics))","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"ceiling_price":{"description":"Max price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"commission_rate":{"description":"Commission rate","type":"number"},"create_time":{"description":"Listing time","type":"integer"},"floor_price":{"description":"Min price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"id":{"description":"Unique identifier","type":"string"},"l1_category":{"description":"Level-1 category","type":"string"},"last_update_time":{"description":"Last updated (ms timestamp)","type":"integer"},"original_ceiling_price":{"description":"Original max price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"original_floor_price":{"description":"Original min price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"product_id":{"description":"Product ID","type":"string"},"product_images":{"description":"Product images","items":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"type":"array"},"product_name":{"description":"Product name","type":"string"},"product_rating":{"description":"Product rating (0-5)","type":"number"},"product_sku_props":{"description":"SKU properties","items":{"properties":{"has_image":{"description":"Has image","type":"boolean"},"prop_id":{"description":"Property ID","type":"string"},"prop_name":{"description":"Property name","type":"string"},"sale_prop_values":{"description":"Property values","items":{"properties":{"image":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"prop_value":{"description":"Property value","type":"string"},"prop_value_id":{"description":"Property value ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"product_skus":{"description":"SKU list","items":{"properties":{"is_hot":{"description":"Is hot selling","type":"boolean"},"price":{"properties":{"discount":{"description":"Discount info","type":"string"},"original_price":{"description":"Original price","type":"string"},"original_price_value":{"description":"Original price value","type":"string"},"real_price":{"description":"Actual price","type":"number"},"unit_price_desc":{"description":"Unit price description","type":"string"}},"type":"object"},"sale_prop_value_ids":{"description":"Property value ID combination","type":"string"},"sku_id":{"description":"SKU ID","type":"string"},"sku_sale_props":{"description":"SKU properties","items":{"properties":{"prop_id":{"description":"Property ID","type":"string"},"prop_name":{"description":"Property name (e.g. Color)","type":"string"},"prop_value":{"description":"Property value","type":"string"},"prop_value_id":{"description":"Property value ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"Status (1=active)","type":"integer"},"stock":{"description":"Stock","type":"integer"}},"type":"object"},"type":"array"},"product_specifications":{"description":"Product specifications","items":{"properties":{"name":{"description":"Specification name","type":"string"},"value":{"description":"Specification value","type":"string"}},"type":"object"},"type":"array"},"region":{"description":"Region code","type":"string"},"review_count":{"description":"Review count","type":"integer"},"seller_avatar":{"description":"Shop avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"seller_business_info":{"description":"Business entity info","items":{"type":"string"},"type":"array"},"seller_creator_avatar":{"description":"Creator avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"seller_creator_follow_count":{"description":"Creator follower count","type":"string"},"seller_creator_nickname":{"description":"Creator display name","type":"string"},"seller_creator_role":{"description":"Creator role","type":"integer"},"seller_creator_user_id":{"description":"Creator user ID","type":"string"},"seller_creator_user_name":{"description":"Creator username","type":"string"},"seller_id":{"description":"Shop ID","type":"string"},"shipping_fee":{"description":"Shipping fee","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"shop_main_category":{"description":"Main category","type":"string"},"shop_name":{"description":"Shop name","type":"string"},"shop_rating":{"description":"Shop rating","type":"number"},"shop_total_gmv":{"description":"Shop total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"shop_total_sold_count":{"description":"Shop total sales","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Product Detail","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.products.read"}},"/open/v1/products/{id}/creators":{"get":{"description":"","operationId":"trenz-products-creators","parameters":[{"description":"Product ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_product_detail_author_avg_engagement_rate":{"description":"Avg engagement rate","type":"number"},"tiktok_product_detail_author_avg_like_cnt":{"description":"Author avg likes per video","type":"number"},"tiktok_product_detail_author_avg_play_cnt":{"description":"Author avg views per video","type":"number"},"tiktok_product_detail_author_total_like_cnt":{"description":"Author total likes","type":"integer"},"tiktok_product_detail_author_total_play_cnt":{"description":"Author total views","type":"integer"},"tiktok_product_detail_by_live":{"description":"Sells via live commerce","type":"boolean"},"tiktok_product_detail_by_shop":{"description":"Sells via shop","type":"boolean"},"tiktok_product_detail_by_video":{"description":"Sells via video commerce","type":"boolean"},"tiktok_product_detail_category_label":{"description":"Creator category label","type":"string"},"tiktok_product_detail_country_code":{"description":"Country code","type":"string"},"tiktok_product_detail_creator_bio_email":{"description":"Bio email","type":"string"},"tiktok_product_detail_creator_facebook_url":{"description":"Facebook URL","type":"string"},"tiktok_product_detail_creator_ins_id":{"description":"Instagram ID","type":"string"},"tiktok_product_detail_creator_linkedin_url":{"description":"LinkedIn URL","type":"string"},"tiktok_product_detail_creator_related_total_live":{"description":"Related live count","type":"integer"},"tiktok_product_detail_creator_related_total_video":{"description":"Related video count","type":"string"},"tiktok_product_detail_creator_telegram_url":{"description":"Telegram URL","type":"string"},"tiktok_product_detail_creator_twitter_id":{"description":"Twitter/X ID","type":"string"},"tiktok_product_detail_creator_video_30d_gmv":{"description":"Video 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_creator_video_7d_gmv":{"description":"Video 7D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_creator_whatsapp_url":{"description":"WhatsApp URL","type":"string"},"tiktok_product_detail_creator_youtube_channel_id":{"description":"YouTube channel ID","type":"string"},"tiktok_product_detail_follower_count":{"description":"Follower count","type":"integer"},"tiktok_product_detail_live_30d_gmv":{"description":"Live 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_live_7d_gmv":{"description":"Live 7D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_nickname":{"description":"Display name","type":"string"},"tiktok_product_detail_product_id":{"description":"Product ID","type":"string"},"tiktok_product_detail_total_video_live_30d_gmv":{"description":"Total Video Live 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_total_video_live_7d_gmv":{"description":"Total Video Live 7D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_uid":{"description":"User ID","type":"string"},"tiktok_product_detail_unique_id":{"description":"TikTok username","type":"string"},"tiktok_product_detail_user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_product_detail_user_id":{"description":"User ID","type":"string"},"tiktok_product_detail_video_total_like_count_to_follower_count_ratio":{"description":"Video likes to followers ratio","type":"number"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Product Related Creators","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.products.read"}},"/open/v1/products/{id}/lives":{"get":{"description":"","operationId":"trenz-products-lives","parameters":[{"description":"Product ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_product_detail_ceiling_price":{"description":"Max price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_country_code":{"description":"Country code","type":"string"},"tiktok_product_detail_cover":{"description":"Live cover","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_product_detail_end_time":{"description":"End time (ms timestamp)","type":"integer"},"tiktok_product_detail_gpm":{"description":"GPM (GMV per 1K views)","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_live_total_sold_count":{"description":"Live total units sold","type":"integer"},"tiktok_product_detail_max_user_count":{"description":"Peak viewers","type":"integer"},"tiktok_product_detail_most_product_category_label":{"description":"Main product category","type":"string"},"tiktok_product_detail_new_follower_count":{"description":"New followers gained","type":"integer"},"tiktok_product_detail_nickname":{"description":"Display name","type":"string"},"tiktok_product_detail_opm":{"description":"OPM (orders per 1K views)","type":"number"},"tiktok_product_detail_product_count":{"description":"Product count","type":"integer"},"tiktok_product_detail_room_id":{"description":"Live room ID","type":"string"},"tiktok_product_detail_room_link":{"description":"Live room URL","type":"string"},"tiktok_product_detail_start_time":{"description":"Start time (ms timestamp)","type":"integer"},"tiktok_product_detail_title":{"description":"Live title","type":"string"},"tiktok_product_detail_total_gmv":{"description":"Total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_total_user":{"description":"Total viewers","type":"integer"},"tiktok_product_detail_user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_product_detail_user_category_label":{"description":"User category label","type":"string"},"tiktok_product_detail_user_id":{"description":"User ID","type":"string"},"tiktok_product_detail_user_unique_id":{"description":"User TikTok username","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Product Related Lives","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.products.read"}},"/open/v1/products/{id}/reviews":{"get":{"description":"","operationId":"trenz-products-reviews","parameters":[{"description":"Product ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_product_detail_review_content":{"description":"Review content","type":"string"},"tiktok_product_detail_review_id":{"description":"Unique identifier","type":"string"},"tiktok_product_detail_review_images":{"description":"Image list","type":"array"},"tiktok_product_detail_review_media":{"description":"Media resources","properties":{"cover_url":{"description":"Video cover URL","type":"string"},"video_url":{"description":"Video URL","type":"string"}},"type":"object"},"tiktok_product_detail_review_product_id":{"description":"Product ID","type":"string"},"tiktok_product_detail_review_publish_time":{"description":"Published at (ms timestamp)","type":"string"},"tiktok_product_detail_review_rating":{"description":"Rating","type":"integer"},"tiktok_product_detail_review_sku_id":{"description":"SKU ID","type":"string"},"tiktok_product_detail_review_sku_image":{"description":"SKU image","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_product_detail_review_sku_specification":{"description":"SKU specification","type":"string"},"tiktok_product_detail_review_translated_review":{"description":"Translated review","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Product Reviews","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.products.read"}},"/open/v1/products/{id}/similar":{"get":{"description":"","operationId":"trenz-products-similar","parameters":[{"description":"Product ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_product_detail_similar_l1_category":{"description":"Level-1 category","type":"string"},"tiktok_product_detail_similar_l2_category":{"description":"Level-2 category","type":"string"},"tiktok_product_detail_similar_l3_category":{"description":"Level-3 category","type":"string"},"tiktok_product_detail_similar_product_gmv":{"description":"Total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_similar_product_id":{"description":"Product ID","type":"string"},"tiktok_product_detail_similar_product_images":{"description":"Product images","items":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"type":"array"},"tiktok_product_detail_similar_product_name":{"description":"Product name","type":"string"},"tiktok_product_detail_similar_product_rating":{"description":"Product rating (0-5)","type":"number"},"tiktok_product_detail_similar_product_sold_count":{"description":"Total sales","type":"integer"},"tiktok_product_detail_similar_region":{"description":"Region code","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Similar Products","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.products.read"}},"/open/v1/products/{id}/videos":{"get":{"description":"","operationId":"trenz-products-videos","parameters":[{"description":"Product ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_product_detail_ad_source":{"description":"Ad source (1=has ad)","type":"integer"},"tiktok_product_detail_country_code":{"description":"Country code","type":"string"},"tiktok_product_detail_cover_url":{"description":"Cover image","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_product_detail_is_ad":{"description":"Is advertisement","type":"boolean"},"tiktok_product_detail_is_aigc_video":{"description":"Is AI-generated video","type":"boolean"},"tiktok_product_detail_product_id":{"description":"Product ID","type":"string"},"tiktok_product_detail_share_url":{"description":"TikTok share URL","type":"string"},"tiktok_product_detail_user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_product_detail_user_id":{"description":"User ID","type":"string"},"tiktok_product_detail_user_nickname":{"description":"User display name","type":"string"},"tiktok_product_detail_user_unique_id":{"description":"User TikTok username","type":"string"},"tiktok_product_detail_video_30d_gmv":{"description":"Video 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_video_30d_play_count":{"description":"Video 30D Play Count","type":"integer"},"tiktok_product_detail_video_30d_sold_count":{"description":"Video 30D Sold Count","type":"integer"},"tiktok_product_detail_video_desc":{"description":"Video description","type":"string"},"tiktok_product_detail_video_duration":{"description":"Duration (ms)","type":"integer"},"tiktok_product_detail_video_engagement_rate":{"description":"Engagement rate (0-1)","type":"number"},"tiktok_product_detail_video_id":{"description":"Video ID","type":"string"},"tiktok_product_detail_video_launch_time":{"description":"Published at (ms timestamp)","type":"integer"},"tiktok_product_detail_video_like_count":{"description":"Like count","type":"integer"},"tiktok_product_detail_video_play_count":{"description":"View count","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Product Related Videos","tags":["Data/1.Products"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.products.read"}},"/open/v1/reports/{id}":{"get":{"description":"Returns the report detail by ID (including its `session_id`). Free endpoint.","operationId":"get-report","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"Report ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"content":"Markdown 内容","created_at":"2026-05-20T10:00:00Z","id":"rpt-xxxx","session_id":"sess-xxxx","title":"报告标题","updated_at":"2026-05-20T10:01:00Z"},"request_id":"req-xxxx"},"schema":{"properties":{"data":{"properties":{"content":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"session_id":{"type":"string"},"title":{"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"description":"FORBIDDEN — report exists but its session belongs to another user (owner check failed)"},"404":{"description":"REPORT_NOT_FOUND — report does not exist"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Get a single report","tags":["Trenz Agent/2.Sessions \u0026 Reports"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/sellers/rankings/most-promoted":{"get":{"description":"Query TikTok sellers most promoted by creators, videos, and live streams for a period.","operationId":"trenz-sellers-ranking-most-promoted","parameters":[{"description":"Statistics date in YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Granularity: daily/0, weekly/1, or monthly/2","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"Primary product category ID of the seller","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Shop type: 1=overseas, 2=local, 3=brand, 4=non-brand","in":"query","name":"shop_type","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"Sort as field:asc|desc; fields: product_count, related_creator_count, related_video_count, shop_creator_count, total_related_creator_count, video_creator_count","example":"related_creator_count:desc","in":"query","name":"sort","required":false,"schema":{"default":"related_creator_count:desc","type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 10, maximum 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Ranking results with internal field prefixes removed","items":{"additionalProperties":true,"properties":{"id":{"description":"Unique identifier of the ranked entity","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total number of records matching the filters","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Most Promoted Sellers","tags":["Data/4.Sellers"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.sellers.read"}},"/open/v1/sellers/rankings/top-selling":{"get":{"description":"Query top-selling TikTok sellers by period with filters, sorting, and pagination.","operationId":"trenz-sellers-ranking-top-selling","parameters":[{"description":"Statistics date in YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"Granularity: daily/0, weekly/1, or monthly/2","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"Primary product category ID of the seller","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Shop type: 1=overseas, 2=local, 3=brand, 4=non-brand","in":"query","name":"shop_type","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"Sort as field:asc|desc; fields: gmv_growth_rate, interval_gmv, interval_sold_count, product_count, sold_count_growth_rate, total_gmv, total_sold_count","example":"interval_sold_count:desc","in":"query","name":"sort","required":false,"schema":{"default":"interval_sold_count:desc","type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 10, maximum 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"Ranking results with internal field prefixes removed","items":{"additionalProperties":true,"properties":{"id":{"description":"Unique identifier of the ranked entity","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total number of records matching the filters","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Seller Top Selling","tags":["Data/4.Sellers"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.sellers.read"}},"/open/v1/sellers/search":{"get":{"description":"Search TikTok sellers with multi-dimensional filters on category, rating, sales, etc.","operationId":"trenz-sellers-search","parameters":[{"description":"Search keyword","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"Seller primary category ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Seller type: 1=Overseas Non-brand, 2=Local, 3=Brand, 4=Non-brand","example":"local","in":"query","name":"seller_type","required":false,"schema":{"type":"string"}},{"description":"Min seller rating","example":4,"in":"query","name":"min_rating","required":false,"schema":{"type":"number"}},{"description":"Max seller rating","example":5,"in":"query","name":"max_rating","required":false,"schema":{"type":"number"}},{"description":"7-day min sales","example":100,"in":"query","name":"min_sold_7d","required":false,"schema":{"type":"number"}},{"description":"7-day max sales","example":10000,"in":"query","name":"max_sold_7d","required":false,"schema":{"type":"number"}},{"description":"7-day min sales amount (USD)","example":500,"in":"query","name":"min_gmv_7d","required":false,"schema":{"type":"number"}},{"description":"7-day max sales amount (USD)","example":50000,"in":"query","name":"max_gmv_7d","required":false,"schema":{"type":"number"}},{"description":"Sort, format: field:asc|desc. Allowed: gmv_7d, product_count, rating, sold_7d, total_gmv, total_sold. Default: gmv_7d:desc","example":"gmv_7d:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv_7d:desc","enum":["gmv_7d","product_count","rating","sold_7d","total_gmv","total_sold"],"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"region":{"description":"Region code","type":"string"},"seller_business_info":{"description":"Business entity info","items":{"type":"string"},"type":"array"},"shop_gmv_for_last_7_days":{"description":"7-day GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"shop_main_category":{"description":"Main category","type":"string"},"shop_name":{"description":"Shop name","type":"string"},"shop_product_count":{"description":"Product count","type":"integer"},"shop_rating":{"description":"Shop rating","type":"number"},"shop_sold_count_for_last_7_days":{"description":"7-day sales","type":"integer"},"shop_total_gmv":{"description":"Shop total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"shop_total_sold_count":{"description":"Shop total sales","type":"integer"},"sold_count_trend":{"description":"Sales trend (7-day)","items":{"properties":{"timestamp":{"description":"Timestamp (ms)","type":"integer"},"value":{"description":"Value","type":"number"}},"type":"object"},"type":"array"},"total_related_creator_count":{"description":"Related creator count","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Seller Search","tags":["Data/4.Sellers"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.sellers.read"}},"/open/v1/sellers/{id}":{"get":{"description":"Get TikTok seller details with product list and linked creators.","operationId":"trenz-sellers-detail","parameters":[{"description":"Seller ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Include related resources, comma-separated (values: channel(Sales Channels), core(Core Metrics))","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"business_info":{"description":"Business info","items":{"type":"string"},"type":"array"},"create_time":{"description":"Listing time","type":"integer"},"creator_avatar":{"description":"Creator avatar","type":"string"},"creator_follow_count":{"description":"Creator followers","type":"string"},"creator_nickname":{"description":"Creator name","type":"string"},"creator_role":{"description":"Creator role","type":"integer"},"creator_user_id":{"description":"Creator user ID","type":"string"},"creator_user_name":{"description":"Creator username","type":"string"},"id":{"description":"Unique identifier","type":"string"},"last_update_time":{"description":"Last updated (ms timestamp)","type":"integer"},"region":{"description":"Region code","type":"string"},"seller_avatar":{"description":"Shop avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"seller_id":{"description":"Shop ID","type":"string"},"shop_main_category":{"description":"Main category","type":"string"},"shop_name":{"description":"Shop name","type":"string"},"shop_rating":{"description":"Shop rating","type":"number"},"shop_total_gmv":{"description":"Shop total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Seller Detail","tags":["Data/4.Sellers"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.sellers.read"}},"/open/v1/sellers/{id}/creators":{"get":{"description":"","operationId":"trenz-sellers-creators","parameters":[{"description":"Seller ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_seller_detail_creator_account_type":{"description":"Account type","type":"integer"},"tiktok_seller_detail_creator_author_avg_engagement_rate":{"description":"Avg engagement rate","type":"number"},"tiktok_seller_detail_creator_author_avg_like_cnt":{"description":"Author avg likes per video","type":"number"},"tiktok_seller_detail_creator_author_avg_play_cnt":{"description":"Author avg views per video","type":"number"},"tiktok_seller_detail_creator_author_total_play_cnt":{"description":"Author total views","type":"integer"},"tiktok_seller_detail_creator_bio_email":{"description":"Bio email","type":"string"},"tiktok_seller_detail_creator_by_live":{"description":"Sells via live commerce","type":"boolean"},"tiktok_seller_detail_creator_by_shop":{"description":"Sells via shop","type":"boolean"},"tiktok_seller_detail_creator_by_video":{"description":"Sells via video commerce","type":"boolean"},"tiktok_seller_detail_creator_category_label":{"description":"Creator category label","type":"string"},"tiktok_seller_detail_creator_country_code":{"description":"Country code","type":"string"},"tiktok_seller_detail_creator_facebook_url":{"description":"Facebook URL","type":"string"},"tiktok_seller_detail_creator_follower_count":{"description":"Follower count","type":"integer"},"tiktok_seller_detail_creator_ins_id":{"description":"Instagram ID","type":"string"},"tiktok_seller_detail_creator_linkedin_url":{"description":"LinkedIn URL","type":"string"},"tiktok_seller_detail_creator_live_30d_gmv":{"description":"Live 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_seller_detail_creator_nickname":{"description":"Display name","type":"string"},"tiktok_seller_detail_creator_related_total_live":{"description":"Related live count","type":"integer"},"tiktok_seller_detail_creator_related_total_video":{"description":"Related video count","type":"integer"},"tiktok_seller_detail_creator_seller_id":{"description":"Shop ID","type":"string"},"tiktok_seller_detail_creator_telegram_url":{"description":"Telegram URL","type":"string"},"tiktok_seller_detail_creator_total_favorited":{"description":"Total likes received","type":"integer"},"tiktok_seller_detail_creator_total_video_live_30d_gmv":{"description":"Total Video Live 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_seller_detail_creator_twitter_id":{"description":"Twitter/X ID","type":"string"},"tiktok_seller_detail_creator_unique_id":{"description":"TikTok username","type":"string"},"tiktok_seller_detail_creator_user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_seller_detail_creator_user_id":{"description":"User ID","type":"string"},"tiktok_seller_detail_creator_video_30d_gmv":{"description":"Video 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_seller_detail_creator_video_7d_gmv":{"description":"Video 7D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_seller_detail_creator_video_count":{"description":"Video count","type":"integer"},"tiktok_seller_detail_creator_whatsapp_url":{"description":"WhatsApp URL","type":"string"},"tiktok_seller_detail_creator_youtube_channel_id":{"description":"YouTube channel ID","type":"string"},"tiktok_seller_detail_live_7d_gmv":{"description":"Live 7D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_seller_detail_total_video_live_7d_gmv":{"description":"Total Video Live 7D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Seller Related Creators","tags":["Data/4.Sellers"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.sellers.read"}},"/open/v1/sellers/{id}/products":{"get":{"description":"","operationId":"trenz-sellers-products","parameters":[{"description":"Seller ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_seller_detail_product_detail_link":{"description":"Product detail URL","type":"string"},"tiktok_seller_detail_product_link":{"description":"Product URL","type":"string"},"tiktok_seller_product_ceiling_price":{"description":"Max price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_seller_product_commission_rate":{"description":"Commission rate","type":"number"},"tiktok_seller_product_create_time":{"description":"Listing time","type":"integer"},"tiktok_seller_product_floor_price":{"description":"Min price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_seller_product_l1_category":{"description":"Level-1 category","type":"string"},"tiktok_seller_product_l2_category":{"description":"Level-2 category","type":"string"},"tiktok_seller_product_l3_category":{"description":"Level-3 category","type":"string"},"tiktok_seller_product_product_gmv":{"description":"Total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_seller_product_product_gmv_for_last_7_days":{"description":"Product Gmv For Last 7 Days","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_seller_product_product_id":{"description":"Product ID","type":"string"},"tiktok_seller_product_product_images":{"description":"Product images","items":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"type":"array"},"tiktok_seller_product_product_name":{"description":"Product name","type":"string"},"tiktok_seller_product_product_rating":{"description":"Product rating (0-5)","type":"number"},"tiktok_seller_product_product_sku_props":{"description":"SKU properties","items":{"properties":{"has_image":{"description":"Has image","type":"boolean"},"prop_id":{"description":"Property ID","type":"string"},"prop_name":{"description":"Property name","type":"string"},"sale_prop_values":{"description":"Property values","items":{"properties":{"image":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"prop_value":{"description":"Property value","type":"string"},"prop_value_id":{"description":"Property value ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"tiktok_seller_product_product_skus":{"description":"SKU list","items":{"properties":{"is_hot":{"description":"Is hot selling","type":"boolean"},"price":{"properties":{"discount":{"description":"Discount info","type":"string"},"original_price":{"description":"Original price","type":"string"},"original_price_value":{"description":"Original price value","type":"string"},"real_price":{"description":"Actual price","type":"number"},"unit_price_desc":{"description":"Unit price description","type":"string"}},"type":"object"},"sale_prop_value_ids":{"description":"Property value ID combination","type":"string"},"sku_id":{"description":"SKU ID","type":"string"},"sku_sale_props":{"description":"SKU properties","items":{"properties":{"prop_id":{"description":"Property ID","type":"string"},"prop_name":{"description":"Property name (e.g. Color)","type":"string"},"prop_value":{"description":"Property value","type":"string"},"prop_value_id":{"description":"Property value ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"Status (1=active)","type":"integer"},"stock":{"description":"Stock","type":"integer"}},"type":"object"},"type":"array"},"tiktok_seller_product_product_sold_count":{"description":"Total sales","type":"integer"},"tiktok_seller_product_product_sold_count_for_last_7_days":{"description":"Product Sold Count For Last 7 Days","type":"integer"},"tiktok_seller_product_product_status":{"description":"Product status","type":"integer"},"tiktok_seller_product_region":{"description":"Region code","type":"string"},"tiktok_seller_product_review_count":{"description":"Review count","type":"integer"},"tiktok_seller_product_total_related_creator_count":{"description":"Related creator count","type":"integer"},"tiktok_seller_product_total_related_video_count":{"description":"Related video count","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Seller Related Products","tags":["Data/4.Sellers"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.sellers.read"}},"/open/v1/sellers/{id}/videos":{"get":{"description":"","operationId":"trenz-sellers-videos","parameters":[{"description":"Seller ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_seller_detail_cover_url":{"description":"Cover image","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_seller_detail_follower_count":{"description":"Follower count","type":"integer"},"tiktok_seller_detail_is_ad":{"description":"Is advertisement","type":"boolean"},"tiktok_seller_detail_is_aigc_video":{"description":"Is AI-generated video","type":"boolean"},"tiktok_seller_detail_share_url":{"description":"TikTok share URL","type":"string"},"tiktok_seller_detail_user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_seller_detail_user_id":{"description":"User ID","type":"string"},"tiktok_seller_detail_user_nickname":{"description":"User display name","type":"string"},"tiktok_seller_detail_user_unique_id":{"description":"User TikTok username","type":"string"},"tiktok_seller_detail_video_30d_gmv":{"description":"Video 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_seller_detail_video_30d_play_count":{"description":"Video 30D Play Count","type":"integer"},"tiktok_seller_detail_video_30d_sold_count":{"description":"Video 30D Sold Count","type":"integer"},"tiktok_seller_detail_video_ad_source":{"description":"Video ad source","type":"integer"},"tiktok_seller_detail_video_comment_count":{"description":"Comment count","type":"integer"},"tiktok_seller_detail_video_country_code":{"description":"Video country","type":"string"},"tiktok_seller_detail_video_desc":{"description":"Video description","type":"string"},"tiktok_seller_detail_video_duration":{"description":"Duration (ms)","type":"integer"},"tiktok_seller_detail_video_engagement_rate":{"description":"Engagement rate (0-1)","type":"number"},"tiktok_seller_detail_video_id":{"description":"Video ID","type":"string"},"tiktok_seller_detail_video_launch_time":{"description":"Published at (ms timestamp)","type":"integer"},"tiktok_seller_detail_video_like_count":{"description":"Like count","type":"integer"},"tiktok_seller_detail_video_play_count":{"description":"View count","type":"integer"},"tiktok_seller_detail_video_seller_id":{"description":"Seller ID","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Seller Related Videos","tags":["Data/4.Sellers"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.sellers.read"}},"/open/v1/sessions":{"get":{"description":"Returns the session list for the current (or delegated) user; optionally fuzzy-search titles via `q`. `total` is the filtered total — page with `limit`/`offset`. Free endpoint.","operationId":"list-sessions","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"Page size, default 20, max 100 (cap enforced by nebula-claude)","in":"query","name":"limit","required":false,"schema":{"type":"integer"}},{"description":"Offset, default 0","in":"query","name":"offset","required":false,"schema":{"type":"integer"}},{"description":"Fuzzy title search (ILIKE)","in":"query","name":"q","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"sessions":[{"created_at":"2026-05-20T10:00:00Z","id":"sess-xxxx","last_active_at":"2026-05-25T12:00:00Z","message_count":7,"status":"active","title":"会话标题"}],"total":42},"request_id":"req-xxxx"},"schema":{"properties":{"data":{"properties":{"sessions":{"items":{"properties":{"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"last_active_at":{"format":"date-time","type":"string"},"message_count":{"type":"integer"},"status":{"description":"Session status (default active)","enum":["active","archived"],"type":"string"},"title":{"type":"string"}},"type":"object"},"type":"array"},"total":{"type":"integer"}},"required":["sessions","total"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"List the current user's sessions","tags":["Trenz Agent/2.Sessions \u0026 Reports"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/sessions/{sid}":{"get":{"description":"Returns all messages of the given session (including async tasks each message triggered). `content` is kept verbatim; business XML tags are parsed client-side.","operationId":"get-session-messages","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"Session ID","in":"path","name":"sid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"messages":[{"agent_id":"trenzer","attachments":null,"content":"string，可能含 \u003creport\u003e 等业务 XML 标签","created_at":"2026-05-20T10:00:00Z","id":"msg-xxxx","role":"assistant","tasks":[{"completed_at":"2026-05-20T10:00:05Z","created_at":"2026-05-20T10:00:01Z","display_name":"Generate Image","result_type":"image","status":"completed","task_id":"tk-xxxx","tool_name":"image_gen"}]}]},"request_id":"req-xxxx"},"schema":{"properties":{"data":{"properties":{"messages":{"items":{"properties":{"agent_id":{"type":"string"},"attachments":{"items":{"properties":{"media_type":{"type":"string"},"name":{"type":"string"},"os_bucket":{"type":"string"},"os_key":{"type":"string"}},"type":"object"},"nullable":true,"type":"array"},"content":{"description":"原文，可能含 \u003creport\u003e/\u003centity\u003e 等业务 XML 标签，解析责任在客户端","type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"role":{"enum":["user","assistant"],"type":"string"},"tasks":{"items":{"properties":{"completed_at":{"format":"date-time","type":"string"},"created_at":{"format":"date-time","type":"string"},"display_name":{"type":"string"},"result_type":{"description":"Result type (default report; currently 3 values, may expand in future)","enum":["image","video","report"],"type":"string"},"status":{"description":"Task status","enum":["pending","running","completed","failed","cancelled"],"type":"string"},"task_id":{"type":"string"},"tool_name":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"}},"required":["messages"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"description":"SESSION_NOT_FOUND — Session does not exist or does not belong to the current user (merged semantics to avoid probing existence via status code)"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Get a session's messages","tags":["Trenz Agent/2.Sessions \u0026 Reports"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/sessions/{sid}/reports":{"get":{"description":"Returns all reports generated in the given session, ordered by `created_at` DESC. Free endpoint.","operationId":"get-session-reports","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"Session ID","in":"path","name":"sid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"reports":[{"content":"Markdown 内容","created_at":"2026-05-20T10:00:00Z","id":"rpt-xxxx","message_id":"msg-xxxx","title":"报告标题","updated_at":"2026-05-20T10:01:00Z"}]},"request_id":"req-xxxx"},"schema":{"properties":{"data":{"properties":{"reports":{"items":{"properties":{"content":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"message_id":{"type":"string"},"title":{"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"type":"object"},"type":"array"}},"required":["reports"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"description":"SESSION_NOT_FOUND — Session does not exist or does not belong to the current user (merged semantics to avoid probing existence via status code)"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Get all reports of a session","tags":["Trenz Agent/2.Sessions \u0026 Reports"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/social/accounts/list":{"post":{"description":"List social accounts with full metrics (followers, engagement, shoppable data, etc.). sort_by supports ranking by followers / views / likes / comments / shares / engagement / gmv / orders; filter by platform, status, group or keyword.","operationId":"trenz-social-accounts-list","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"filter_unread":{"description":"Filter by unread comments. true = only return accounts with unread comments, false = only return accounts without unread comments, omit = no filtering","type":"boolean"},"group_id":{"description":"Filter by group. Pass a numeric ID to filter a specific group; pass \"ungrouped\" to filter ungrouped accounts; omit or pass an empty string to return all","type":"string"},"keyword":{"description":"Search keyword, matched against username, display name, and remark (fuzzy search)","type":"string"},"page":{"default":1,"description":"Page number, starting from 1","minimum":1,"type":"integer"},"page_size":{"default":10,"description":"Items per page, default 10","maximum":50,"type":"integer"},"platform_account_ids":{"description":"Filter by exact account ID; pass a list of account IDs","items":{"type":"integer"},"type":"array"},"platforms":{"description":"Filter by platform (multi-select). Allowed values: tiktok / tiktok-shop-pc / instagram / youtube / facebook","items":{"type":"string"},"type":"array"},"sort_by":{"default":"created_at","description":"Sort field. Allowed values: created_at (default) / display_name / followers / total_content / views / likes / comments / shares / favorites / engagement / avg_views / gmv / orders / last_synced","type":"string"},"sort_order":{"default":"desc","description":"Sort direction. Allowed values: desc (default, descending) / asc (ascending)","type":"string"},"statuses":{"description":"Filter by status (multi-select). Allowed values: active / expired","items":{"type":"string"},"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"accounts":{"items":{"properties":{"account_type":{"description":"Account type: creator / business","type":"string"},"avatar_url":{"description":"Avatar URL","type":"string"},"avg_views_per_content":{"description":"Average views per content; not returned when there is no content","type":"number"},"created_at":{"description":"Bind time (Unix timestamp, seconds)","type":"integer"},"display_name":{"description":"Account display name","type":"string"},"engagement_rate":{"description":"Engagement rate (%), calculated as (likes + comments + shares + favorites) / views × 100","type":"number"},"followers":{"description":"Follower count","type":"integer"},"gmv":{"description":"GMV amount (returned only for TikTok Shop accounts)","type":"number"},"gmv_currency":{"description":"GMV currency (returned only for TikTok Shop accounts)","type":"string"},"group_id":{"description":"Group ID the account belongs to; null means ungrouped","type":"integer"},"group_name":{"description":"Name of the group the account belongs to","type":"string"},"id":{"description":"Account ID (internal system identifier)","type":"integer"},"image_count":{"description":"Number of images","type":"integer"},"items_sold":{"description":"Items sold (returned only for TikTok Shop accounts)","type":"integer"},"orders":{"description":"Number of orders (returned only for TikTok Shop accounts)","type":"integer"},"platform":{"description":"Platform identifier: tiktok / tiktok-shop-pc / instagram / youtube / facebook","type":"string"},"region":{"description":"Account region (returned only for TikTok Shop accounts, e.g. US / GB)","type":"string"},"remark":{"description":"User-defined remark","type":"string"},"status":{"description":"Account status: active (normal) / expired (token expired)","type":"string"},"sync_updated_at":{"description":"Last data sync time (Unix timestamp, seconds). null means not yet synced","type":"integer"},"token_expires_at":{"description":"OAuth token expiration time (Unix timestamp, seconds)","type":"integer"},"total_comments":{"description":"Total comments","type":"integer"},"total_content_count":{"description":"Total published content count (videos + images + carousels)","type":"integer"},"total_favorites":{"description":"Total favorites (returned only for TikTok / Instagram)","type":"integer"},"total_likes":{"description":"Total likes","type":"integer"},"total_shares":{"description":"Total shares (not returned for YouTube)","type":"integer"},"total_views":{"description":"Total views","type":"integer"},"unread_comment_count":{"description":"Number of unread comments","type":"integer"},"username":{"description":"Platform username","type":"string"},"video_count":{"description":"Number of videos","type":"integer"}},"type":"object"},"type":"array"},"platform_counts":{"description":"Account count per platform. Always returns five entries: tiktok / tiktok-shop-pc / instagram / youtube / facebook, including those with a count of 0","items":{"properties":{"count":{"description":"Number of accounts on this platform","type":"integer"},"platform":{"description":"Platform identifier","type":"string"}},"type":"object"},"type":"array"},"total":{"description":"Total number of accounts matching the filter criteria","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Social Account List","tags":["Social/1.Account Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/analytics/account-trend":{"post":{"description":"Returns daily metric time series and summary for each account within a specified time range. Includes views, likes, comments, shares, favorites, engagement rate, followers, posts, avg views per post, GMV and more. Supports sorting and pagination.","operationId":"trenz-social-analytics-account-trend","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"end_time":{"description":"截止时间（Unix 秒），建议跨度不超过 35 天","type":"integer"},"page":{"default":1,"description":"页码，默认 1","type":"integer"},"page_size":{"default":10,"description":"每页条数，默认 10，最大 20","maximum":20,"type":"integer"},"platform_account_ids":{"description":"按账号 ID 筛选","items":{"type":"integer"},"type":"array"},"platforms":{"description":"平台筛选。如 [\"tiktok\", \"instagram\"]","items":{"type":"string"},"type":"array"},"sort_by":{"default":"views","description":"排序指标。可选值：views（播放量，默认）/ likes（点赞）/ comments（评论）/ shares（分享）/ favorites（收藏）/ posts（发帖数）/ followers（粉丝变化）/ gmv（销售额）/ orders（订单数）","type":"string"},"sort_order":{"default":"desc","description":"排序方向。可选值：desc（降序，默认）/ asc（升序）","type":"string"},"start_time":{"description":"起始时间（Unix 秒）","type":"integer"}},"required":["start_time","end_time"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"accounts":{"description":"账号趋势数据列表","items":{"properties":{"anchor_display_rate":{"description":"锚点展示率（仅 TikTok Shop，0-1 小数）","type":"number"},"avatar_url":{"description":"头像 URL","type":"string"},"avg_views_per_post":{"description":"均播 = total_views / total_posts","type":"integer"},"click_through_rate":{"description":"点击率（仅 TikTok Shop，0-1 小数）","type":"number"},"daily":{"description":"每日指标序列（从 data_start_date 开始）","items":{"properties":{"anchor_display_rate":{"description":"当天锚点展示率（仅 TikTok Shop）","type":"number"},"avg_views":{"description":"当天均播 = views/posts","type":"integer"},"click_through_rate":{"description":"当天点击率（仅 TikTok Shop）","type":"number"},"comments":{"description":"日增评论","type":"integer"},"date":{"description":"日期 YYYY-MM-DD","type":"string"},"engagement_rate":{"description":"当天互动率 (%) = (likes+comments+shares+favorites)/views*100","type":"number"},"favorites":{"description":"日增收藏","type":"integer"},"followers":{"description":"当天粉丝数（快照值，非增量）","type":"integer"},"gmv":{"description":"当天 GMV（仅 TikTok Shop）","type":"number"},"items_sold":{"description":"当天售出件数（仅 TikTok Shop）","type":"integer"},"likes":{"description":"日增点赞","type":"integer"},"orders":{"description":"当天订单数（仅 TikTok Shop）","type":"integer"},"posts":{"description":"当天发帖数","type":"integer"},"shares":{"description":"日增分享","type":"integer"},"views":{"description":"日增播放","type":"integer"}},"type":"object"},"type":"array"},"data_start_date":{"description":"首次有数据的日期 YYYY-MM-DD，图表从此日开始","type":"string"},"display_name":{"description":"显示名称","type":"string"},"engagement_rate":{"description":"综合互动率 (%) = (likes+comments+shares+favorites)/views*100","type":"number"},"followers":{"description":"区间末粉丝数（快照值）","type":"integer"},"followers_change":{"description":"区间粉丝变化（末日 - 首日）","type":"integer"},"gmv":{"description":"GMV 销售额（仅 TikTok Shop）","type":"number"},"gmv_currency":{"description":"GMV 币种（目前全部 USD）","type":"string"},"image_count":{"description":"图片数量","type":"integer"},"items_sold":{"description":"售出件数（仅 TikTok Shop）","type":"integer"},"orders":{"description":"订单数（仅 TikTok Shop）","type":"integer"},"platform":{"description":"平台（tiktok / tiktok-shop-pc / instagram）","type":"string"},"platform_account_id":{"description":"账号 ID","type":"integer"},"region":{"description":"地区（仅 shop 账号）","type":"string"},"sync_updated_at":{"description":"数据最后同步时间戳（Unix 秒）","type":"integer"},"total_comments":{"description":"区间评论增量","type":"integer"},"total_favorites":{"description":"区间收藏增量","type":"integer"},"total_likes":{"description":"区间点赞增量","type":"integer"},"total_posts":{"description":"区间发帖数","type":"integer"},"total_shares":{"description":"区间分享增量","type":"integer"},"total_views":{"description":"区间播放增量","type":"integer"},"username":{"description":"用户名","type":"string"},"video_count":{"description":"视频数量","type":"integer"}},"type":"object"},"type":"array"},"total":{"description":"符合条件的账号总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Account Data Trend","tags":["Social/5.Analytics"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/analytics/overview":{"post":{"description":"Social analytics dashboard for a given period: core KPI cards (views / engagement rate / followers / GMV / orders / items sold, with period-over-period change), platform split, account split, and an AI-generated period brief. The comparison period is the adjacent preceding time span of equal length.\n\n[Changelog 2026-07] The data source has been upgraded to the new analytics dashboard. The response structure is fully redesigned: period-over-period change rates, platform/account splits and AI brief are added; the old flat overview structure is no longer returned. Please integrate against the latest response fields.","operationId":"trenz-social-analytics-overview","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"end_time":{"description":"Period end time (Unix seconds)","type":"integer"},"platform":{"default":"all","description":"Platform filter. Options: all (default, returns the platforms split) / tiktok / tiktok-shop-pc (TikTok Shop) / instagram / youtube","type":"string"},"start_time":{"description":"Period start time (Unix seconds). Together with end_time defines the current period; the comparison period is the adjacent preceding span of equal length","type":"integer"}},"required":["start_time","end_time"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"accounts":{"description":"Per-account split. With platform=all only shop accounts are included (GMV/orders breakdown); with a specific platform, all accounts of that platform (click to expand detailed fields)","items":{"properties":{"avatar_url":{"description":"Avatar URL (temporary signed link; do not persist)","type":"string"},"display_name":{"description":"Account display name","type":"string"},"engagement_detail":{"description":"Likes/comments/shares breakdown (click to expand detailed fields)","properties":{"comments":{"description":"Comments gained in the period","type":"integer"},"likes":{"description":"Likes gained in the period","type":"integer"},"shares":{"description":"Shares gained in the period","type":"integer"}},"type":"object"},"engagement_rate":{"description":"Engagement rate percentage for the period","type":"number"},"engagement_rate_change":{"description":"Engagement rate change (ratio)","type":"number"},"follower_growth":{"description":"Net follower growth in the period (may be omitted for newly connected accounts)","type":"integer"},"followers":{"description":"Current total followers","type":"integer"},"gmv":{"description":"GMV in the period (shop accounts only)","type":"number"},"gmv_currency":{"description":"Currency (shop accounts only)","type":"string"},"platform":{"description":"Platform of the account","type":"string"},"platform_account_id":{"description":"Account ID, same as id in Social Account List","type":"integer"},"username":{"description":"Platform username (e.g. @kitchen_tips)","type":"string"},"view_share":{"description":"Share of views across all accounts (0.66 means 66%)","type":"number"},"views":{"description":"Views gained in the period","type":"integer"}},"type":"object"},"type":"array"},"brief":{"description":"AI period brief generated from rule templates; language follows the request locale (click to expand detailed fields)","properties":{"main":{"description":"Core summary, 1-3 sentences with attribution (e.g. Views up 23% to 95.1K, driven by TikTok (61% share))","type":"string"},"warning":{"description":"Action reminder (e.g. a platform metric dropped and why); omitted when nothing unusual","type":"string"}},"type":"object"},"metrics":{"description":"KPI cards, one item per core metric (click to expand detailed fields)","items":{"properties":{"change_rate":{"description":"Period-over-period change rate (ratio, 0.23 means +23%). Omitted when the previous period has no data","type":"number"},"currency":{"description":"Currency code (only for gmv / orders / items_sold, e.g. USD)","type":"string"},"engagement_detail":{"description":"Engagement breakdown, only for the engagement_rate metric (click to expand detailed fields)","properties":{"comments":{"description":"Comments gained in the period","type":"integer"},"likes":{"description":"Likes gained in the period","type":"integer"},"shares":{"description":"Shares gained in the period","type":"integer"}},"type":"object"},"metric":{"description":"Metric name. Possible values: views / engagement_rate / followers / gmv / orders / items_sold","type":"string"},"secondary_label":{"description":"Label describing secondary_value","type":"string"},"secondary_value":{"description":"Secondary value paired with secondary_label","type":"number"},"value":{"description":"Primary value. engagement_rate is a percentage number (4.2 means 4.2%); others are raw values","type":"number"}},"type":"object"},"type":"array"},"period":{"description":"Period info. Change rates are computed against the previous period of equal length (click to expand detailed fields)","properties":{"end_date":{"description":"Current period end date, YYYY-MM-DD","type":"string"},"previous_end_date":{"description":"Previous period end date, YYYY-MM-DD","type":"string"},"previous_start_date":{"description":"Previous period start date, YYYY-MM-DD","type":"string"},"start_date":{"description":"Current period start date, YYYY-MM-DD","type":"string"}},"type":"object"},"platforms":{"description":"Per-platform split, returned only when platform=all (click to expand detailed fields)","items":{"properties":{"account_count":{"description":"Number of accounts on this platform","type":"integer"},"engagement_detail":{"description":"Likes/comments/shares breakdown (omitted for shop accounts) (click to expand detailed fields)","properties":{"comments":{"description":"Comments gained in the period","type":"integer"},"likes":{"description":"Likes gained in the period","type":"integer"},"shares":{"description":"Shares gained in the period","type":"integer"}},"type":"object"},"engagement_rate":{"description":"Engagement rate percentage for the period (omitted for shop accounts)","type":"number"},"engagement_rate_change":{"description":"Engagement rate change (ratio)","type":"number"},"followers":{"description":"Total followers (omitted for shop accounts)","type":"integer"},"gmv":{"description":"GMV in the period (tiktok-shop-pc only)","type":"number"},"gmv_currency":{"description":"GMV currency (tiktok-shop-pc only)","type":"string"},"platform":{"description":"Platform: tiktok / tiktok-shop-pc / instagram / youtube","type":"string"},"views":{"description":"Views gained in the period (omitted for shop accounts)","type":"integer"}},"type":"object"},"type":"array"},"posts_count":{"description":"Posts published in the current period","type":"integer"},"posts_count_prev":{"description":"Posts published in the previous period; subtract from posts_count for the delta","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Analytics Overview","tags":["Social/5.Analytics"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/analytics/top-products":{"post":{"description":"Rank top products by sales metric.","operationId":"trenz-social-analytics-top-products","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_types":{"description":"Account type filter. Allowed values: creator / business","items":{"type":"string"},"type":"array"},"end_date":{"description":"End date (YYYY-MM-DD)","type":"string"},"limit":{"default":10,"description":"Number to return, default 10, max 50","maximum":50,"type":"integer"},"metric":{"description":"Sort metric. Allowed values: gmv (GMV amount) / orders / video_count (number of associated videos)","type":"string"},"platform_account_ids":{"description":"Filter by account ID","items":{"type":"integer"},"type":"array"},"start_date":{"description":"Start date (YYYY-MM-DD), defaults to last 7 days if omitted","type":"string"}},"required":["metric"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"products":{"description":"Product ranking, sorted by metric value descending","items":{"properties":{"image_url":{"description":"Product main image URL","type":"string"},"platform_product_id":{"description":"Platform-side product ID","type":"string"},"price_amount":{"description":"Product price","type":"number"},"price_currency":{"description":"Price currency","type":"string"},"product_id":{"description":"Product ID (internal system identifier)","type":"integer"},"title":{"description":"Product name","type":"string"},"total_gmv":{"description":"Total GMV during the statistics period","type":"number"},"total_items_sold":{"description":"Total items sold during the statistics period","type":"integer"},"total_orders":{"description":"Total orders during the statistics period","type":"integer"},"video_count":{"description":"Number of associated videos","type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Top Products Ranking","tags":["Social/5.Analytics"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/analytics/top-videos":{"post":{"description":"Rank top videos by metric.","operationId":"trenz-social-analytics-top-videos","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_types":{"description":"Account type filter. Allowed values: creator / business","items":{"type":"string"},"type":"array"},"end_date":{"description":"End date (YYYY-MM-DD)","type":"string"},"limit":{"default":10,"description":"Number of results, default 10, max 50","maximum":50,"type":"integer"},"metric":{"description":"Sort metric. Allowed values: views / likes / comments / shares / gmv","type":"string"},"platform_account_ids":{"description":"Filter by account IDs","items":{"type":"integer"},"type":"array"},"platforms":{"description":"Platform filter, e.g. [\"tiktok\", \"instagram\"]","items":{"type":"string"},"type":"array"},"start_date":{"description":"Start date (YYYY-MM-DD), defaults to last 7 days if omitted","type":"string"}},"required":["metric"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"videos":{"description":"Video ranking, sorted by metric value descending","items":{"properties":{"account_avatar_url":{"description":"Account avatar URL","type":"string"},"account_display_name":{"description":"Account display name","type":"string"},"anchor_display_rate":{"description":"Product anchor display rate (%, only returned for shoppable videos)","type":"number"},"click_through_rate":{"description":"Click-through rate (%, only returned for shoppable videos)","type":"number"},"comment_count":{"description":"Comments","type":"integer"},"cover_url":{"description":"Cover image URL","type":"string"},"gmv_amount":{"description":"GMV amount (only returned for shoppable videos)","type":"number"},"gmv_currency":{"description":"GMV currency","type":"string"},"item_sold_count":{"description":"Number of items sold (only returned for shoppable videos)","type":"integer"},"like_count":{"description":"Likes","type":"integer"},"metric_growth":{"description":"Growth of the sort metric during the statistics period","type":"integer"},"order_count":{"description":"Number of orders (only returned for shoppable videos)","type":"integer"},"platform":{"description":"Platform identifier","type":"string"},"platform_account_id":{"description":"ID of the account it belongs to","type":"integer"},"platform_url":{"description":"Video URL on the platform","type":"string"},"platform_video_id":{"description":"Platform-side video ID","type":"string"},"product_id":{"description":"Associated product ID (only returned for shoppable videos)","type":"string"},"product_image_url":{"description":"Associated product main image URL (only returned for shoppable videos)","type":"string"},"product_title":{"description":"Associated product name (only returned for shoppable videos)","type":"string"},"published_at":{"description":"Publish time (Unix timestamp in seconds)","type":"integer"},"region":{"description":"Account region (only returned for TikTok Shop)","type":"string"},"share_count":{"description":"Shares","type":"integer"},"video_title":{"description":"Video title","type":"string"},"view_count":{"description":"Views","type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Top Videos Ranking","tags":["Social/5.Analytics"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/comments/create":{"post":{"description":"Post a new comment under a video as the bound account.","operationId":"trenz-social-comments-create","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"Platform account ID","type":"integer"},"platform_video_id":{"description":"Platform video ID","type":"string"},"text":{"description":"Comment content","type":"string"}},"required":["platform_account_id","platform_video_id","text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"comment":{"properties":{"author":{"properties":{"display_name":{"description":"Commenter display name","type":"string"},"username":{"description":"Commenter username","type":"string"}},"type":"object"},"like_count":{"description":"Like count","type":"integer"},"platform":{"description":"Platform identifier","type":"string"},"platform_comment_id":{"description":"Platform-side comment ID","type":"string"},"platform_video_id":{"description":"Platform ID of the video it belongs to","type":"string"},"published_at":{"description":"Publish time (Unix timestamp in seconds)","type":"integer"},"reply_count":{"description":"Reply count","type":"integer"},"text":{"description":"Comment content","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Create Comment","tags":["Social/4.Comment Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/comments/delete":{"post":{"description":"Delete a comment on the platform and update local state.\n\nNote: due to a TikTok API restriction, only comments posted by **your own account** can be deleted. Comments left by other users on your video cannot be deleted — use Hide Comment (POST /open/v1/social/comments/hide) to make them invisible to other users instead.","operationId":"trenz-social-comments-delete","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"Platform account ID","type":"integer"},"platform_comment_id":{"description":"Comment ID","type":"string"},"platform_video_id":{"description":"Platform video ID","type":"string"}},"required":["platform_account_id","platform_video_id","platform_comment_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"comment":{"properties":{"is_deleted":{"description":"Whether it has been deleted","type":"boolean"},"platform":{"description":"Platform identifier","type":"string"},"platform_comment_id":{"description":"Platform-side comment ID","type":"string"},"text":{"description":"Comment content","type":"string"}},"type":"object"},"success":{"description":"Whether the operation succeeded","type":"boolean"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Delete Comment","tags":["Social/4.Comment Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/comments/hide":{"post":{"description":"Hide or unhide a comment posted by **another user** on your video. Hidden comments become invisible to other users (status HIDDEN) and can be unhidden at any time.\n\nWhich endpoint to use: unwanted comments from other users → hide them with this endpoint; comments posted by your own account → use Delete Comment (the TikTok API can only delete comments posted by your own account).","operationId":"trenz-social-comments-hide","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"hidden":{"description":"true = hide the comment (invisible to other users), false = unhide (restore visibility)","type":"boolean"},"platform_account_id":{"description":"Platform account ID (the video owner's account), from the id field returned by Social Account List","type":"integer"},"platform_comment_id":{"description":"Comment ID to hide, from the platform_comment_id field returned by Managed Comment List or Reply List","type":"string"}},"required":["platform_account_id","platform_comment_id","hidden"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"hidden":{"description":"The comment's hidden state after the operation: true = hidden, false = visible","type":"boolean"},"success":{"description":"Whether the operation succeeded","type":"boolean"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Hide Comment","tags":["Social/4.Comment Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/comments/like":{"post":{"description":"Like or unlike a comment on the platform.","operationId":"trenz-social-comments-like","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"action":{"description":"Action: like/unlike","type":"string"},"platform_account_id":{"description":"Platform account ID","type":"integer"},"platform_comment_id":{"description":"Comment ID","type":"string"},"platform_video_id":{"description":"Platform video ID","type":"string"}},"required":["platform_account_id","platform_video_id","platform_comment_id","action"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"comment":{"properties":{"is_liked":{"description":"Current like status (after the operation)","type":"boolean"},"like_count":{"description":"Latest like count","type":"integer"},"platform":{"description":"Platform identifier","type":"string"},"platform_comment_id":{"description":"Platform-side comment ID","type":"string"},"text":{"description":"Comment content","type":"string"}},"type":"object"},"success":{"description":"Whether the operation succeeded","type":"boolean"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Like Comment","tags":["Social/4.Comment Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/comments/managed":{"post":{"description":"Query synced **top-level comments** (comments directly under a video) from the local database, with filters for account/platform/video, keyword search, read status and hidden status. Call \"Sync Comments\" first to pull platform comments.\n\nDifference from Reply List: this endpoint returns top-level comments under videos; to page through the replies under a specific comment, pass that comment's platform_comment_id to Managed Reply List (POST /open/v1/social/comments/managed/replies).","operationId":"trenz-social-comments-managed-list","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"engaged":{"description":"Brand engagement filter. true = only comments that have been replied to (is_owner_replied=true)","type":"boolean"},"include_replies":{"description":"Whether to inline-return replies under each comment","type":"boolean"},"is_deleted":{"description":"Deleted status filter. true = deleted comments only, false = non-deleted only (default)","type":"boolean"},"is_hidden":{"description":"Hidden status filter. true = hidden comments only, false = visible comments only (default)","type":"boolean"},"is_read":{"description":"Read status filter. true = read only, false = unread only, omitted = all","type":"boolean"},"keyword":{"description":"Search keyword, matches comment content","type":"string"},"limit":{"default":20,"description":"Items per page, default 20, max 100","maximum":100,"type":"integer"},"max_replies":{"description":"Maximum number of replies to return per comment (only effective when include_replies=true)","type":"integer"},"owner_replied":{"description":"Replied filter. true = replied, false = not replied. Similar to engaged but more direct in meaning","type":"boolean"},"page":{"default":1,"description":"Page number, starting from 1","minimum":1,"type":"integer"},"platform_account_ids":{"description":"Filter by account ID","items":{"type":"integer"},"type":"array"},"platform_video_id":{"description":"Platform-side video ID, to filter comments under a specific video","type":"string"},"platforms":{"description":"Platform filter (multiple). Allowed values: tiktok / instagram / youtube / facebook","items":{"type":"string"},"type":"array"},"published_after":{"description":"Comment publish time start (Unix timestamp in seconds)","type":"integer"},"published_before":{"description":"Comment publish time end (Unix timestamp in seconds)","type":"integer"},"sort_by":{"description":"Sort field. Allowed values: published_at (default) / like_count","type":"string"},"sort_order":{"description":"Sort direction. Allowed values: desc (default) / asc","type":"string"},"view_mode":{"description":"View mode. Allowed values: priority (cross-video aggregation, sorted by AI priority). Omitted = normal list","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"comments":{"items":{"properties":{"ai_context_hint":{"description":"AI business context hint (only returned for opportunity comments)","type":"string"},"ai_intent":{"description":"AI intent classification: purchase_intent / negative_sentiment / high_value_user / collab_partnership / general / new_comment","type":"string"},"ai_priority":{"description":"AI priority: opportunity (business opportunity) / routine","type":"string"},"ai_priority_score":{"description":"AI priority score (0.0-1.0)","type":"number"},"author":{"properties":{"avatar_url":{"description":"Commenter avatar URL","type":"string"},"display_name":{"description":"Commenter display name","type":"string"},"username":{"description":"Commenter username","type":"string"}},"type":"object"},"id":{"description":"Comment record ID (internal system identifier)","type":"integer"},"is_deleted":{"description":"Whether deleted","type":"boolean"},"is_hidden":{"description":"Whether hidden","type":"boolean"},"is_liked":{"description":"Whether you have liked this comment","type":"boolean"},"is_owner_replied":{"description":"Whether this comment has been replied to","type":"boolean"},"is_read":{"description":"Whether read","type":"boolean"},"is_self_comment":{"description":"Whether it is your own comment","type":"boolean"},"like_count":{"description":"Comment like count","type":"integer"},"platform":{"description":"Source platform: tiktok / instagram / youtube","type":"string"},"platform_account_id":{"description":"ID of the account the comment belongs to","type":"integer"},"platform_comment_id":{"description":"Platform-side comment ID","type":"string"},"platform_video_id":{"description":"Platform ID of the video the comment belongs to","type":"string"},"published_at":{"description":"Comment publish time (Unix timestamp in seconds)","type":"integer"},"reply_count":{"description":"Reply count","type":"integer"},"text":{"description":"Comment content","type":"string"}},"type":"object"},"type":"array"},"limit":{"description":"Items per page","type":"integer"},"page":{"description":"Current page number","type":"integer"},"total_count":{"description":"Total number of matching comments","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Managed Comment List","tags":["Social/4.Comment Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/comments/managed/replies":{"post":{"description":"List the synced **replies under a specific comment** (pass the parent comment's platform_comment_id). Data comes from the \"Sync Comments\" operation. Uses offset-based pagination.\n\nDifference from Managed Comment List: Managed Comment List returns top-level comments under videos; this endpoint returns the replies under one of those comments. Typical flow: fetch top-level comments first, then call this endpoint for comments with reply_count \u003e 0.","operationId":"trenz-social-comments-managed-replies","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"is_deleted":{"description":"Filter by deleted status. true = only deleted replies, false = only non-deleted replies","type":"boolean"},"is_hidden":{"description":"Filter by hidden status. true = only hidden replies, false = only visible replies","type":"boolean"},"limit":{"default":20,"description":"Items per page, default 20","maximum":100,"type":"integer"},"page":{"default":1,"description":"Page number, starting from 1","minimum":1,"type":"integer"},"platform_account_id":{"description":"Account ID","type":"integer"},"platform_comment_id":{"description":"Platform-side ID of the parent comment","type":"string"}},"required":["platform_account_id","platform_comment_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"limit":{"description":"Items per page","type":"integer"},"page":{"description":"Current page number","type":"integer"},"replies":{"items":{"properties":{"author":{"properties":{"avatar_url":{"description":"Replier avatar URL","type":"string"},"display_name":{"description":"Replier display name","type":"string"},"username":{"description":"Replier username","type":"string"}},"type":"object"},"id":{"description":"Reply record ID (internal system identifier)","type":"integer"},"is_liked":{"description":"Whether you have liked this reply","type":"boolean"},"is_read":{"description":"Whether it has been read","type":"boolean"},"is_self_comment":{"description":"Whether the reply was posted by yourself","type":"boolean"},"like_count":{"description":"Like count","type":"integer"},"platform_comment_id":{"description":"Platform-side ID of the reply","type":"string"},"published_at":{"description":"Publish time (Unix timestamp in seconds)","type":"integer"},"text":{"description":"Reply content","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total number of replies","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Managed Reply List","tags":["Social/4.Comment Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/comments/reply":{"post":{"description":"Reply to a comment as the bound account.","operationId":"trenz-social-comments-reply","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"Platform account ID","type":"integer"},"platform_comment_id":{"description":"Comment ID","type":"string"},"platform_video_id":{"description":"Platform video ID","type":"string"},"text":{"description":"Reply content","type":"string"}},"required":["platform_account_id","platform_video_id","platform_comment_id","text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"reply":{"properties":{"author":{"properties":{"display_name":{"description":"Replier display name","type":"string"},"username":{"description":"Replier username","type":"string"}},"type":"object"},"like_count":{"description":"Like count","type":"integer"},"platform":{"description":"Platform identifier","type":"string"},"platform_comment_id":{"description":"Platform-side ID of the reply","type":"string"},"published_at":{"description":"Publish time (Unix timestamp in seconds)","type":"integer"},"text":{"description":"Reply content","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Reply to Comment","tags":["Social/4.Comment Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/comments/sync":{"post":{"description":"Trigger a sync to pull comments from the platform into the local database. Returns sync statistics. Use \"Managed Comment List\" to view synced results.","operationId":"trenz-social-comments-sync","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"Account ID. The system will fetch the latest comments on all videos under this account","type":"integer"},"platform_video_id":{"description":"Optional. The platform ID of a specific video; only that video's comments are synced. Omit to sync all videos under the account","type":"string"}},"required":["platform_account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"comments_synced":{"description":"Number of new comments synced this time","type":"integer"},"errors":{"description":"Number of errors that occurred during sync","type":"integer"},"replies_synced":{"description":"Number of new replies synced this time","type":"integer"},"videos_processed":{"description":"Number of videos processed this time","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Sync Comments","tags":["Social/4.Comment Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/hashtag/suggestions":{"post":{"description":"Get popular TikTok hashtag suggestions for a given keyword.","operationId":"trenz-social-hashtag-suggestions","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"keyword":{"description":"Search keyword (word)","type":"string"},"language":{"description":"Language code, default en","type":"string"}},"required":["keyword"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"from_cache":{"description":"Whether the result comes from cache. true = cache hit, false = fetched in real time from the TikTok API","type":"boolean"},"suggestions":{"description":"List of recommended hashtags, sorted by popularity in descending order","items":{"properties":{"name":{"description":"Hashtag name (without the # symbol)","type":"string"},"view_count":{"description":"Total view count of the hashtag","type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Hashtag Suggestions","tags":["Social/6.Creation Tools"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.social.read"}},"/open/v1/social/im/channels/list":{"post":{"description":"List bound social media DM channels across WhatsApp/WhatsApp Business/LINE/TikTok/Facebook/Instagram, with unread counts, sync status and platform health info","operationId":"trenz-social-im-channels-list","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"channel_ids":{"description":"Filter by exact channel IDs (multiple allowed)","example":["550e8400-e29b-41d4-a716-446655440000"],"items":{"type":"string"},"type":"array"},"filter_unread":{"description":"When true, only return channels with unread messages","example":true,"type":"boolean"},"limit":{"description":"Page size (required), 1-50","example":20,"type":"integer"},"name":{"description":"Fuzzy search keyword, matching channel name and remark; for WhatsApp channels also the bound phone number (+ signs and spaces ignored)","example":"support","type":"string"},"offset":{"description":"Pagination offset starting from 0, default 0; pass limit*1 for page 2, limit*2 for page 3, etc.","example":0,"type":"integer"},"order":{"description":"Sort direction: DESC (default) | ASC","enum":["DESC","ASC"],"example":"DESC","type":"string"},"order_by":{"description":"Sort field: created_at (binding time, default) | updated_at | name","enum":["created_at","updated_at","name"],"example":"created_at","type":"string"},"platform_connection_ids":{"description":"Filter by platform-side account identifiers (multiple allowed), e.g. WhatsApp phone numbers","example":["5216642344918"],"items":{"type":"string"},"type":"array"},"platform_type":{"description":"Filter by platform; omit for all platforms. A channel is one social media account bound to the DM system (one WhatsApp number / one TikTok account = one channel); a channel contains conversations with multiple contacts.","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"status":{"description":"Filter by status (multiple allowed): active | pending_approval | disconnected | suspended | deleted; defaults to active-only when omitted","example":["active"],"items":{"enum":["active","pending_approval","disconnected","suspended","deleted"],"type":"string"},"type":"array"}},"required":["limit","offset"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"data":{"description":"Channel list. A channel is one social media account bound to the DM system (one WhatsApp number / one TikTok account = one channel); a channel contains conversations with multiple contacts.","items":{"properties":{"ai_automation_level":{"description":"AI auto-reply level: off | autopilot (fully automatic)","enum":["off","autopilot"],"example":"off","type":"string"},"avatar":{"description":"Channel avatar URL (signed link, valid ~30 days)","example":"https://cdn.example.com/avatar/ch.jpg","type":"string"},"channel_id":{"description":"Channel ID (UUID format); input for the conversation list and other endpoints","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"created_at":{"description":"Binding time (Unix seconds)","example":1780000000,"type":"integer"},"name":{"description":"Channel name (social account name or bound phone number); falls back to the platform-side account identifier when empty","example":"Official Support WhatsApp","type":"string"},"platform":{"description":"Social platform: whatsapp (WhatsApp personal) | whatsapp_business (WhatsApp Business) | line | tiktok | facebook (Messenger) | instagram","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"platform_connection_id":{"description":"Platform-side account identifier: phone number for WhatsApp, phone_number_id for WhatsApp Business, Page ID for Facebook, IG account ID for Instagram","example":"5216642344918","type":"string"},"remark":{"description":"Channel remark","example":"Main account for TH market","type":"string"},"status":{"description":"Channel status: active | pending_approval | disconnected (needs re-auth) | suspended | deleted | pending_pin (2FA PIN required) | registration_failed (retryable)","enum":["active","pending_approval","disconnected","suspended","deleted","pending_pin","registration_failed"],"example":"active","type":"string"},"sync_status":{"description":"History sync status: pending | syncing | success | failed; absent if never synced","enum":["pending","syncing","success","failed"],"example":"success","type":"string"},"unread_count":{"description":"Total unread messages of this channel","example":12,"type":"integer"},"updated_at":{"description":"Last update time (Unix seconds)","example":1783670000,"type":"integer"},"user_id":{"description":"Owner user ID of the channel","example":"6a7ef569","type":"string"},"wa_account_review_status":{"description":"WhatsApp Business only: account review status","enum":["APPROVED","PENDING","REJECTED","VIOLATION"],"example":"APPROVED","type":"string"},"wa_health_snapshot":{"description":"WhatsApp Business only: health diagnostic snapshot (click to expand details)","properties":{"checked_at":{"description":"Last check time (Unix seconds)","example":1783670000,"type":"integer"},"issues":{"description":"Issue list; empty when healthy","items":{"properties":{"entity_type":{"description":"Entity type","enum":["PHONE_NUMBER","WABA","BUSINESS","APP","MESSAGE_TEMPLATE"],"example":"PHONE_NUMBER","type":"string"},"error_code":{"description":"Meta error code (BLOCKED only)","example":141000,"type":"integer"},"message":{"description":"Issue description","example":"Messaging limit reached","type":"string"},"severity":{"description":"Severity","enum":["LIMITED","BLOCKED"],"example":"LIMITED","type":"string"},"solution":{"description":"Actionable suggestion (BLOCKED only)","example":"Verify your business","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"Overall health: AVAILABLE | LIMITED | BLOCKED","enum":["AVAILABLE","LIMITED","BLOCKED"],"example":"AVAILABLE","type":"string"}},"type":"object"},"wa_messaging_limit":{"description":"WhatsApp Business only: tier of users reachable per 24h","enum":["TIER_50","TIER_250","TIER_1K","TIER_10K","TIER_100K","TIER_UNLIMITED"],"example":"TIER_1K","type":"string"},"wa_phone_status":{"description":"WhatsApp Business only: phone connection status","enum":["CONNECTED","OFFLINE","FLAGGED","RATE_LIMITED","BANNED","RESTRICTED"],"example":"CONNECTED","type":"string"},"wa_quality_rating":{"description":"WhatsApp Business only: number quality rating (GREEN is best)","enum":["GREEN","YELLOW","RED"],"example":"GREEN","type":"string"},"wa_verified_name":{"description":"WhatsApp Business only: Meta-verified business name","example":"Example Store","type":"string"}},"type":"object"},"type":"array"},"total":{"description":"Total matching channels (for pagination)","example":3,"type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"DM Channel List","tags":["Social/8.Direct Messages"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/im/channels/unread-count":{"post":{"description":"Aggregate unread message counts across DM channels, for badge display","operationId":"trenz-social-im-channels-unread-count","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"channel_ids":{"description":"Channel ID list; omit to count all active channels under the current account. Channels with zero unread are also returned. Get channel IDs via the DM Channel List endpoint (under Social/8.Direct Messages)","example":["550e8400-e29b-41d4-a716-446655440000"],"items":{"type":"string"},"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"data":{"description":"Per-channel unread counts","items":{"properties":{"channel_id":{"description":"Channel ID","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"platform":{"description":"Social platform: whatsapp (WhatsApp personal) | whatsapp_business (WhatsApp Business) | line | tiktok | facebook (Messenger) | instagram","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"unread_count":{"description":"Unread message count of this channel","example":12,"type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"DM Unread Count","tags":["Social/8.Direct Messages"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/im/conversations/list":{"post":{"description":"List DM conversations of a channel with pagination, keyword search, unread filter and AI tag filter","operationId":"trenz-social-im-conversations-list","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"channel_id":{"description":"Channel ID (required). A channel is one social media account bound to the DM system (one WhatsApp number / one TikTok account = one channel); a channel contains conversations with multiple contacts. Get it from the channel_id field of the DM Channel List endpoint (under Social/8.Direct Messages)","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"conversation_ids":{"description":"Filter by exact conversation IDs (multiple allowed)","example":["12345"],"items":{"type":"string"},"type":"array"},"filter_marked_unread":{"description":"When true, only return conversations manually marked as unread; ignored when keyword is used","example":false,"type":"boolean"},"filter_tag":{"description":"Filter by AI insight tag: kol (influencer) | b2b (B2B inquiry) | buyer | fan | general. See the Conversation Tag Counts endpoint for per-tag counts","enum":["kol","b2b","buyer","fan","general"],"example":"buyer","type":"string"},"filter_unread":{"description":"When true, only return conversations with unread messages","example":true,"type":"boolean"},"keyword":{"description":"Search keyword, matching conversation title and remark; for WhatsApp conversations also the contact phone number (+ signs and spaces ignored). Note: filter_marked_unread is ignored when keyword is used","example":"Somchai","type":"string"},"limit":{"description":"Page size (required), 1-50","example":20,"type":"integer"},"offset":{"description":"Pagination offset starting from 0, default 0; pass limit*1 for page 2, limit*2 for page 3, etc.","example":0,"type":"integer"}},"required":["channel_id","limit"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"data":{"description":"Conversation list, fixed order: pinned conversations first (by pin time ascending), then by last message time descending. A conversation is the message thread between a channel and a single contact (or group).","items":{"properties":{"auto_reply_paused":{"description":"Whether AI auto-reply is manually paused for this conversation","example":false,"type":"boolean"},"avatar":{"description":"Avatar URL: contact avatar for direct chats, group avatar for groups","example":"https://cdn.example.com/avatar/xxx.jpg","type":"string"},"channel_id":{"description":"Channel ID it belongs to","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"conversation_id":{"description":"Conversation ID (numeric string); input for message list / send endpoints","example":"12345","type":"string"},"external_id":{"description":"Original platform-side conversation/contact identifier (e.g. WhatsApp phone number)","example":"66812345678","type":"string"},"group_color":{"description":"Conversation group color","example":"#1677ff","type":"string"},"group_id":{"description":"Conversation group ID; absent if ungrouped","example":3,"type":"integer"},"group_name":{"description":"Conversation group name","example":"Priority follow-up","type":"string"},"is_pinned":{"description":"Whether pinned","example":false,"type":"boolean"},"labels":{"description":"Conversation labels (click to expand details)","items":{"properties":{"color":{"description":"Label color","example":"#722ed1","type":"string"},"id":{"description":"Label ID","example":7,"type":"integer"},"name":{"description":"Label name","example":"KOL Collab","type":"string"},"tag":{"description":"AI tag key: kol/b2b/buyer/fan/general; empty for manual labels","example":"kol","type":"string"}},"type":"object"},"type":"array"},"last_message":{"description":"Preview of the last message, for list display (click to expand details)","properties":{"content":{"description":"Message text; caption or empty for media messages","example":"Hi, is this item in stock?","type":"string"},"created_at":{"description":"Message time (Unix seconds)","example":1783670000,"type":"integer"},"direction":{"description":"Direction: inbound (from contact) | outbound (sent by you)","enum":["inbound","outbound"],"example":"inbound","type":"string"},"id":{"description":"Message ID","example":987654,"type":"integer"},"media":{"description":"Media preview, media messages only (click to expand details)","properties":{"filename":{"description":"File name","example":"photo.jpg","type":"string"},"mime_type":{"description":"MIME type","example":"image/jpeg","type":"string"},"type":{"description":"Media type","enum":["image","video","audio","document","sticker"],"example":"image","type":"string"},"url":{"description":"Media access URL (time-limited)","example":"https://cdn.example.com/im/xxx.jpg","type":"string"}},"type":"object"},"mentions":{"description":"Group-chat @mention mapping; @\u003cid\u003e tokens in content render to names via this list; absent when no mentions (click to expand details)","items":{"properties":{"id":{"description":"Mention token (phone number for individuals)","example":"8615626176095","type":"string"},"is_all":{"description":"Whether @everyone","example":false,"type":"boolean"},"name":{"description":"Display name","example":"John","type":"string"}},"type":"object"},"type":"array"},"message_type":{"description":"Message type: text | image | video | audio | document | sticker | gif | lottie | template (WhatsApp template) | location | reaction","enum":["text","image","video","audio","document","sticker","gif","lottie","template","location","reaction"],"example":"text","type":"string"},"platform_message_id":{"description":"Original platform-side message ID","example":"wamid.HBgLOD...","type":"string"},"sender_id":{"description":"Sender ID","example":"66812345678","type":"string"},"sender_name":{"description":"Sender name","example":"Somchai","type":"string"},"status":{"description":"Status: pending | sent | delivered | read | failed | revoked","enum":["pending","sent","delivered","read","failed","revoked"],"example":"read","type":"string"},"str_id":{"description":"String message ID (big-number safe); use this for quoted replies","example":"987654","type":"string"}},"type":"object"},"last_message_at":{"description":"Last message time (Unix seconds); list is sorted by this field descending","example":1783670000,"type":"integer"},"marked_unread":{"description":"Whether manually marked as unread","example":false,"type":"boolean"},"metadata":{"description":"Conversation metadata JSON string (group description etc.); empty if none","example":"{\"group_description\":\"VIP customers\"}","type":"string"},"owner_user_id":{"description":"Assigned agent user ID; empty if unassigned","example":"6a7ef569","type":"string"},"pinned_at":{"description":"Pinned time (Unix seconds); absent if not pinned","example":1783600000,"type":"integer"},"platform":{"description":"Social platform: whatsapp (WhatsApp personal) | whatsapp_business (WhatsApp Business) | line | tiktok | facebook (Messenger) | instagram","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"remark":{"description":"Conversation remark (set via Update Conversation Remark)","example":"Key account in Thailand","type":"string"},"title":{"description":"Conversation title: contact name for direct chats, group name for groups","example":"Somchai","type":"string"},"type":{"description":"Conversation type: 1 (direct) | 2 (group)","enum":[1,2],"example":1,"type":"integer"},"unread_count":{"description":"Unread message count of this conversation","example":2,"type":"integer"},"window_info":{"description":"Messaging window. Platforms restrict business-initiated messages to a time window (e.g. WhatsApp: within 24h after the customer's last message); sending outside the window fails. Check can_send_message before calling Send Direct Message (click to expand details)","properties":{"can_send_message":{"description":"Whether messages can currently be sent; false means Send Direct Message will fail with a window-closed error","example":true,"type":"boolean"},"csw_expires_at":{"description":"WhatsApp Business only: 24h Customer Service Window expiry (Unix seconds); 0 on other platforms","example":1783746400,"type":"integer"},"fep_expires_at":{"description":"WhatsApp Business only: 72h Free Entry Point window (ad-referral) expiry (Unix seconds); 0 on other platforms","example":0,"type":"integer"},"hours_remaining":{"description":"Hours remaining; negative means expired","example":20,"type":"integer"},"last_origin_type":{"description":"WhatsApp Business only: conversation origin (Meta-defined), e.g. user_initiated | marketing | referral_conversion","example":"user_initiated","type":"string"},"messages_sent":{"description":"Messages sent within the current window (for capped windows)","example":3,"type":"integer"},"window_expires_at":{"description":"Current window expiry (Unix seconds)","example":1783746400,"type":"integer"},"window_start_time":{"description":"Current window start (Unix seconds)","example":1783660000,"type":"integer"},"window_type":{"description":"Window type: unlimited | 24h | 48h_with_limit (48h with message cap). Actual per-platform values: WhatsApp personal/LINE = unlimited, WhatsApp Business/Facebook/Instagram = 24h, TikTok = 48h_with_limit (max 10 messages)","enum":["unlimited","24h","48h_with_limit"],"example":"24h","type":"string"}},"type":"object"}},"type":"object"},"type":"array"},"total":{"description":"Total matching conversations (for pagination)","example":87,"type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"DM Conversation List","tags":["Social/8.Direct Messages"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/im/conversations/tag-counts":{"post":{"description":"Count conversations per AI insight tag (KOL/B2B/Buyer/Fan/General) under a channel","operationId":"trenz-social-im-conversation-tag-counts","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"channel_id":{"description":"Channel ID (required). A channel is one social media account bound to the DM system (one WhatsApp number / one TikTok account = one channel); a channel contains conversations with multiple contacts. Get it from the channel_id field of the DM Channel List endpoint (under Social/8.Direct Messages)","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},"required":["channel_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"tags":{"description":"Conversation counts per AI insight tag (auto-assigned by AI); always returns all 5 tags including zero counts","items":{"properties":{"count":{"description":"Conversation count of this tag","example":25,"type":"integer"},"label":{"description":"Fixed English display name: KOL Collab | B2B Inquiry | Purchase Intent | Fan Engagement | General","example":"Purchase Intent","type":"string"},"tag":{"description":"Tag key: kol (influencer) | b2b (B2B inquiry) | buyer | fan | general","enum":["kol","b2b","buyer","fan","general"],"example":"buyer","type":"string"}},"type":"object"},"type":"array"},"total":{"description":"Total conversations of the channel","example":87,"type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Conversation Tag Counts","tags":["Social/8.Direct Messages"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/im/conversations/{id}":{"post":{"description":"Get details of a DM conversation, including participants and messaging window status","operationId":"trenz-social-im-conversation-detail","parameters":[{"description":"Conversation ID (numeric string). A conversation is the message thread between a channel and a single contact (or group). Get it from the conversation_id field of the DM Conversation List endpoint (under Social/8.Direct Messages)","in":"path","name":"id","required":true,"schema":{"example":"12345","type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"data":{"description":"Conversation detail; includes participants on top of the list item fields (click to expand details)","properties":{"auto_reply_paused":{"description":"Whether AI auto-reply is manually paused for this conversation","example":false,"type":"boolean"},"avatar":{"description":"Avatar URL: contact avatar for direct chats, group avatar for groups","example":"https://cdn.example.com/avatar/xxx.jpg","type":"string"},"channel_id":{"description":"Channel ID it belongs to","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"conversation_id":{"description":"Conversation ID (numeric string); input for message list / send endpoints","example":"12345","type":"string"},"external_id":{"description":"Original platform-side conversation/contact identifier (e.g. WhatsApp phone number)","example":"66812345678","type":"string"},"last_message":{"description":"Preview of the last message, for list display (click to expand details)","properties":{"content":{"description":"Message text; caption or empty for media messages","example":"Hi, is this item in stock?","type":"string"},"created_at":{"description":"Message time (Unix seconds)","example":1783670000,"type":"integer"},"direction":{"description":"Direction: inbound (from contact) | outbound (sent by you)","enum":["inbound","outbound"],"example":"inbound","type":"string"},"id":{"description":"Message ID","example":987654,"type":"integer"},"media":{"description":"Media preview, media messages only (click to expand details)","properties":{"filename":{"description":"File name","example":"photo.jpg","type":"string"},"mime_type":{"description":"MIME type","example":"image/jpeg","type":"string"},"type":{"description":"Media type","enum":["image","video","audio","document","sticker"],"example":"image","type":"string"},"url":{"description":"Media access URL (time-limited)","example":"https://cdn.example.com/im/xxx.jpg","type":"string"}},"type":"object"},"mentions":{"description":"Group-chat @mention mapping; @\u003cid\u003e tokens in content render to names via this list; absent when no mentions (click to expand details)","items":{"properties":{"id":{"description":"Mention token (phone number for individuals)","example":"8615626176095","type":"string"},"is_all":{"description":"Whether @everyone","example":false,"type":"boolean"},"name":{"description":"Display name","example":"John","type":"string"}},"type":"object"},"type":"array"},"message_type":{"description":"Message type: text | image | video | audio | document | sticker | gif | lottie | template (WhatsApp template) | location | reaction","enum":["text","image","video","audio","document","sticker","gif","lottie","template","location","reaction"],"example":"text","type":"string"},"platform_message_id":{"description":"Original platform-side message ID","example":"wamid.HBgLOD...","type":"string"},"sender_id":{"description":"Sender ID","example":"66812345678","type":"string"},"sender_name":{"description":"Sender name","example":"Somchai","type":"string"},"status":{"description":"Status: pending | sent | delivered | read | failed | revoked","enum":["pending","sent","delivered","read","failed","revoked"],"example":"read","type":"string"},"str_id":{"description":"String message ID (big-number safe); use this for quoted replies","example":"987654","type":"string"}},"type":"object"},"last_message_at":{"description":"Last message time (Unix seconds); list is sorted by this field descending","example":1783670000,"type":"integer"},"owner_user_id":{"description":"Assigned agent user ID; empty if unassigned","example":"6a7ef569","type":"string"},"participants":{"description":"Participants: the contact for direct chats, all members for groups (click to expand details)","items":{"properties":{"avatar":{"description":"Participant avatar URL","example":"https://cdn.example.com/avatar/p.jpg","type":"string"},"id":{"description":"Participant ID (e.g. WhatsApp phone number)","example":"66812345678","type":"string"},"is_admin":{"description":"Whether group admin (groups only)","example":false,"type":"boolean"},"is_super_admin":{"description":"Whether group owner (groups only)","example":false,"type":"boolean"},"name":{"description":"Participant name","example":"Somchai","type":"string"}},"type":"object"},"type":"array"},"platform":{"description":"Social platform: whatsapp (WhatsApp personal) | whatsapp_business (WhatsApp Business) | line | tiktok | facebook (Messenger) | instagram","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"remark":{"description":"Conversation remark (set via Update Conversation Remark)","example":"Key account in Thailand","type":"string"},"title":{"description":"Conversation title: contact name for direct chats, group name for groups","example":"Somchai","type":"string"},"type":{"description":"Conversation type: 1 (direct) | 2 (group)","enum":[1,2],"example":1,"type":"integer"},"unread_count":{"description":"Unread message count of this conversation","example":2,"type":"integer"},"window_info":{"description":"Messaging window. Platforms restrict business-initiated messages to a time window (e.g. WhatsApp: within 24h after the customer's last message); sending outside the window fails. Check can_send_message before calling Send Direct Message (click to expand details)","properties":{"can_send_message":{"description":"Whether messages can currently be sent; false means Send Direct Message will fail with a window-closed error","example":true,"type":"boolean"},"csw_expires_at":{"description":"WhatsApp Business only: 24h Customer Service Window expiry (Unix seconds); 0 on other platforms","example":1783746400,"type":"integer"},"fep_expires_at":{"description":"WhatsApp Business only: 72h Free Entry Point window (ad-referral) expiry (Unix seconds); 0 on other platforms","example":0,"type":"integer"},"hours_remaining":{"description":"Hours remaining; negative means expired","example":20,"type":"integer"},"last_origin_type":{"description":"WhatsApp Business only: conversation origin (Meta-defined), e.g. user_initiated | marketing | referral_conversion","example":"user_initiated","type":"string"},"messages_sent":{"description":"Messages sent within the current window (for capped windows)","example":3,"type":"integer"},"window_expires_at":{"description":"Current window expiry (Unix seconds)","example":1783746400,"type":"integer"},"window_start_time":{"description":"Current window start (Unix seconds)","example":1783660000,"type":"integer"},"window_type":{"description":"Window type: unlimited | 24h | 48h_with_limit (48h with message cap). Actual per-platform values: WhatsApp personal/LINE = unlimited, WhatsApp Business/Facebook/Instagram = 24h, TikTok = 48h_with_limit (max 10 messages)","enum":["unlimited","24h","48h_with_limit"],"example":"24h","type":"string"}},"type":"object"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"DM Conversation Detail","tags":["Social/8.Direct Messages"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/im/conversations/{id}/messages":{"post":{"description":"List messages of a DM conversation with type/time/keyword filters; optionally mark the conversation as read while fetching","operationId":"trenz-social-im-messages-list","parameters":[{"description":"Conversation ID (numeric string). A conversation is the message thread between a channel and a single contact (or group). Get it from the conversation_id field of the DM Conversation List endpoint (under Social/8.Direct Messages)","in":"path","name":"id","required":true,"schema":{"example":"12345","type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"end_time":{"description":"End time (Unix seconds); filters by server ingest time","example":1783670400,"type":"integer"},"keyword":{"description":"Search by message text content","example":"order","type":"string"},"limit":{"description":"Page size (required), 1-50","example":20,"type":"integer"},"mark_as_read":{"description":"When true, marks the conversation as read and clears its unread count; ALSO sends read receipts to the platform (e.g. WhatsApp blue ticks) visible to the contact — use deliberately","example":true,"type":"boolean"},"message_type":{"description":"Filter by message type: text | image | video | audio | document | sticker | gif | lottie | template | location | reaction","enum":["text","image","video","audio","document","sticker","gif","lottie","template","location","reaction"],"example":"image","type":"string"},"offset":{"description":"Pagination offset starting from 0, default 0; pass limit*1 for page 2, limit*2 for page 3, etc.","example":0,"type":"integer"},"order":{"description":"Sort direction: DESC (newest first, default) | ASC (oldest first)","enum":["DESC","ASC"],"example":"DESC","type":"string"},"order_by":{"description":"Sort field: sent_at (send time, default) | created_at (ingest time)","enum":["sent_at","created_at"],"example":"sent_at","type":"string"},"start_time":{"description":"Start time (Unix seconds); filters by server ingest time","example":1783584000,"type":"integer"}},"required":["limit"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"data":{"description":"Message list","items":{"properties":{"channel_id":{"description":"Channel ID it belongs to","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"content":{"description":"Message text; caption or empty for media messages","example":"Hi, is this item in stock?","type":"string"},"conversation_id":{"description":"Conversation ID it belongs to","example":"12345","type":"string"},"created_at":{"description":"Message send time (platform-side, Unix seconds); falls back to server ingest time","example":1783670000,"type":"integer"},"direction":{"description":"Direction: inbound (from contact) | outbound (sent by you)","enum":["inbound","outbound"],"example":"inbound","type":"string"},"error_code":{"description":"Platform error code when sending failed; absent on success","example":"131047","type":"string"},"error_message":{"description":"Error description when sending failed; absent on success","example":"Re-engagement message","type":"string"},"id":{"description":"Message ID","example":987654,"type":"integer"},"is_auto_reply":{"description":"Whether sent by AI auto-reply","example":false,"type":"boolean"},"is_imported":{"description":"Whether bulk-imported historical message (not real-time)","example":false,"type":"boolean"},"media":{"description":"Media content, media messages only (click to expand details)","properties":{"error_reason":{"description":"Reason the media is unavailable; absent when available","example":"media expired","type":"string"},"filename":{"description":"File name","example":"photo.jpg","type":"string"},"height":{"description":"Height in pixels (image/video)","example":1920,"type":"integer"},"mime_type":{"description":"MIME type","example":"image/jpeg","type":"string"},"status":{"description":"Returned as unavailable only when the media is inaccessible (e.g. expired on platform); absent when available","enum":["unavailable"],"example":"unavailable","type":"string"},"type":{"description":"Media type","enum":["image","video","audio","document","sticker"],"example":"image","type":"string"},"url":{"description":"Media access URL (signed link, valid ~30 days; consider re-hosting)","example":"https://cdn.example.com/im/xxx.jpg","type":"string"},"width":{"description":"Width in pixels (image/video)","example":1080,"type":"integer"}},"type":"object"},"mentions":{"description":"Group-chat @mention mapping; @\u003cid\u003e tokens in content render to names via this list (click to expand details)","items":{"properties":{"id":{"description":"Mention token matching \u003cid\u003e of @\u003cid\u003e in content (phone number for individuals)","example":"8615626176095","type":"string"},"is_all":{"description":"Whether @everyone","example":false,"type":"boolean"},"name":{"description":"Display name","example":"John","type":"string"}},"type":"object"},"type":"array"},"message_type":{"description":"Message type: text | image | video | audio | document | sticker | gif | lottie | template (WhatsApp template) | location | reaction","enum":["text","image","video","audio","document","sticker","gif","lottie","template","location","reaction"],"example":"text","type":"string"},"platform":{"description":"Social platform: whatsapp (WhatsApp personal) | whatsapp_business (WhatsApp Business) | line | tiktok | facebook (Messenger) | instagram","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"platform_message_id":{"description":"Original platform-side message ID","example":"wamid.HBgLOD...","type":"string"},"reactions":{"description":"Emoji reactions (click to expand details)","items":{"properties":{"emoji":{"description":"Emoji character","example":"👍","type":"string"},"is_self":{"description":"Whether reacted by your own account","example":false,"type":"boolean"},"ts":{"description":"Reaction time (Unix seconds)","example":1783670100,"type":"integer"},"user_id":{"description":"Reactor ID","example":"66812345678","type":"string"}},"type":"object"},"type":"array"},"reply_to":{"description":"The quoted message (single-level trimmed preview without sentiment/reactions/mentions; never nests recursively); absent for non-reply messages (click to expand details)","properties":{"content":{"description":"Quoted message content","example":"Do you have it in black?","type":"string"},"created_at":{"description":"Quoted message time (Unix seconds)","example":1783669000,"type":"integer"},"id":{"description":"Quoted message ID","example":987650,"type":"integer"},"message_type":{"description":"Quoted message type","example":"text","type":"string"},"sender_name":{"description":"Quoted message sender","example":"Somchai","type":"string"},"str_id":{"description":"Quoted message string ID","example":"987650","type":"string"}},"type":"object"},"sender_id":{"description":"Sender ID","example":"66812345678","type":"string"},"sender_name":{"description":"Sender name","example":"Somchai","type":"string"},"sent_by_platform":{"description":"Whether sent by your own account from another client (e.g. mobile app)","example":false,"type":"boolean"},"sentiment":{"description":"AI sentiment analysis, only for analyzed messages (click to expand details)","properties":{"emoji":{"description":"Message intent emoji","example":"🛒","type":"string"},"insight":{"description":"Key insight summary","example":"Customer shows clear purchase intent","type":"string"},"insight_label":{"description":"Message intent label","example":"Purchase inquiry","type":"string"},"key_phrases":{"description":"Key sentiment phrases (up to 5)","example":["in stock"],"items":{"type":"string"},"type":"array"},"label":{"description":"Sentiment label: positive | neutral | negative | angry","enum":["positive","neutral","negative","angry"],"example":"positive","type":"string"},"score":{"description":"Sentiment score, -1.0 (most negative) to 1.0 (most positive)","example":0.8,"type":"number"},"trend":{"description":"Sentiment trend: improving | stable | declining","example":"stable","type":"string"}},"type":"object"},"status":{"description":"Status: pending | sent | delivered | read | failed | revoked","enum":["pending","sent","delivered","read","failed","revoked"],"example":"read","type":"string"},"str_id":{"description":"String message ID (big-number safe); use this for quoted replies","example":"987654","type":"string"},"template_info":{"description":"WhatsApp template message info, only when message_type=template (click to expand details)","properties":{"components_json":{"description":"Template components JSON string (header/body/button)","example":"[{\"type\":\"body\",...}]","type":"string"},"language":{"description":"Template language code","example":"en_US","type":"string"},"name":{"description":"Template name","example":"order_confirmation","type":"string"},"status":{"description":"Template review status","enum":["PENDING","APPROVED","REJECTED","PAUSED","DISABLED"],"example":"APPROVED","type":"string"},"template_id":{"description":"Template ID","example":101,"type":"integer"}},"type":"object"}},"type":"object"},"type":"array"},"total":{"description":"Total matching messages (for pagination)","example":156,"type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"DM Message List","tags":["Social/8.Direct Messages"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/im/conversations/{id}/remark":{"post":{"description":"Update the remark of a DM conversation","operationId":"trenz-social-im-conversation-remark","parameters":[{"description":"Conversation ID (numeric string). A conversation is the message thread between a channel and a single contact (or group). Get it from the conversation_id field of the DM Conversation List endpoint (under Social/8.Direct Messages)","in":"path","name":"id","required":true,"schema":{"example":"12345","type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"remark":{"description":"Remark content; pass an empty string to clear; max 255 characters. Note: for WhatsApp direct chats the remark is synced as the contact display name on the platform side","example":"Key account, negotiating annual contract","type":"string"}},"required":["remark"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"description":"No business payload on success; use the envelope request_id to confirm","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Update Conversation Remark","tags":["Social/8.Direct Messages"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/im/messages/send":{"post":{"description":"Send a message to a DM conversation: text, image, video, audio, document, and quoted reply. For media, first call the DM Upload Presigned URL endpoint to upload the file.\n\nPrerequisites: the social account's binding authorization must include messaging permissions — accounts bound earlier need to re-authorize; TikTok DM requires a Business-type account (personal accounts can switch to Business for free in the TikTok app; re-scan the QR code after switching); Instagram / Facebook must be bound via the console. When prerequisites are not met, the channel will not appear in DM Channel List.\n\nNote: returns business error code 20510 when the messaging window is closed; identical content sent to the same conversation within 10 seconds hits idempotent dedup","operationId":"trenz-social-im-message-send","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"content":{"description":"Message text; strongly required for text type (the server does not validate — omitting it sends an empty text message), optional caption for media types","example":"Hi, the item is in stock. Order today and we ship tomorrow.","type":"string"},"conversation_id":{"description":"Conversation ID (required). Get it via the DM Conversation List endpoint (under Social/8.Direct Messages); check the conversation's window_info.can_send_message first — sending fails when the window is closed","example":"12345","type":"string"},"media":{"description":"Media info, required for media messages. Upload the file first via the DM Upload Presigned URL endpoint (under Social/8.Direct Messages) (click to expand details)","properties":{"filename":{"description":"File name with extension. Required — if omitted, the file name displayed in chat degrades to an unreadable storage token (e.g. upload_3f7a1c9e.pdf).","example":"photo.jpg","type":"string"},"height":{"description":"Image/video height in pixels, optional","example":1920,"type":"integer"},"mime_type":{"description":"MIME type, must match the upload","example":"image/jpeg","type":"string"},"s3_bucket":{"description":"Bucket name, from s3_bucket returned by DM Upload Presigned URL","example":"datanebula-object","type":"string"},"s3_key":{"description":"Object key of the uploaded file, from object_key returned by DM Upload Presigned URL","example":"im/2026/07/10/20260710153000_photo.jpg","type":"string"},"width":{"description":"Image/video width in pixels, optional","example":1080,"type":"integer"}},"required":["filename"],"type":"object"},"mentions":{"description":"Phone numbers to @mention in group chats (digits only, no +); WhatsApp groups only, must pair with @\u003cphone\u003e tokens in content","example":["8615626176095"],"items":{"type":"string"},"type":"array"},"message_type":{"description":"Message type (required): text | image | video | audio | document. Media types also require the media field","enum":["text","image","video","audio","document"],"example":"text","type":"string"},"reply_to":{"description":"str_id of the message being quoted (from a DM Message List item); omit for a normal message","example":"987650","type":"string"}},"required":["conversation_id","message_type"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"data":{"description":"Full detail of the sent message, same structure as a DM Message List item; usable directly without another list call (click to expand details)","properties":{"content":{"description":"Message text content","example":"Hi, the item is in stock. Order today and we ship tomorrow.","type":"string"},"conversation_id":{"description":"Conversation ID it belongs to","example":"12345","type":"string"},"created_at":{"description":"Message time (Unix seconds)","example":1783670200,"type":"integer"},"direction":{"description":"Direction, always outbound for sent messages","example":"outbound","type":"string"},"id":{"description":"Message ID","example":987655,"type":"integer"},"message_type":{"description":"Message type","example":"text","type":"string"},"status":{"description":"Message status","example":"sent","type":"string"},"str_id":{"description":"String message ID","example":"987655","type":"string"}},"type":"object"},"id":{"description":"Message ID","example":987655,"type":"integer"},"platform_message_id":{"description":"Original platform-side message ID (present after success)","example":"wamid.HBgLOD...","type":"string"},"status":{"description":"Send status; sending is synchronous and returns sent on success (delivered/read states come later via the DM Message List endpoint)","example":"sent","type":"string"},"str_id":{"description":"String message ID (big-number safe)","example":"987655","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Send Direct Message","tags":["Social/8.Direct Messages"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/im/upload/presigned-url":{"post":{"description":"Generate an S3 presigned URL for DM media upload. Only for DM media sending; NOT interchangeable with the general/accelerated file upload endpoints. Flow: 1. call this endpoint to get presigned_url; 2. HTTP PUT the file to presigned_url; 3. fill the returned object_key and s3_bucket into the media field of the Send Direct Message endpoint","operationId":"trenz-social-im-upload-presigned-url","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"description":"File MIME type; must match the Content-Type header of the subsequent PUT upload","example":"image/jpeg","type":"string"},"expires_in":{"description":"Presigned URL validity in seconds, default 3600 (1 hour), max 604800 (7 days)","example":3600,"type":"integer"},"file_name":{"description":"File name with extension","example":"photo.jpg","type":"string"}},"required":["file_name","content_type"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"cdn_url":{"description":"CDN access URL after upload (useful to verify the upload succeeded)","example":"https://oss.chuhaijiang.com/im/2026/07/10/20260710153000_photo.jpg","type":"string"},"object_key":{"description":"Object key (format im/YYYY/MM/DD/timestamp_filename); after upload, fill into media.s3_key of the Send Direct Message endpoint (under Social/8.Direct Messages)","example":"im/2026/07/10/20260710153000_photo.jpg","type":"string"},"presigned_url":{"description":"Presigned upload URL: HTTP PUT the file binary to it with the same Content-Type as requested","example":"https://datanebula-object.s3.us-west-2.amazonaws.com/im/2026/07/10/20260710153000_photo.jpg?X-Amz-...","type":"string"},"s3_bucket":{"description":"Bucket name; fill into media.s3_bucket of the Send Direct Message endpoint","example":"datanebula-object","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"DM Upload Presigned URL","tags":["Social/8.Direct Messages"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.social.write"}},"/open/v1/social/music/recently-used":{"post":{"description":"List recently used music tracks.","operationId":"trenz-social-music-recently-used","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"keyword":{"description":"Search keyword, matches song name or artist","type":"string"},"limit":{"default":20,"description":"Items per page, default 20","maximum":100,"type":"integer"},"page":{"default":1,"description":"Page number, starting from 1","minimum":1,"type":"integer"},"platform_account_id":{"description":"Filter by account ID, returns only music used by that account","type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"limit":{"description":"Items per page","type":"integer"},"music_list":{"items":{"properties":{"artist":{"description":"Artist/singer","type":"string"},"commercial_music_id":{"description":"TikTok commercial music ID (used to specify background music when publishing a video)","type":"string"},"commercial_music_name":{"description":"Song name","type":"string"},"duration":{"description":"Music duration (seconds)","type":"integer"},"genres":{"description":"List of music genre tags","items":{"type":"string"},"type":"array"},"id":{"description":"Music record ID","type":"integer"},"platform_account_id":{"description":"ID of the account that used this music","type":"integer"},"preview_url":{"description":"Preview URL","type":"string"},"song_clip_id":{"description":"Song clip ID (used to precisely reference a specific clip)","type":"string"},"thumbnail_url":{"description":"Cover thumbnail URL","type":"string"},"used_at":{"description":"Most recent usage time (Unix timestamp in seconds)","type":"integer"}},"type":"object"},"type":"array"},"page":{"description":"Current page number","type":"integer"},"total_count":{"description":"Total number of music tracks matching the conditions","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Recently Used Music","tags":["Social/6.Creation Tools"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/music/search":{"post":{"description":"Search popular TikTok music with filters on keyword and type.","operationId":"trenz-social-music-search","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"country_code":{"description":"Country/region code (ISO 3166-1 alpha-2), default US","type":"string"},"date_range":{"description":"Trending time range. Allowed values: 1DAY (trending today) / 7DAY (last 7 days) / 30DAY (last 30 days)","type":"string"},"genre":{"description":"Filter by music genre. Dynamically derived from chart data; common values include Pop / Hip Hop / Electronic, etc.","type":"string"},"keyword":{"description":"Search keyword, matches song name or artist. If omitted, returns the trending music chart","type":"string"},"limit":{"default":20,"description":"Items per page, default 20, maximum 100","maximum":100,"type":"integer"},"page":{"default":1,"description":"Page number, starting from 1","minimum":1,"type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"limit":{"description":"Items per page","type":"integer"},"music_list":{"items":{"properties":{"artist":{"description":"Artist/singer","type":"string"},"commercial_music_id":{"description":"TikTok commercial music ID","type":"string"},"commercial_music_name":{"description":"Song name","type":"string"},"country_code":{"description":"Country/region code it belongs to","type":"string"},"duration":{"description":"Music duration (seconds)","type":"integer"},"genres":{"description":"List of music genre tags","items":{"type":"string"},"type":"array"},"id":{"description":"Music record ID","type":"integer"},"preview_url":{"description":"Preview URL","type":"string"},"rank_position":{"description":"Chart position (only returned for chart results)","type":"integer"},"song_clip_id":{"description":"Song clip ID","type":"string"},"thumbnail_url":{"description":"Cover thumbnail URL","type":"string"}},"type":"object"},"type":"array"},"page":{"description":"Current page number","type":"integer"},"total_count":{"description":"Total number of music tracks matching the conditions","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Popular Music Search","tags":["Social/6.Creation Tools"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.social.read"}},"/open/v1/social/platform-accounts/detail":{"post":{"description":"Get details for a single social platform account.","operationId":"trenz-social-platform-account-detail","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Platform account ID","type":"integer"}},"required":["account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"account":{"properties":{"account_type":{"description":"Account type: creator (creator) / business (business account)","type":"string"},"avatar_url":{"description":"Avatar URL","type":"string"},"created_at":{"description":"Binding time (Unix timestamp in seconds)","type":"integer"},"display_name":{"description":"Account display name","type":"string"},"id":{"description":"Account ID (internal system identifier)","type":"integer"},"platform":{"description":"Platform identifier: tiktok / tiktok-shop-pc / instagram / youtube / facebook","type":"string"},"platform_account_id":{"description":"Platform-side unique account identifier","type":"string"},"region":{"description":"Region the account belongs to (only returned for TikTok Shop, e.g. US / GB)","type":"string"},"remark":{"description":"User-defined remark","type":"string"},"scopes":{"description":"List of OAuth authorization scopes","items":{"type":"string"},"type":"array"},"status":{"description":"Account status: active (normal) / expired (Token expired)","type":"string"},"updated_at":{"description":"Information update time (Unix timestamp in seconds)","type":"integer"},"username":{"description":"Platform username","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Social Account Detail","tags":["Social/1.Account Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/platform-accounts/disconnect":{"post":{"description":"Disconnect a social platform account.","operationId":"trenz-social-platform-account-disconnect","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"ID of the account to disconnect","format":"int32","type":"integer"}},"required":["account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"description":"Returns an empty object on success. After disconnecting, all OAuth tokens for this account are revoked and subsequent operations (publish, comment, etc.) will fail.","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Disconnect Social Account","tags":["Social/1.Account Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/platform-accounts/update-remark":{"post":{"description":"Update the user-defined remark on a social platform account.","operationId":"trenz-social-platform-account-update-remark","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Platform account ID","type":"integer"},"remark":{"description":"Remark content, max 500 characters","type":"string"}},"required":["account_id","remark"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"account":{"properties":{"display_name":{"description":"Account display name","type":"string"},"id":{"description":"Account ID","type":"integer"},"remark":{"description":"Updated remark content","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Update Account Remark","tags":["Social/1.Account Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/posts":{"post":{"description":"List a user's published content, organized by publication record. Supports multi-dimensional filtering, sorting, and performance metrics (views/likes/comments/shares/GMV etc). Pass platform=tiktok-shop-pc with sort_by=gmv / orders for a shoppable video leaderboard; start_time / end_time accept any range.","operationId":"trenz-social-posts-list","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"description":"Content type filter. Options: video / image","type":"string"},"end_time":{"description":"Date range end, Unix timestamp (seconds), must be used with start_time","type":"integer"},"include_daily":{"description":"Whether to include daily metric series per post, requires start_time+end_time","type":"boolean"},"page":{"default":1,"description":"Page number, starts from 1","minimum":1,"type":"integer"},"page_size":{"default":20,"description":"Items per page, default 20, max 50","maximum":50,"type":"integer"},"platform":{"description":"Platform filter. Options: tiktok / tiktok-shop-pc / instagram / youtube / facebook","type":"string"},"platform_account_id":{"description":"Used with platform_video_id","type":"integer"},"platform_account_ids":{"description":"Filter by account ID list, omit to return all","items":{"type":"integer"},"type":"array"},"platform_video_id":{"description":"Exact match a single post (requires platform_account_id)","type":"string"},"publication_id":{"description":"Exact match a single post, ignores other filters/pagination when provided","type":"integer"},"scope":{"default":"published","description":"Data scope. published (default): only posts published within the range + cumulative metrics / all: all posts with data changes within the range + incremental metrics. Only effective with start_time+end_time","type":"string"},"search":{"description":"Fuzzy search by title","type":"string"},"sort_by":{"default":"display_time","description":"Sort field. Options: display_time (default) / views / likes / comments / shares / favorites / engagement / gmv / orders","type":"string"},"sort_order":{"default":"desc","description":"Sort direction. Options: desc (default) / asc","type":"string"},"start_time":{"description":"Date range start, Unix timestamp (seconds)","type":"integer"},"status":{"description":"Status filter. Options: published / scheduled / draft / failed / cancelled. Omit to query all","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"posts":{"description":"Posts list","items":{"properties":{"account_avatar_url":{"description":"Account avatar URL","type":"string"},"account_display_name":{"description":"Account name","type":"string"},"account_remark":{"description":"Account remark","type":"string"},"comment_count":{"description":"Total comments","type":"integer"},"content_type":{"description":"Content type: video / image","type":"string"},"cover_url":{"description":"Cover image URL","type":"string"},"display_time":{"description":"Display timestamp (Unix seconds)","type":"integer"},"engagement_rate":{"description":"Engagement rate (%) = (likes+comments+shares)/views*100","type":"number"},"error_message":{"description":"Error message (failed status only)","type":"string"},"favorite_count":{"description":"Total favorites","type":"integer"},"gmv":{"description":"Total GMV (tiktok-shop-pc only)","type":"number"},"gmv_currency":{"description":"GMV currency (currently all USD)","type":"string"},"last_refreshed_at":{"description":"Metrics last refreshed timestamp","type":"integer"},"like_count":{"description":"Total likes","type":"integer"},"orders":{"description":"Order count (tiktok-shop-pc only)","type":"integer"},"platform":{"description":"Platform (tiktok / tiktok-shop-pc / instagram / youtube / facebook)","type":"string"},"platform_account_id":{"description":"Platform account ID","type":"integer"},"platform_url":{"description":"Platform original URL","type":"string"},"platform_video_id":{"description":"Platform video ID (published status only)","type":"string"},"publication_id":{"description":"Publication record ID","type":"integer"},"region":{"description":"Region (shop accounts)","type":"string"},"share_count":{"description":"Total shares","type":"integer"},"source":{"description":"Content source","type":"string"},"status":{"description":"Status: published / scheduled / draft / failed / cancelled","type":"string"},"title":{"description":"Content title","type":"string"},"view_count":{"description":"Total views","type":"integer"},"view_trend":{"description":"Daily view increments for last 7 days","items":{"type":"integer"},"type":"array"}},"type":"object"},"type":"array"},"total":{"description":"Total count of matching records","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Publishing Record List","tags":["Social/3.Video Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/posts/refresh":{"post":{"description":"Manually trigger a metrics refresh (views/likes/comments/shares) for a single post, fetching the latest cumulative values — useful for ensuring freshness before fetching the detail. Note: this refreshes current cumulative metrics only; it does not revise historical daily data.\n\nSupports sync and async modes: async (background=true) returns immediately, and last_refreshed_at in Publishing Record Detail advances once done.\n\nRate limiting: after a successful refresh the same video enters a 60-second cooldown — calls within the window return success immediately without hitting the platform API; in async mode a duplicate call while a refresh is in flight returns \"refresh already in progress\"; 503 is returned when the background queue is full (retry later); 410 is returned for deleted videos.","operationId":"trenz-social-posts-refresh","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"background":{"default":false,"description":"Async refresh flag. true: return immediately and pull latest platform metrics in the background — poll last_refreshed_at in Publishing Record Detail to detect completion; false or omitted: wait synchronously until the refresh completes","type":"boolean"},"platform_account_id":{"description":"Platform account ID, from the id field returned by Social Account List (Social \u003e Account Management)","type":"integer"},"platform_video_id":{"description":"Platform video ID, from the platform_video_id field returned by Publishing Record List (Social \u003e Video Management)","type":"string"}},"required":["platform_video_id","platform_account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"description":"No business data fields. A successful response means the refresh has completed (sync mode) or has been triggered (async mode); fetch the updated metrics via Publishing Record Detail","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Refresh Post Metrics","tags":["Social/3.Video Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/publish/cancel":{"post":{"description":"Cancel a specific publish task.","operationId":"trenz-social-publish-cancel","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Publish task ID","type":"integer"}},"required":["publication_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"description":"Returns an empty object on successful cancellation. Only publication tasks in pending / uploading status can be cancelled.","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Cancel Individual Publish","tags":["Social/2.Video Publishing"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/publish/reschedule":{"post":{"description":"Change the scheduled publish time of a publication in scheduled status without cancelling and recreating it. Only valid for scheduled publications created via Upload and Publish Video that have not started publishing yet.","operationId":"trenz-social-publish-reschedule","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Publication ID, from the Upload and Publish Video response or Publishing Record List. The publication must be in scheduled status","type":"integer"},"scheduled_at":{"description":"New scheduled publish time (Unix seconds). Must be between 5 minutes and 90 days from now","type":"integer"}},"required":["publication_id","scheduled_at"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"description":"No business data fields. A successful response means the reschedule is done; verify the new time via Publishing Record List or Publish Session Status","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Reschedule Publication","tags":["Social/2.Video Publishing"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/publish/session":{"post":{"description":"Query the progress of a video publish session.","operationId":"trenz-social-publish-session","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"session_token":{"description":"Publish session token","type":"string"}},"required":["session_token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"publications":{"description":"Detailed status of each publish target","items":{"properties":{"id":{"description":"Publish task ID","type":"integer"},"platform_url":{"description":"Video URL on the platform (returned after successful publishing)","type":"string"},"platform_video_id":{"description":"Platform-side video ID (returned after successful publishing)","type":"string"},"progress_percentage":{"description":"Progress percentage (0-100)","type":"integer"},"stage":{"description":"Current stage description","type":"string"},"status":{"description":"Publish status: pending / uploading / processing / published / failed / cancelled","type":"string"}},"type":"object"},"type":"array"},"session":{"properties":{"completed_at":{"description":"Session completion time (Unix timestamp in seconds), null while in progress","type":"integer"},"completed_publications":{"description":"Number successfully completed","type":"integer"},"failed_publications":{"description":"Number failed","type":"integer"},"id":{"description":"Session ID","type":"integer"},"session_token":{"description":"Session Token","type":"string"},"started_at":{"description":"Session start time (Unix timestamp in seconds)","type":"integer"},"status":{"description":"Session status: in_progress / completed (all completed) / failed (all failed) / cancelled","type":"string"},"total_publications":{"description":"Total number of publish targets","type":"integer"},"video_id":{"description":"Associated video record ID","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Publish Session Status","tags":["Social/2.Video Publishing"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/publish/session/cancel":{"post":{"description":"Cancel an entire video publish session.","operationId":"trenz-social-publish-session-cancel","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"session_token":{"description":"Publish session token","type":"string"}},"required":["session_token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"description":"Returns an empty object on successful cancellation. This cancels all unfinished publication tasks under the session.","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Cancel Publish Session","tags":["Social/2.Video Publishing"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/publish/upload-and-publish":{"post":{"description":"One-step upload-and-publish a video to multiple social platforms.","operationId":"trenz-social-publish-upload","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"bucket_key":{"description":"Video file path (obtained from the object_key field returned by the Generate Upload Presigned URL endpoint). Used when publishing a single video; mutually exclusive with media_items","type":"string"},"bucket_name":{"description":"Name of the bucket where the video file is stored (obtained from the s3_bucket field returned by the Generate Upload Presigned URL endpoint). Used when publishing a single video; mutually exclusive with media_items","type":"string"},"content_type":{"default":"video","description":"Content type. video = video (default), image = image / image carousel","type":"string"},"cover_bucket_key":{"description":"Cover image file path (optional, obtained from the Generate Upload Presigned URL endpoint)","type":"string"},"cover_bucket_name":{"description":"Cover image bucket name (optional, obtained from the Generate Upload Presigned URL endpoint)","type":"string"},"dry_run":{"default":false,"description":"Dry-run mode. When set to true, the content is not actually published to the platform; only a publication record is created for testing","type":"boolean"},"duration":{"description":"Video duration (seconds), optional. Detected automatically if omitted","type":"number"},"file_size":{"description":"File size (bytes), optional. Detected automatically if omitted","type":"integer"},"media_items":{"description":"List of media items, used for multi-file publishing such as image carousels. When using this field, there is no need to pass bucket_name and bucket_key. Each item's path is obtained after uploading via the Generate Upload Presigned URL endpoint","items":{"properties":{"bucket_key":{"description":"File path","type":"string"},"bucket_name":{"description":"Name of the bucket where the file is stored","type":"string"},"order":{"description":"Sort order (starting from 1)","type":"integer"}},"required":["bucket_name","bucket_key","order"],"type":"object"},"type":"array"},"publications":{"description":"List of publish targets. Supports publishing to multiple accounts at once; each account can have its own title, description, tags, and scheduled time","items":{"properties":{"description":{"description":"Video description as published to the platform","type":"string"},"platform_account_id":{"description":"Target social account ID (obtained from the Social Account List endpoint)","type":"integer"},"platform_config":{"description":"Platform-specific publish configuration (JSON string). Available fields:\n- privacy (string): Privacy setting. YouTube: public/private(default)/unlisted; TikTok: PUBLIC_TO_EVERYONE(default)/MUTUAL_FOLLOW_FRIENDS/FOLLOWER_OF_CREATOR/SELF_ONLY. ⚠️ Note: when you authorize a TikTok account to Trenz, the authorization is via TikTok Business API (business authorization), so privacy does NOT take effect — the post will follow the account's default privacy setting in TikTok (by contrast, the is_aigc AI-generated content declaration DOES take effect)\n- disable_comment (boolean): Disable comments (TikTok only; not effective for TikTok Shop shoppable posts)\n- disable_duet (boolean): Disable duet (TikTok video only; not effective for TikTok Shop shoppable posts)\n- disable_stitch (boolean): Disable stitch (TikTok video only; not effective for TikTok Shop shoppable posts)\n- is_aigc (boolean): AI-generated content declaration (TikTok business-authorized video and photo posts only; not effective for TikTok Shop shoppable posts)\n- music_sound_id (string): Commercial music clip for a TikTok business-authorized account. Use the song_clip_id returned by Trending Music Search or Recently Used Music. Supported for video and photo posts; not supported for TikTok Personal or TikTok Shop shoppable posts\n- music_sound_volume (integer): Music volume from 0 to 100; defaults to 100 (TikTok business-authorized video posts only)\n- music_sound_start (integer): Music clip start time in milliseconds; must be greater than or equal to 0 (TikTok business-authorized video posts only)\n- music_sound_end (integer): Music clip end time in milliseconds; must be greater than or equal to 0 and, when used with music_sound_start, greater than the start time (TikTok business-authorized video posts only)\n- video_original_sound_volume (integer): Original video sound volume from 0 to 100 (TikTok business-authorized video posts only)\n- auto_add_music (boolean): Let TikTok automatically add music (TikTok business-authorized photo posts only). For photo posts, choose either auto_add_music or music_sound_id; do not send both\n- product_id (string): Linked product ID (TikTok Shop only)\n- product_title (string): Linked product title (TikTok Shop only, used together with product_id)\n\n⚠️ Important: once product_id is provided, the post goes through the TikTok Shop shoppable publishing flow — privacy/disable_comment/disable_duet/disable_stitch/is_aigc and the TikTok business music settings above will NOT take effect; comments and other settings follow the TikTok account defaults.\n\nExample: {\"privacy\":\"PUBLIC_TO_EVERYONE\",\"is_aigc\":true,\"music_sound_id\":\"7512345678901234567\",\"music_sound_volume\":80,\"video_original_sound_volume\":20}","type":"string"},"scheduled_at":{"description":"Scheduled publish time (Unix timestamp, seconds). Omit to publish immediately","type":"integer"},"tags":{"description":"Tag list (e.g. [\"#fyp\", \"#viral\"])","items":{"type":"string"},"type":"array"},"title":{"description":"Video title as published to the platform","type":"string"}},"required":["platform_account_id","title"],"type":"object"},"type":"array"},"video_description":{"description":"Video description, shown in the publication record","type":"string"},"video_title":{"description":"Video title, shown in the publication record","type":"string"}},"required":["video_title","publications"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"session_token":{"description":"Publish session token. Used to poll publish progress via the Publish Session Status endpoint","type":"string"},"skipped_accounts":{"description":"List of account info skipped due to rate limiting. Normally an empty array","items":{"type":"string"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Upload and Publish Video","tags":["Social/2.Video Publishing"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/seller/daily-report":{"post":{"description":"Single-shop daily business report: yesterday's battle report (GMV / orders / AOV / refunds / top products, real-time order data), return \u0026 inventory signals (with days-to-sell-out estimates), business analytics (visitors / conversion / GMV channel breakdown / product funnels / GMV attribution / underperformers, T-2 data), AI business advice (focus line / 1-3 action suggestions / one-line insight), risk board and 7-day trend. Requires TikTok Shop seller authorization.\n\nHow it works: this endpoint reads a pre-generated report cache (a report is cached for 26 hours per shop per date). status=ready returns full data; status=generating means the report is being computed — retry in 5-10 seconds.\n\nBilling note: every call is billed, including calls that return generating. Consider caching the report on your side after fetching.\n\nTroubleshooting: if the status stays generating for a long time, check that ① platform_account_id is a TikTok Shop seller account owned by the current user, and ② date is strictly formatted as YYYY-MM-DD — these errors do not return an error response, but the report will never be generated.","operationId":"trenz-seller-daily-report","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"date":{"description":"Report date, strictly formatted YYYY-MM-DD (e.g. 2026-07-09), usually yesterday. A malformed date does not return an error, but the report will stay in generating forever. Battle report uses real-time order data of that date; business analytics uses T-2 data","type":"string"},"platform_account_id":{"description":"Seller shop account ID (from Social Account List; must be a TikTok Shop seller account). Note: passing a non-seller or inaccessible account does not return an error, but the report will stay in generating forever","type":"integer"}},"required":["platform_account_id","date"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":5}},"schema":{"properties":{"data":{"properties":{"data":{"description":"Report data, present only when status=ready (click to expand detailed fields)","properties":{"advice":{"description":"AI business advice (click to expand detailed fields)","properties":{"focus_line":{"description":"Focus headline","type":"string"},"from_llm":{"description":"Whether generated by AI (false = rule-based fallback)","type":"boolean"},"insight":{"description":"One-line business insight, may be empty","type":"string"},"suggestions":{"description":"1-3 action suggestions","items":{"type":"string"},"type":"array"}},"type":"object"},"analytics":{"description":"Business analytics (T-2, may be absent): visitors / conversion / page views, video commerce, GMV channel breakdown (live / video / product card), product funnels, GMV attribution, underperformers","type":"object"},"battle":{"description":"Yesterday battle report (real-time orders) (click to expand detailed fields)","properties":{"aov":{"description":"Average order value","type":"string"},"currency":{"description":"Currency","type":"string"},"gmv":{"description":"GMV of the day","type":"string"},"gmv_change":{"description":"GMV vs previous day (e.g. +8.5%), empty when no prior data","type":"string"},"items":{"description":"Items sold","type":"integer"},"orders":{"description":"Valid (paid) orders","type":"integer"},"refund_amount":{"description":"Refund amount","type":"string"},"refund_count":{"description":"Refund requests initiated that day","type":"integer"},"top_products":{"description":"Top-selling products (GMV / items / price / image / stock alert)","items":{"type":"object"},"type":"array"}},"type":"object"},"battle_date":{"description":"Battle report date","type":"string"},"risk":{"description":"Shop risk board (qualification / product status / refund rate / settlement); absent when no risks","type":"object"},"shop_name":{"description":"Shop name","type":"string"},"signals":{"description":"Return \u0026 inventory signals (click to expand detailed fields)","properties":{"inventory":{"description":"Inventory status of products sold yesterday (total qty / lowest SKU qty / out-of-stock SKUs / days-to-sell-out estimate)","items":{"type":"object"},"type":"array"},"refunds":{"description":"Refunds aggregated by SKU with most common reason","items":{"type":"object"},"type":"array"}},"type":"object"},"trend":{"description":"7-day GMV \u0026 visitors trend with streak annotation. Visitors = -1 means data not yet available for that day","type":"object"}},"type":"object"},"status":{"description":"Report status: ready (data present) / generating (retry in 5-10s; if it never resolves, check the account and date parameters)","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Seller Daily Report","tags":["Social/9.Seller Analytics"],"x-billing-mode":"per_call","x-coin-cost":5,"x-scope":"trenz.social.read"}},"/open/v1/social/seller/shop-products":{"post":{"description":"List products of your connected TikTok Shop seller stores, with keyword search and sorting. Returns title, main image, price, status and owning shop. Requires TikTok Shop seller authorization (different from creator account authorization). For SKU details and numeric inventory use Shop Product Detail.","operationId":"trenz-seller-shop-products","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"keyword":{"description":"Keyword search on product title (fuzzy match)","type":"string"},"page":{"default":1,"description":"Page number, defaults to 1","type":"integer"},"page_size":{"default":10,"description":"Items per page, default 10, max 50","maximum":50,"type":"integer"},"platform_account_id":{"description":"Seller shop account ID (from Social Account List, account type TikTok Shop seller). Omit to query products across all your seller shops","type":"integer"},"sort_by":{"default":"update_time","description":"Sort field: update_time (default) / create_time / price / title. Other values fall back to update_time (no error)","type":"string"},"sort_order":{"default":"desc","description":"Sort direction: desc (default) / asc. Other values fall back to desc","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"products":{"description":"Product list (click to expand detailed fields)","items":{"properties":{"category":{"description":"Top-level category name; empty if not enriched yet","type":"string"},"create_time":{"description":"Product creation time (Unix seconds)","type":"integer"},"image_url":{"description":"Main image URL (temporary signed link); empty if images not yet synced","type":"string"},"platform_account_id":{"description":"Owning seller account ID","type":"integer"},"price":{"description":"Price (sale price of the first SKU)","type":"number"},"price_currency":{"description":"Price currency","type":"string"},"product_id":{"description":"Product ID, used by Shop Product Detail","type":"string"},"shop_name":{"description":"Owning shop name","type":"string"},"shop_region":{"description":"Shop region (e.g. US / BR / MX)","type":"string"},"status":{"description":"Product status: ACTIVATE / SELLER_DEACTIVATED / DELETED","type":"string"},"title":{"description":"Product title","type":"string"},"update_time":{"description":"Product update time (Unix seconds)","type":"integer"}},"type":"object"},"type":"array"},"total":{"description":"Total product count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Shop Product List","tags":["Social/9.Seller Analytics"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.social.read"}},"/open/v1/social/seller/shop-products/detail":{"post":{"description":"Full detail of a single product in your seller shop: rich-text description, all images, full category chain, and SKU breakdown with per-SKU price and **numeric inventory**. Data is fetched live from the official TikTok Shop seller API (not cached). Requires TikTok Shop seller authorization. A system error is returned when the product does not exist or does not belong to the shop.","operationId":"trenz-seller-shop-product-detail","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"Seller shop account ID (from Social Account List)","type":"integer"},"product_id":{"description":"Product ID from Shop Product List","type":"string"}},"required":["platform_account_id","product_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"category":{"description":"Full category chain, e.g. Sports \u0026 Outdoor \u003e Fitness \u003e ...","type":"string"},"create_time":{"description":"Creation time (Unix seconds)","type":"integer"},"description":{"description":"Rich-text product description (HTML)","type":"string"},"images":{"description":"All product images (click to expand detailed fields)","items":{"properties":{"height":{"description":"Height in pixels","type":"integer"},"url":{"description":"Image URL","type":"string"},"width":{"description":"Width in pixels","type":"integer"}},"type":"object"},"type":"array"},"product_id":{"description":"Product ID","type":"string"},"shop_name":{"description":"Shop name","type":"string"},"shop_region":{"description":"Shop region","type":"string"},"skus":{"description":"SKU list with price and numeric inventory (click to expand detailed fields)","items":{"properties":{"inventory":{"description":"Current numeric inventory of this SKU (live value, total across all warehouses)","type":"integer"},"price":{"description":"SKU price","type":"number"},"price_currency":{"description":"Currency","type":"string"},"seller_sku":{"description":"Seller-defined SKU code","type":"string"},"sku_id":{"description":"SKU ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"Product status: ACTIVATE / SELLER_DEACTIVATED / DELETED","type":"string"},"title":{"description":"Product title","type":"string"},"update_time":{"description":"Update time (Unix seconds)","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Shop Product Detail","tags":["Social/9.Seller Analytics"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/seller/shops-overview":{"post":{"description":"Multi-shop business overview: GMV / orders / items sold with period-over-period change, video views and GPM, average visitors and conversion rate, plus per-shop breakdown (sorted by GMV, with daily GMV series). Data comes from the official TikTok Shop seller API; statistics lag 1-2 days (see data_available_date). Requires TikTok Shop seller authorization.","operationId":"trenz-seller-shops-overview","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"currency":{"default":"USD","description":"Currency mode, only USD (default, cross-shop totals in USD) / LOCAL (per-shop local currency) are supported. Note: the summary block is present only when all shops report the same currency","type":"string"},"end_date":{"description":"Period end date YYYY-MM-DD (inclusive), defaults to today. Must be passed together with start_date","type":"string"},"start_date":{"description":"Period start date YYYY-MM-DD (inclusive), defaults to yesterday. Must be passed together with end_date; passing only one falls back to the default range","type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"connected_shops":{"description":"Shops with active authorization","type":"integer"},"currency":{"description":"Unified currency (e.g. USD); empty when shop currencies differ","type":"string"},"current_period":{"description":"Actual statistics period, based on the latest date TikTok data is available for — may be earlier than requested (click to expand detailed fields)","properties":{"end_date":{"description":"Period end date YYYY-MM-DD (inclusive; the latest day with available data)","type":"string"},"start_date":{"description":"Period start date YYYY-MM-DD (inclusive)","type":"string"}},"type":"object"},"data_available_date":{"description":"Latest date TikTok Shop statistics are available for (statistics lag 1-2 days)","type":"string"},"previous_period":{"description":"Comparison period (click to expand detailed fields)","properties":{"end_date":{"description":"Period end date","type":"string"},"start_date":{"description":"Period start date","type":"string"}},"type":"object"},"shops":{"description":"Per-shop breakdown, sorted by GMV descending (click to expand detailed fields)","items":{"properties":{"avg_conversion_rate":{"description":"Average daily conversion rate (0.0435 = 4.35%)","type":"number"},"avg_visitors":{"description":"Average daily visitors","type":"integer"},"daily_gmv":{"description":"Daily GMV series in the period (ascending by date), useful for trend charts","items":{"type":"number"},"type":"array"},"gmv":{"description":"GMV in the period","type":"number"},"gmv_change_rate":{"description":"GMV change rate","type":"number"},"gmv_currency":{"description":"Currency","type":"string"},"gmv_share":{"description":"Share of total GMV (0.675 = 67.5%)","type":"number"},"items_sold":{"description":"Items sold","type":"integer"},"items_sold_change_rate":{"description":"Items sold change rate","type":"number"},"orders":{"description":"Orders","type":"integer"},"orders_change_rate":{"description":"Orders change rate","type":"number"},"platform_account_id":{"description":"Shop account ID","type":"integer"},"product_count":{"description":"Number of products in the shop","type":"integer"},"shop_name":{"description":"Shop name","type":"string"},"shop_region":{"description":"Shop region: US / BR / MX etc.","type":"string"},"status":{"description":"Authorization status: active / expired / revoked","type":"string"}},"type":"object"},"type":"array"},"summary":{"description":"Cross-shop totals, present only when all shops report the same currency (click to expand detailed fields)","properties":{"gmv":{"description":"Total GMV across shops","type":"number"},"gmv_change_rate":{"description":"GMV change vs previous period (0.15 = +15%)","type":"number"},"gmv_currency":{"description":"Currency","type":"string"},"gpm":{"description":"GMV per mille = GMV / views × 1000","type":"number"},"items_sold":{"description":"Total items sold","type":"integer"},"items_sold_change_rate":{"description":"Items sold change rate","type":"number"},"orders":{"description":"Total orders","type":"integer"},"orders_change_rate":{"description":"Orders change rate","type":"number"},"video_views":{"description":"Total video views across shops","type":"integer"},"video_views_change_rate":{"description":"Video views change rate","type":"number"}},"type":"object"},"total_shops":{"description":"Total connected seller shops (including expired authorizations)","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Seller Shops Overview","tags":["Social/9.Seller Analytics"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/tiktok-shop/products":{"post":{"description":"Get the unified TikTok Shop product list, auto-routing between showcase and shop sources.","operationId":"trenz-social-tiktok-shop-products","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"TikTok Shop account ID","type":"integer"},"data_source":{"description":"Data source. Allowed values: shop (all products in the store) / showcase (showcase products)","type":"string"},"origin":{"description":"Filter by product origin. Allowed values: LIVE (live) / SHOWCASE (showcase)","type":"string"},"page_size":{"default":20,"description":"Items per page, range 1-20, default 20","maximum":20,"minimum":1,"type":"integer"},"page_token":{"description":"Pagination Token. Leave empty on the first request, then pass the next_page_token from the previous response","type":"string"},"sort_field":{"description":"Sort field. Allowed values: PRODUCT_ID / PRICE / SALE","type":"string"},"sort_order":{"description":"Sort direction. Allowed values: DESC (descending) / ASC (ascending)","type":"string"},"title_keyword":{"description":"Search keyword for product title","type":"string"}},"required":["account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"creator_type":{"description":"Creator type","type":"string"},"data_source":{"description":"Data source","type":"string"},"next_page_token":{"description":"Token for the next page. Empty means the last page has been reached","type":"string"},"products":{"items":{"properties":{"added_status":{"description":"Showcase addition status","type":"string"},"brand_name":{"description":"Brand name","type":"string"},"commission":{"description":"Commission information","properties":{"amount":{"description":"Commission amount","type":"string"},"rate":{"description":"Commission rate (%)","type":"number"}},"type":"object"},"detail_link":{"description":"Link to the product detail page","type":"string"},"id":{"description":"Product ID","type":"string"},"images":{"description":"List of product images","items":{"properties":{"height":{"description":"Image height (pixels)","type":"integer"},"url":{"description":"Image URL","type":"string"},"width":{"description":"Image width (pixels)","type":"integer"}},"type":"object"},"type":"array"},"inventory_status":{"description":"Inventory status","type":"string"},"is_hidden":{"description":"Whether it is hidden in the showcase","type":"boolean"},"price":{"description":"Product price","properties":{"amount":{"description":"Price amount","type":"string"},"currency":{"description":"Currency","type":"string"}},"type":"object"},"review_status":{"description":"Review status","type":"string"},"sale_regions":{"description":"List of sale regions (e.g. US / GB)","items":{"type":"string"},"type":"array"},"sales_count":{"description":"Cumulative sales count","type":"integer"},"shop_name":{"description":"Name of the store it belongs to","type":"string"},"source":{"description":"Product origin","type":"string"},"title":{"description":"Product name","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total number of products","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"TikTok Shop Product List","tags":["Social/7.TikTok Shop"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/tiktok-shop/showcase/add":{"post":{"description":"Add a product to the TikTok Shop creator showcase.","operationId":"trenz-social-tiktok-shop-showcase-add","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Platform account ID","type":"integer"},"add_type":{"description":"Add mode: PRODUCT_ID/PRODUCT_LINK","type":"string"},"product_ids":{"description":"Product ID list, max 20","items":{"type":"string"},"type":"array"},"product_link":{"description":"Product URL","type":"string"}},"required":["account_id","add_type"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"errors":{"description":"List of products that failed to be added. An empty array means all succeeded","items":{"properties":{"code":{"description":"Error code","type":"integer"},"message":{"description":"Description of the error reason","type":"string"},"product_id":{"description":"ID of the product that failed to be added","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Add Product to Showcase","tags":["Social/7.TikTok Shop"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/tiktok/qrcode":{"post":{"description":"Get a TikTok QR code for login. ⚠️ Important: start polling the \"TikTok QR Code Status Check\" endpoint immediately after obtaining the QR code (every 2-3 seconds, until it returns status=confirmed/utilised). Do NOT wait until the code has been scanned to start polling — a QR code whose status has never been checked will show an \"expired\" error when scanned.","operationId":"trenz-social-tiktok-qrcode","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"connector":{"description":"Connector identifier, always pass \"trenz\"","enum":["trenz"],"type":"string"},"state":{"description":"Optional CSRF protection parameter. If provided, it is returned verbatim upon scan confirmation, used to verify the legitimacy of the callback source","type":"string"}},"required":["connector"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"scan_qrcode_url":{"description":"QR code image URL, shown to the user to scan with the TikTok app","type":"string"},"token":{"description":"QR scan session token, used to poll the scan result via the \"TikTok QR Code Status Check\" endpoint. Start polling immediately after receiving this response (every 2-3 seconds); do not wait for the scan","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"TikTok QR Code Login","tags":["Social/1.Account Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/tiktok/qrcode/check":{"post":{"description":"Poll the TikTok QR code login status. ⚠️ Start polling this endpoint immediately after obtaining the QR code (every 2-3 seconds); do not wait until the code has been scanned — a QR code whose status has never been checked will show an \"expired\" error when scanned.","operationId":"trenz-social-tiktok-qrcode-check","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"connector":{"description":"Connector identifier, always pass \"trenz\"","enum":["trenz"],"type":"string"},"token":{"description":"The token obtained from the \"TikTok QR Code Login\" endpoint","type":"string"}},"required":["connector","token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"account":{"description":"Account info returned on successful binding (when `status=confirmed` and connection succeeds)","properties":{"account_type":{"description":"Account type: business/creator","type":"string"},"avatar_url":{"description":"Avatar URL","type":"string"},"created_at":{"description":"Bound at (Unix timestamp)","type":"integer"},"display_name":{"description":"Display name","type":"string"},"id":{"description":"Account ID","type":"integer"},"platform":{"description":"Platform","type":"string"},"platform_account_id":{"description":"Platform-side account ID","type":"string"},"region":{"description":"TikTok Shop region","type":"string"},"scopes":{"description":"OAuth scope","items":{"type":"string"},"type":"array"},"status":{"description":"Account status: active/expired/revoked","type":"string"},"username":{"description":"Username","type":"string"}},"type":"object"},"status":{"description":"Authorization state machine: new (waiting for scan) → scanned (scanned, waiting for confirmation in the TikTok App) → confirmed (authorized; Trenz automatically exchanges the authorization code and completes account binding) → utilised (authorization code redeemed; binding completed). The QR code expires into expired if not confirmed in time. When polling, this is the only field you need to watch: on expired, call the \"TikTok QR Code Login\" endpoint to generate a new QR code; both confirmed and utilised mean binding is done — stop polling and call the \"Social Account List\" endpoint to confirm the newly bound account. Note: your polling interval may skip confirmed and see utilised directly, which is normal","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"TikTok QR Code Status Check","tags":["Social/1.Account Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.write"}},"/open/v1/social/upload/presigned-url":{"post":{"description":"Generate an S3 presigned upload URL for direct client-side file upload.\n\nUsage:\n1. Call this endpoint to obtain presigned_url and cdn_url\n2. Upload the file via HTTP PUT to presigned_url (see example below)\n3. Once uploaded, the file is accessible at cdn_url\n\nStep 2 upload example:\ncurl --request PUT \\\n  --header \"Content-Type: image/jpeg\" \\\n  --data-binary @\"your_file.jpg\" \\\n  \"{presigned_url}\"","operationId":"trenz-social-upload-presigned-url","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"description":"File MIME type, e.g. video/mp4, image/jpeg, image/png","type":"string"},"expires_in":{"description":"Presigned URL validity period (seconds), default 3600 (1 hour)","type":"integer"},"file_name":{"description":"File name (including extension), e.g. \"video.mp4\" or \"cover.jpg\"","type":"string"},"region":{"description":"Storage region. Allowed values: tos (Asia-Pacific, default) / aws (US). Choosing a region closer to the target publishing platform can improve upload speed","type":"string"}},"required":["file_name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"cdn_url":{"description":"CDN access URL of the file (available after the upload completes)","type":"string"},"object_key":{"description":"File path. Pass it as the bucket_key field when calling the Upload and Publish Video endpoint","type":"string"},"presigned_url":{"description":"Presigned upload URL. Upload the file to this URL using the HTTP PUT method","type":"string"},"s3_bucket":{"description":"Bucket name. Pass it as the bucket_name field when calling the Upload and Publish Video endpoint","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Generate Presigned Upload URL","tags":["File Upload"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/videos/check-info":{"post":{"description":"Validate a video against the rules of each target platform before publishing.","operationId":"trenz-social-video-check-info","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"bucket_name":{"description":"Bucket name (the `s3_bucket` returned by 'Generate Presigned Upload URL' under the 'General' category)","type":"string"},"object_key":{"description":"Object key (the `object_key` returned by 'Generate Presigned Upload URL' under the 'General' category)","type":"string"}},"required":["bucket_name","object_key"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"platform_rules":{"additionalProperties":{"type":"object"},"description":"Video rule requirements for each platform (duration, resolution, file size limits, etc.)","type":"object"},"validation_results":{"additionalProperties":{"properties":{"errors":{"description":"List of validation errors (returned when is_valid=false)","items":{"properties":{"field":{"description":"The non-compliant field (e.g. duration / resolution / file_size)","type":"string"},"reason":{"description":"The specific reason for non-compliance","type":"string"}},"type":"object"},"type":"array"},"is_valid":{"description":"Whether validation passed for this platform","type":"boolean"}},"type":"object"},"description":"Validation results for each platform. The key is the platform identifier (tiktok / instagram / youtube, etc.)","type":"object"},"video_metadata":{"description":"Video file metadata","properties":{"bit_rate":{"description":"Bit rate (bps)","type":"integer"},"codec_name":{"description":"Video codec format (e.g. h264 / hevc)","type":"string"},"duration":{"description":"Video duration (seconds)","type":"number"},"file_size":{"description":"File size (bytes)","type":"integer"},"frame_rate":{"description":"Frame rate (fps)","type":"number"},"height":{"description":"Video height (pixels)","type":"integer"},"width":{"description":"Video width (pixels)","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Validate Video Info","tags":["Social/3.Video Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/videos/detail":{"post":{"description":"Full detail of a single publishing record: basic info, cumulative social metrics (views/likes/comments/shares/favorites/engagement rate), 30-day daily metric series, platform-specific extended metrics (19 TikTok fields incl. completion rate/reach/audience breakdowns; Instagram reach/watch time), and shoppable data (GMV/orders/items sold/30-day daily series/tagged products/anchor display rate/CTR). Locate the record by publication_id, or by platform_video_id + platform_account_id.\n\n[Changelog 2026-07] The data source has been upgraded and the response structure fully redesigned (all social metrics, metric series, extended metrics and shoppable data added). Please integrate against the latest response fields.","operationId":"trenz-social-video-detail","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"Platform account ID, used together with platform_video_id","type":"integer"},"platform_video_id":{"description":"Platform video ID from Publishing Record List. Must be used together with platform_account_id; locates posts synced from the platform","type":"string"},"publication_id":{"description":"Publication ID from Publishing Record List. Either this or platform_video_id is required; this field wins when both are provided","type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"description":"Full publishing record detail. Optional fields are omitted when there is no data","properties":{"account_avatar_url":{"description":"Avatar URL (temporary signed link)","type":"string"},"account_display_name":{"description":"Account display name","type":"string"},"account_username":{"description":"Platform username, may be empty","type":"string"},"anchor_display_rate":{"description":"Average anchor display rate, 0-1 (tiktok-shop-pc only)","type":"number"},"click_through_rate":{"description":"Average click-through rate, 0-1 (tiktok-shop-pc only)","type":"number"},"comment_count":{"description":"Cumulative comments (published only)","type":"integer"},"content_type":{"description":"Content type: video / image","type":"string"},"cover_url":{"description":"Cover image URL (temporary signed link)","type":"string"},"description":{"description":"Post description","type":"string"},"display_time":{"description":"Display timestamp (Unix seconds): scheduled time for scheduled posts, otherwise created/published time","type":"integer"},"engagement_rate":{"description":"Engagement rate percentage = (likes+comments+shares)/views*100. Omitted when views is 0","type":"number"},"error_message":{"description":"Failure reason (failed status only, localized)","type":"string"},"extra_metrics":{"description":"Platform-specific extended metrics (JSON string, parse per platform; omitted when not collected). TikTok has 19 fields: completion_rate (0-1), average_time_watched (seconds), total_time_watched, reach, new_followers, impression_sources, audience_types / audience_countries / audience_genders / audience_cities, video_view_retention (per-second retention curve), engagement_likes (per-second likes), profile_views, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks, website_clicks, address_clicks. Instagram: reach, avg_watch_time / total_watch_time (Reels, seconds)","type":"string"},"favorite_count":{"description":"Cumulative favorites (TikTok / Instagram only)","type":"integer"},"gmv":{"description":"Cumulative GMV (published + tiktok-shop-pc only)","type":"number"},"gmv_currency":{"description":"GMV currency","type":"string"},"last_refreshed_at":{"description":"Last metrics refresh timestamp (Unix seconds). Use Refresh Post Metrics to refresh proactively","type":"integer"},"like_count":{"description":"Cumulative likes (published only)","type":"integer"},"media_items":{"description":"Image list (image posts only) (click to expand detailed fields)","items":{"properties":{"order":{"description":"Image order, starting from 0","type":"integer"},"presigned_url":{"description":"Image download URL (temporary signed link)","type":"string"}},"type":"object"},"type":"array"},"metric_series":{"description":"Daily metric series for the last 30 days; values are cumulative as of each day (click to expand detailed fields)","items":{"properties":{"comment_count":{"description":"Cumulative comments on that day","type":"integer"},"date":{"description":"Date, YYYY-MM-DD","type":"string"},"favorite_count":{"description":"Cumulative favorites on that day (TikTok / Instagram only)","type":"integer"},"like_count":{"description":"Cumulative likes on that day","type":"integer"},"share_count":{"description":"Cumulative shares on that day","type":"integer"},"view_count":{"description":"Cumulative views on that day","type":"integer"}},"type":"object"},"type":"array"},"platform":{"description":"Platform: tiktok / tiktok-shop-pc / instagram / youtube / facebook","type":"string"},"platform_account_id":{"description":"Platform account ID","type":"integer"},"platform_url":{"description":"Original post URL on the platform","type":"string"},"platform_video_id":{"description":"Platform video ID","type":"string"},"products":{"description":"Products tagged on the post (tiktok-shop-pc only) (click to expand detailed fields)","items":{"properties":{"image_url":{"description":"Product main image URL (temporary signed link)","type":"string"},"price_amount":{"description":"Product price","type":"number"},"price_currency":{"description":"Price currency, defaults to USD","type":"string"},"product_id":{"description":"TikTok Shop product ID","type":"string"},"title":{"description":"Product title","type":"string"}},"type":"object"},"type":"array"},"publication_id":{"description":"Publication ID; 0 for posts synced from the platform (not published via this platform)","type":"integer"},"published_at":{"description":"Actual publish time (Unix seconds)","type":"integer"},"region":{"description":"Account region","type":"string"},"share_count":{"description":"Cumulative shares (published only)","type":"integer"},"shop_daily_metrics":{"description":"Daily shoppable metric series for the last 30 days (tiktok-shop-pc only) (click to expand detailed fields)","items":{"properties":{"anchor_display_rate":{"description":"Anchor (shopping cart) display rate on that day, 0-1","type":"number"},"click_through_rate":{"description":"Click-through rate on that day, 0-1","type":"number"},"date":{"description":"Date, YYYY-MM-DD","type":"string"},"gmv":{"description":"GMV on that day","type":"number"},"gmv_currency":{"description":"Currency","type":"string"},"items_sold":{"description":"Items sold on that day","type":"integer"},"orders":{"description":"Orders on that day","type":"integer"}},"type":"object"},"type":"array"},"status":{"description":"Status: published / scheduled / draft / failed / cancelled","type":"string"},"title":{"description":"Post title","type":"string"},"total_items_sold":{"description":"Cumulative items sold (tiktok-shop-pc only)","type":"integer"},"total_orders":{"description":"Cumulative orders (tiktok-shop-pc only)","type":"integer"},"video_url":{"description":"Video source file download URL (temporary signed link; only for posts published via this platform, absent for synced posts)","type":"string"},"view_count":{"description":"Cumulative views (published only)","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Publishing Record Detail","tags":["Social/3.Video Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/social/videos/export":{"post":{"description":"Export published social media video data as an Excel file. Returns a download link valid for 24 hours. Maximum 1000 records per export.","operationId":"trenz-social-videos-export","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"description":"Content type filter. Allowed values: video / image","type":"string"},"end_time":{"description":"Publish time end filter (Unix timestamp in seconds)","type":"integer"},"limit":{"default":1000,"description":"Number of records to export, default 1000, maximum 1000","maximum":1000,"minimum":1,"type":"integer"},"offset":{"default":0,"description":"Skip the first N records (0-based), for batch export","minimum":0,"type":"integer"},"platform":{"description":"Platform filter. Allowed values: tiktok / instagram / youtube / facebook","type":"string"},"platform_account_ids":{"description":"Filter by account ID list","items":{"type":"integer"},"type":"array"},"search":{"description":"Fuzzy search by video title","type":"string"},"sort_by":{"description":"Sort field. Allowed values: display_time (default) / views / likes / comments / shares / favorites / engagement / gmv / orders","type":"string"},"sort_order":{"description":"Sort direction. Allowed values: desc (default) / asc","type":"string"},"start_time":{"description":"Publish time start filter (Unix timestamp in seconds)","type":"integer"},"timezone":{"description":"IANA timezone (e.g. America/Los_Angeles) for formatting dates in the exported file. Defaults to UTC if omitted","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"download_url":{"description":"Excel file download link (S3 presigned URL, valid for approximately 24 hours)","type":"string"},"exported_count":{"description":"Actual number of exported rows (≤ 1000)","type":"integer"},"filename":{"description":"Suggested filename for the download","type":"string"},"total":{"description":"Total number of records matching the filter (real count before truncation)","type":"integer"},"truncated":{"description":"Whether the result was truncated. true means total exceeds 1000 and only the first 1000 records were exported","type":"boolean"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Export Publishing Records","tags":["Social/3.Video Management"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"trenz.social.read"}},"/open/v1/social/videos/platform":{"post":{"description":"List videos published to the platform along with their metrics.","operationId":"trenz-social-platform-videos","parameters":[{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"filter":{"description":"Filter conditions","properties":{"published_after":{"description":"Start of publish-time filter range (Unix timestamp in seconds)","type":"integer"},"published_before":{"description":"End of publish-time filter range (Unix timestamp in seconds)","type":"integer"},"search_keyword":{"description":"Search keyword, matches the video title","type":"string"},"sort_by":{"description":"Sort field. Allowed values: published_at (publish time, default) / play_count / like_count / comment_count / share_count","type":"string"},"sort_order":{"description":"Sort direction. Allowed values: desc (descending, default) / asc (ascending)","type":"string"}},"type":"object"},"filter_unread":{"description":"Filter by unread comments. true = only videos with unread comments, false = only videos without unread comments, omit = no filtering","type":"boolean"},"include_presigned_urls":{"description":"Whether to return presigned download URLs for the video files. Default false","type":"boolean"},"limit":{"default":20,"description":"Items per page, default 20","maximum":100,"type":"integer"},"page":{"default":1,"description":"Page number, starting from 1","minimum":1,"type":"integer"},"platform_account_id":{"description":"Account ID","type":"integer"},"platform_video_ids":{"description":"Filter by specific platform video IDs; pass a list of video IDs","items":{"type":"string"},"type":"array"}},"required":["platform_account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"last_synced_at":{"description":"Last sync time of the account's video data (Unix timestamp in seconds)","type":"integer"},"limit":{"description":"Items per page","type":"integer"},"page":{"description":"Current page number","type":"integer"},"total_count":{"description":"Total number of videos matching the conditions","type":"integer"},"videos":{"items":{"properties":{"cover_url":{"description":"Cover image URL","type":"string"},"duration":{"description":"Video duration (seconds)","type":"number"},"media_type":{"description":"Media type: video / image / carousel","type":"string"},"metrics":{"description":"Video metrics","properties":{"comment_count":{"description":"Comment count","type":"integer"},"like_count":{"description":"Like count","type":"integer"},"play_count":{"description":"Play count","type":"integer"},"share_count":{"description":"Share count","type":"integer"}},"type":"object"},"metrics_updated_at":{"description":"Last update time of the metrics (Unix timestamp in seconds)","type":"integer"},"platform":{"description":"Platform identifier","type":"string"},"platform_url":{"description":"URL of the video on the platform","type":"string"},"platform_video_id":{"description":"Platform-side video ID","type":"string"},"publication_id":{"description":"Associated publication task ID (returned when published through this system, null for third-party publications)","type":"integer"},"published_at":{"description":"Publish time (Unix timestamp in seconds)","type":"integer"},"video_id":{"description":"Video record ID (internal system identifier)","type":"integer"},"video_title":{"description":"Video title","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Platform Video Metrics List","tags":["Social/3.Video Management"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.social.read"}},"/open/v1/tasks/{task_id}":{"get":{"description":"Query the status and result of an async task. Failed tasks are auto-refunded, status becomes refunded.","operationId":"task-status","parameters":[{"description":"Async task ID (returned by async endpoints)","in":"path","name":"task_id","required":true,"schema":{"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"status":"completed","task_id":"task_abc123"},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"error_message":{"description":"Error message (only when refunded)","type":"string"},"result":{"description":"Task result (only when completed)","type":"object"},"status":{"description":"Task status","enum":["pending","running","completed","refunded"],"type":"string"},"task_id":{"description":"Task ID","type":"string"}},"required":["task_id","status"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Query async task status","tags":["Async Tasks"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/videos/search":{"get":{"description":"Search TikTok shoppable videos with multi-dimensional filters on views, GMV, engagement rate, etc.","operationId":"trenz-videos-search","parameters":[{"description":"Search keyword","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"Video category ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Whether is a commerce video","example":false,"in":"query","name":"is_commercial","required":false,"schema":{"type":"boolean"}},{"description":"Min views","example":1000,"in":"query","name":"min_views","required":false,"schema":{"type":"number"}},{"description":"Max views","example":1000000,"in":"query","name":"max_views","required":false,"schema":{"type":"number"}},{"description":"Min likes","example":100,"in":"query","name":"min_likes","required":false,"schema":{"type":"number"}},{"description":"Max likes","example":100000,"in":"query","name":"max_likes","required":false,"schema":{"type":"number"}},{"description":"30-day min GMV (USD)","example":1000,"in":"query","name":"min_gmv_30d","required":false,"schema":{"type":"number"}},{"description":"30-day max GMV (USD)","example":100000,"in":"query","name":"max_gmv_30d","required":false,"schema":{"type":"number"}},{"description":"Min engagement rate (0-1)","example":0.01,"in":"query","name":"min_engagement","required":false,"schema":{"type":"number"}},{"description":"Max engagement rate (0-1)","example":0.1,"in":"query","name":"max_engagement","required":false,"schema":{"type":"number"}},{"description":"Sort, format: field:asc|desc. Allowed: engagement, gmv_30d, launch_time, likes, sold_30d, views. Default: views:desc","example":"views:desc","in":"query","name":"sort","required":false,"schema":{"default":"views:desc","enum":["engagement","gmv_30d","launch_time","likes","sold_30d","views"],"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"account_type":{"description":"Account type","type":"integer"},"author_category_label":{"description":"Author category label","type":"string"},"author_id":{"description":"Author user ID","type":"string"},"author_nickname":{"description":"Author name","type":"string"},"author_unique_id":{"description":"Author TikTok username","type":"string"},"country_code":{"description":"Country code","type":"string"},"follow_cnt":{"description":"Follower count","type":"integer"},"id":{"description":"Unique identifier","type":"string"},"is_ad":{"description":"Is advertisement","type":"boolean"},"is_aigc_video":{"description":"Is AI-generated video","type":"boolean"},"product_id":{"description":"Product ID","type":"string"},"product_l1_category":{"description":"Product L1 category","type":"string"},"product_l2_category":{"description":"Product L2 category","type":"string"},"product_l3_category":{"description":"Product L3 category","type":"string"},"product_title":{"description":"Product title","type":"string"},"share_url":{"description":"TikTok share URL","type":"string"},"video_30d_gmv":{"description":"30-day video GMV","type":"string"},"video_30d_gpm":{"description":"30-day video GPM","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"video_30d_sold_count":{"description":"30-day video sales","type":"string"},"video_ceiling_price":{"description":"Product max price","type":"string"},"video_collect_count":{"description":"Save count","type":"integer"},"video_comment_count":{"description":"Comment count","type":"integer"},"video_commission_rate":{"description":"Product commission rate","type":"string"},"video_desc":{"description":"Video description","type":"string"},"video_duration":{"description":"Duration (ms)","type":"integer"},"video_engagement_rate":{"description":"Engagement rate (0-1)","type":"number"},"video_floor_price":{"description":"Product min price","type":"string"},"video_launch_time":{"description":"Published at (ms timestamp)","type":"integer"},"video_like_count":{"description":"Like count","type":"integer"},"video_play_count":{"description":"View count","type":"integer"},"video_product_total_gmv":{"description":"Product total GMV","type":"string"},"video_product_total_sold_count":{"description":"Product total sales","type":"string"},"video_share_count":{"description":"Share count","type":"integer"},"video_total_like_count_to_follower_count_ratio":{"description":"Likes to followers ratio","type":"number"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Video Search","tags":["Data/3.Videos"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.videos.read"}},"/open/v1/videos/{id}":{"get":{"description":"Get TikTok video details with linked products.","operationId":"trenz-videos-detail","parameters":[{"description":"Video ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Include related resources, comma-separated (values: core(Core Metrics))","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"account_type":{"description":"Account type","type":"integer"},"author_avg_engagement_rate":{"description":"Avg engagement rate","type":"number"},"country_code":{"description":"Country code","type":"string"},"follower_count":{"description":"Follower count","type":"integer"},"had_product":{"description":"Has linked product","type":"boolean"},"has_comment":{"description":"Has comments","type":"boolean"},"id":{"description":"Unique identifier","type":"string"},"is_ad":{"description":"Is advertisement","type":"boolean"},"is_aigc_video":{"description":"Is AI-generated video","type":"boolean"},"last_update_time":{"description":"Last updated (ms timestamp)","type":"integer"},"nickname":{"description":"Display name","type":"string"},"product_category_label_list":{"description":"Product category labels","type":"string"},"share_url":{"description":"TikTok share URL","type":"string"},"uid":{"description":"User ID","type":"string"},"unique_id":{"description":"TikTok username","type":"string"},"user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"video_avg_like_count":{"description":"Avg video likes","type":"number"},"video_avg_play_count":{"description":"Avg video views","type":"number"},"video_count":{"description":"Video count","type":"integer"},"video_cover":{"description":"Video cover","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"video_desc":{"description":"Video description","type":"string"},"video_duration":{"description":"Duration (ms)","type":"integer"},"video_launch_time":{"description":"Published at (ms timestamp)","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Video Detail","tags":["Data/3.Videos"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.videos.read"}},"/open/v1/videos/{id}/products":{"get":{"description":"","operationId":"trenz-videos-products","parameters":[{"description":"Video ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_product_detail_ceiling_price":{"description":"Max price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_commission_rate":{"description":"Commission rate","type":"number"},"tiktok_product_detail_floor_price":{"description":"Min price","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_product_detail_l1_category":{"description":"Level-1 category","type":"string"},"tiktok_product_detail_l2_category":{"description":"Level-2 category","type":"string"},"tiktok_product_detail_l3_category":{"description":"Level-3 category","type":"string"},"tiktok_product_detail_product_images":{"description":"Product images","items":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_name":{"description":"Product name","type":"string"},"tiktok_product_detail_product_rating":{"description":"Product rating (0-5)","type":"number"},"tiktok_product_detail_product_sku_props":{"description":"SKU properties","items":{"properties":{"has_image":{"description":"Has image","type":"boolean"},"prop_id":{"description":"Property ID","type":"string"},"prop_name":{"description":"Property name","type":"string"},"sale_prop_values":{"description":"Property values","items":{"properties":{"image":{"properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"prop_value":{"description":"Property value","type":"string"},"prop_value_id":{"description":"Property value ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_skus":{"description":"SKU list","items":{"properties":{"is_hot":{"description":"Is hot selling","type":"boolean"},"price":{"properties":{"discount":{"description":"Discount info","type":"string"},"original_price":{"description":"Original price","type":"string"},"original_price_value":{"description":"Original price value","type":"string"},"real_price":{"description":"Actual price","type":"number"},"unit_price_desc":{"description":"Unit price description","type":"string"}},"type":"object"},"sale_prop_value_ids":{"description":"Property value ID combination","type":"string"},"sku_id":{"description":"SKU ID","type":"string"},"sku_sale_props":{"description":"SKU properties","items":{"properties":{"prop_id":{"description":"Property ID","type":"string"},"prop_name":{"description":"Property name (e.g. Color)","type":"string"},"prop_value":{"description":"Property value","type":"string"},"prop_value_id":{"description":"Property value ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"Status (1=active)","type":"integer"},"stock":{"description":"Stock","type":"integer"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_status":{"description":"Product status","type":"integer"},"tiktok_product_detail_region":{"description":"Region code","type":"string"},"tiktok_video_detail_product_country_code":{"description":"Product country","type":"string"},"tiktok_video_detail_product_id":{"description":"Product ID","type":"string"},"tiktok_video_detail_product_launch_time":{"description":"Product listing time (ms timestamp)","type":"integer"},"tiktok_video_detail_product_total_gmv":{"description":"Product total GMV","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_video_detail_product_total_sold_count":{"description":"Product total sales","type":"integer"},"tiktok_video_detail_video_30d_gmv":{"description":"Video 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_video_detail_video_30d_sold_count":{"description":"Video 30D Sold Count","type":"integer"},"tiktok_video_detail_video_id":{"description":"Video ID","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Video Products","tags":["Data/3.Videos"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.videos.read"}},"/open/v1/videos/{id}/reviews":{"get":{"description":"","operationId":"trenz-videos-reviews","parameters":[{"description":"Video ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_video_detail_comment_create_time":{"description":"Listing time","type":"integer"},"tiktok_video_detail_comment_id":{"description":"Unique identifier","type":"string"},"tiktok_video_detail_comment_like_count":{"description":"Like count","type":"integer"},"tiktok_video_detail_comment_nickname":{"description":"Display name","type":"string"},"tiktok_video_detail_comment_reply_count":{"description":"Reply count","type":"integer"},"tiktok_video_detail_comment_text":{"description":"Text content","type":"string"},"tiktok_video_detail_comment_unique_id":{"description":"TikTok username","type":"string"},"tiktok_video_detail_comment_user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_video_detail_video_id":{"description":"Video ID","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Video Reviews","tags":["Data/3.Videos"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.videos.read"}},"/open/v1/videos/{id}/similar":{"get":{"description":"","operationId":"trenz-videos-similar","parameters":[{"description":"Video ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Page number, default 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Page size, default 20, max 20","in":"query","name":"page_size","required":false,"schema":{"default":20,"maximum":20,"type":"integer"}},{"description":"Routing parameter: routes to different backends by country value","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"Unique identifier","type":"string"},"tiktok_video_detail_similar_author_nickname":{"description":"Author display name","type":"string"},"tiktok_video_detail_similar_author_uid":{"description":"Author user ID","type":"string"},"tiktok_video_detail_similar_author_unique_id":{"description":"Author TikTok username","type":"string"},"tiktok_video_detail_similar_category_label":{"description":"Creator category label","type":"string"},"tiktok_video_detail_similar_country_code":{"description":"Country code","type":"string"},"tiktok_video_detail_similar_follower_cnt":{"description":"Follower count","type":"integer"},"tiktok_video_detail_similar_is_aigc_video":{"description":"Is AI-generated video","type":"boolean"},"tiktok_video_detail_similar_product_id":{"description":"Product ID","type":"string"},"tiktok_video_detail_similar_product_images":{"description":"Product images","type":"string"},"tiktok_video_detail_similar_product_l1_category":{"description":"Product L1 Category","type":"string"},"tiktok_video_detail_similar_product_l2_category":{"description":"Product L2 Category","type":"string"},"tiktok_video_detail_similar_product_l3_category":{"description":"Product L3 Category","type":"string"},"tiktok_video_detail_similar_product_title":{"description":"Product title","type":"string"},"tiktok_video_detail_similar_share_url":{"description":"TikTok share URL","type":"string"},"tiktok_video_detail_similar_user_avatar":{"description":"User avatar","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_video_detail_similar_video_30d_gmv":{"description":"Video 30D Gmv","properties":{"unit":{"description":"Currency code (e.g. US)","type":"string"},"value":{"description":"Amount","type":"number"}},"type":"object"},"tiktok_video_detail_similar_video_comment_count":{"description":"Comment count","type":"integer"},"tiktok_video_detail_similar_video_cover":{"description":"Video cover","properties":{"thumb_url":{"description":"Thumbnail URL","type":"string"},"url":{"description":"Image URL","type":"string"}},"type":"object"},"tiktok_video_detail_similar_video_desc":{"description":"Video description","type":"string"},"tiktok_video_detail_similar_video_duration":{"description":"Duration (ms)","type":"integer"},"tiktok_video_detail_similar_video_id":{"description":"Video ID","type":"string"},"tiktok_video_detail_similar_video_launch_time":{"description":"Published at (ms timestamp)","type":"integer"},"tiktok_video_detail_similar_video_like_count":{"description":"Like count","type":"integer"},"tiktok_video_detail_similar_video_play_count":{"description":"View count","type":"integer"},"tiktok_video_detail_similar_video_share_count":{"description":"Share count","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"Total result count","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Similar Videos","tags":["Data/3.Videos"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"trenz.videos.read"}}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"servers":[{"description":"Production","url":"https://openapi.gateway.trenz.ai"}],"tags":[{"description":"Query account status, tier and credits balance.","name":"Account"},{"name":"Ads/1.Accounts"},{"name":"Ads/2.Delivery"},{"name":"Ads/3.GMV MAX"},{"description":"## Async Task Workflow\n\n1. Submit the task (e.g. POST /open/v1/ai/videos/content-analysis) → returns `task_id`\n2. Poll status: GET /open/v1/tasks/{task_id}\n   - status=\"running\" → keep polling (recommended interval 3-5 sec)\n   - status=\"success\" → the `result` field contains the full result\n   - status=\"failed\" → the `error_message` field contains the error details\n3. Successful task results are persisted and can be retrieved again at any time\n\n\u003e All AI analysis and AI generation endpoints are async.\n\u003e They return `task_id` immediately without blocking.","name":"Async Tasks"},{"description":"All `*_url` fields in this section require publicly accessible URLs. To upload local files, first call the 'Generate Presigned Upload URL' endpoint under 'File Upload'.","name":"Content/1.AI Video"},{"description":"All `*_url` fields in this section require publicly accessible URLs. To upload local files, first call the 'Generate Presigned Upload URL' endpoint under 'File Upload'.","name":"Content/2.AI Image"},{"name":"Content/3.AI Copywriting"},{"name":"Content/4.AI Analysis"},{"description":"## Product Category ID Reference\n\nThe `category` parameter in search endpoints takes a numeric category ID. Below is the TikTok Level-1 category list:\n\n| Category ID | Category |\n|-------------|----------|\n| 601450 | Beauty \u0026 Personal Care |\n| 601152 | Womenswear \u0026 Underwear |\n| 700645 | Health |\n| 603014 | Sports \u0026 Outdoor |\n| 601739 | Phones \u0026 Electronics |\n| 600942 | Home Appliances |\n| 824328 | Menswear \u0026 Underwear |\n| 605248 | Fashion Accessories |\n| 700437 | Food \u0026 Beverages |\n| 600001 | Household Products |\n| 604453 | Furniture |\n| 600024 | Kitchenware |\n| 600154 | Home Textiles |\n| 824584 | Luggage \u0026 Bags |\n| 604206 | Toys \u0026 Hobbies |\n| 601352 | Shoes |\n| 604579 | Tools \u0026 Hardware |\n| 604968 | Home Improvement |\n| 602118 | Pet Supplies |\n| 601755 | Computers \u0026 Office |\n| 602284 | Baby \u0026 Maternity |\n| 605196 | Automotive \u0026 Motorcycle |\n| 951432 | Collectibles |\n| 801928 | Books, Magazines \u0026 Audio/Video |\n| 953224 | Jewelry \u0026 Accessories |\n| 856720 | Pre-Owned Goods |\n| 802184 | Kids' Fashion |\n\n\u003e These are Level-1 categories. Passing a Level-1 ID filters all products under that category.","name":"Data/1.Products"},{"description":"## Parameters\n\n- `category`: Creator category ID (a content-niche tag, a different taxonomy from product categories). See \"Creator Category ID Reference\" below for allowed values. You may also search without it and read the `category_label` field from the response for precise filtering.\n- `has_contact`: Whether the creator has public contact info (true/false), filters creators with public email or social handles.\n\n## Creator Category ID Reference\n\n| Category ID | Category |\n|-------------|----------|\n| creator_category_v20240616_8 | Shopping \u0026 Retail |\n| creator_category_v20240616_15 | Media \u0026 Entertainment |\n| creator_category_v20240616_10 | Beauty \u0026 Fashion |\n| creator_category_v20240616_14 | Personal Blog |\n| creator_category_v20240616_12 | Clothing \u0026 Accessories |\n| creator_category_v20240616_32 | Public Figure |\n| creator_category_v20240616_23 | Art \u0026 Crafts |\n| creator_category_v20240616_17 | Sports \u0026 Fitness |\n| creator_category_v20240616_24 | Health \u0026 Wellness |\n| creator_category_v20240616_13 | Music \u0026 Dance |\n| creator_category_v20240616_9 | Home, Furniture \u0026 Appliances |\n| creator_category_v20240616_19 | Pets \u0026 Animals |\n| creator_category_v20240616_18 | Education |\n| creator_category_v20240616_11 | Food \u0026 Drink |\n| creator_category_v20240616_31 | Automotive \u0026 transportation |\n| creator_category_v20240616_5 | Electronics |\n| creator_category_v20240616_29 | Gaming |\n| creator_category_v20240616_30 | Professional Services |\n| creator_category_v20240616_16 | Baby |\n| creator_category_v20240616_33 | Food \u0026 Cooking |\n| creator_category_v20240616_20 | Travel \u0026 Tourism |\n| creator_category_v20240616_27 | Finance \u0026 Investing |\n| creator_category_v20240616_2 | Machinery \u0026 Equipment |\n| creator_category_v20240616_21 | Brand |\n| creator_category_v20240616_25 | Consultant \u0026 Service |\n| creator_category_v20240616_4 | Property |\n| creator_category_v20240616_28 | Government \u0026 Politics |\n| creator_category_v20240616_6 | Restaurants \u0026 Bars |\n| creator_category_v20240616_26 | IT \u0026 High Tech |\n| creator_category_v20240616_22 | Software \u0026 Apps |\n| creator_category_v20240616_3 | LIVE Creator Networks |\n| creator_category_v20240616_7 | Movie, TV \u0026 Studio |\n| creator_category_v20240616_34 | Others |\n\n\u003e Creator and streamer (live) categories share the same taxonomy; this table also applies to the `category` parameter of \"Data/6.Lives\".","name":"Data/2.Creators"},{"description":"## Parameters\n\n- `is_commercial`: Whether this is a commerce video (true/false)\n\n## Product Category ID Reference\n\nThe `category` parameter is the video's associated product category ID:\n\n| Category ID | Category |\n|-------------|----------|\n| 601450 | Beauty \u0026 Personal Care |\n| 601152 | Womenswear \u0026 Underwear |\n| 700645 | Health |\n| 603014 | Sports \u0026 Outdoor |\n| 601739 | Phones \u0026 Electronics |\n| 600942 | Home Appliances |\n| 824328 | Menswear \u0026 Underwear |\n| 605248 | Fashion Accessories |\n| 700437 | Food \u0026 Beverages |\n| 600001 | Household Products |\n| 604453 | Furniture |\n| 600024 | Kitchenware |\n| 600154 | Home Textiles |\n| 824584 | Luggage \u0026 Bags |\n| 604206 | Toys \u0026 Hobbies |\n| 601352 | Shoes |\n| 604579 | Tools \u0026 Hardware |\n| 604968 | Home Improvement |\n| 602118 | Pet Supplies |\n| 601755 | Computers \u0026 Office |\n| 602284 | Baby \u0026 Maternity |\n| 605196 | Automotive \u0026 Motorcycle |\n| 951432 | Collectibles |\n| 801928 | Books, Magazines \u0026 Audio/Video |\n| 953224 | Jewelry \u0026 Accessories |\n| 856720 | Pre-Owned Goods |\n| 802184 | Kids' Fashion |\n\n\u003e These are Level-1 categories. Passing a Level-1 ID filters all videos in that category.","name":"Data/3.Videos"},{"description":"## Parameters\n\n- `seller_type`: Seller type (1=Overseas Non-Brand, 2=Local, 3=Brand, 4=Non-Brand)\n\n## Product Category ID Reference\n\nThe `category` parameter is the seller's primary product category ID; it uses the same taxonomy as product search:\n\n| Category ID | Category |\n|-------------|----------|\n| 601450 | Beauty \u0026 Personal Care |\n| 601152 | Womenswear \u0026 Underwear |\n| 700645 | Health |\n| 603014 | Sports \u0026 Outdoor |\n| 601739 | Phones \u0026 Electronics |\n| 600942 | Home Appliances |\n| 824328 | Menswear \u0026 Underwear |\n| 605248 | Fashion Accessories |\n| 700437 | Food \u0026 Beverages |\n| 600001 | Household Products |\n| 604453 | Furniture |\n| 600024 | Kitchenware |\n| 600154 | Home Textiles |\n| 824584 | Luggage \u0026 Bags |\n| 604206 | Toys \u0026 Hobbies |\n| 601352 | Shoes |\n| 604579 | Tools \u0026 Hardware |\n| 604968 | Home Improvement |\n| 602118 | Pet Supplies |\n| 601755 | Computers \u0026 Office |\n| 602284 | Baby \u0026 Maternity |\n| 605196 | Automotive \u0026 Motorcycle |\n| 951432 | Collectibles |\n| 801928 | Books, Magazines \u0026 Audio/Video |\n| 953224 | Jewelry \u0026 Accessories |\n| 856720 | Pre-Owned Goods |\n| 802184 | Kids' Fashion |\n\n\u003e These are Level-1 categories. Passing a Level-1 ID filters all sellers primarily in that category.","name":"Data/4.Sellers"},{"name":"Data/5.Ads \u0026 Creatives"},{"description":"## Parameters\n\n- `category`: Streamer category ID; uses the same taxonomy as creator categories. See \"Streamer Category ID Reference\" below for allowed values. You may also search without it.\n- `is_living`: Whether currently live-streaming (true/false)\n- `is_commercial`: Whether this is a commerce live stream (true/false)\n\n## Streamer Category ID Reference\n\n| Category ID | Category |\n|-------------|----------|\n| creator_category_v20240616_8 | Shopping \u0026 Retail |\n| creator_category_v20240616_15 | Media \u0026 Entertainment |\n| creator_category_v20240616_10 | Beauty \u0026 Fashion |\n| creator_category_v20240616_14 | Personal Blog |\n| creator_category_v20240616_12 | Clothing \u0026 Accessories |\n| creator_category_v20240616_32 | Public Figure |\n| creator_category_v20240616_23 | Art \u0026 Crafts |\n| creator_category_v20240616_17 | Sports \u0026 Fitness |\n| creator_category_v20240616_24 | Health \u0026 Wellness |\n| creator_category_v20240616_13 | Music \u0026 Dance |\n| creator_category_v20240616_9 | Home, Furniture \u0026 Appliances |\n| creator_category_v20240616_19 | Pets \u0026 Animals |\n| creator_category_v20240616_18 | Education |\n| creator_category_v20240616_11 | Food \u0026 Drink |\n| creator_category_v20240616_31 | Automotive \u0026 transportation |\n| creator_category_v20240616_5 | Electronics |\n| creator_category_v20240616_29 | Gaming |\n| creator_category_v20240616_30 | Professional Services |\n| creator_category_v20240616_16 | Baby |\n| creator_category_v20240616_33 | Food \u0026 Cooking |\n| creator_category_v20240616_20 | Travel \u0026 Tourism |\n| creator_category_v20240616_27 | Finance \u0026 Investing |\n| creator_category_v20240616_2 | Machinery \u0026 Equipment |\n| creator_category_v20240616_21 | Brand |\n| creator_category_v20240616_25 | Consultant \u0026 Service |\n| creator_category_v20240616_4 | Property |\n| creator_category_v20240616_28 | Government \u0026 Politics |\n| creator_category_v20240616_6 | Restaurants \u0026 Bars |\n| creator_category_v20240616_26 | IT \u0026 High Tech |\n| creator_category_v20240616_22 | Software \u0026 Apps |\n| creator_category_v20240616_3 | LIVE Creator Networks |\n| creator_category_v20240616_7 | Movie, TV \u0026 Studio |\n| creator_category_v20240616_34 | Others |\n\n\u003e `category` (streamer category) and `product_category` (commerce product category) are two different taxonomies — do not mix them up.\n\n## Product Category ID Reference\n\nThe `product_category` parameter is the product category ID for commerce lives:\n\n| Category ID | Category |\n|-------------|----------|\n| 601450 | Beauty \u0026 Personal Care |\n| 601152 | Womenswear \u0026 Underwear |\n| 700645 | Health |\n| 603014 | Sports \u0026 Outdoor |\n| 601739 | Phones \u0026 Electronics |\n| 600942 | Home Appliances |\n| 824328 | Menswear \u0026 Underwear |\n| 605248 | Fashion Accessories |\n| 700437 | Food \u0026 Beverages |\n| 600001 | Household Products |\n| 604453 | Furniture |\n| 600024 | Kitchenware |\n| 600154 | Home Textiles |\n| 824584 | Luggage \u0026 Bags |\n| 604206 | Toys \u0026 Hobbies |\n| 601352 | Shoes |\n| 604579 | Tools \u0026 Hardware |\n| 604968 | Home Improvement |\n| 602118 | Pet Supplies |\n| 601755 | Computers \u0026 Office |\n| 602284 | Baby \u0026 Maternity |\n| 605196 | Automotive \u0026 Motorcycle |\n| 951432 | Collectibles |\n| 801928 | Books, Magazines \u0026 Audio/Video |\n| 953224 | Jewelry \u0026 Accessories |\n| 856720 | Pre-Owned Goods |\n| 802184 | Kids' Fashion |\n\n\u003e These are Level-1 categories. Passing a Level-1 ID filters all lives in that category.","name":"Data/6.Lives"},{"name":"File Upload"},{"description":"You must bind at least one social account before using any social media feature. TikTok QR-code login is currently supported.\n\nOnce bound, call 'Social Account List' to view all connected accounts with their status and metrics.","name":"Social/1.Account Management"},{"description":"One-step publishing via 'Upload and Publish Video', with support for immediate and scheduled publishing across multiple accounts.\n\n## Prerequisite: Bind a Social Account\n\nYou must bind at least one social account before publishing. Go to 'Social/1.Account Management' and use 'TikTok QR Code Login' + 'TikTok QR Code Status' for QR-based binding.\n\nOnce bound, retrieve the `id` field from 'Social Account List' — this is the `platform_account_id` required by the publishing endpoint below.\n\n---\n\n## Step 1: Upload File\n\n### 1.1 Call 'Generate Presigned Upload URL' to get a temporary upload URL (this endpoint is under 'File Upload')\n\n```bash\ncurl -X POST \"https://openapi.gateway.trenz.com/open/v1/social/upload/presigned-url\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"file_name\": \"my_video.mp4\"}'\n```\n\nResponse example:\n```json\n{\n  \"data\": {\n    \"presigned_url\": \"https://data-datanebula-object.tos-ap-southeast-1.volces.com/upload/my_video.mp4_xxx?...\",\n    \"object_key\": \"upload/my_video.mp4_xxx\",\n    \"s3_bucket\": \"data-datanebula-object\",\n    \"cdn_url\": \"https://oss-data.trenz.ai/upload%2Fmy_video.mp4_xxx?...\"\n  }\n}\n```\n\n\u003e Record the returned `object_key` and `s3_bucket` — they are needed in the following steps.\n\n### 1.2 Upload the file to presigned_url via PUT\n\n```bash\ncurl -X PUT \"{presigned_url}\" \\\n  -H \"Content-Type: video/mp4\" \\\n  --data-binary @my_video.mp4\n```\n\n\u003e presigned_url is valid for 1 hour. File size limits depend on the target platform (TikTok max 4GB, YouTube max 256GB, Instagram Reels max 1GB).\n\n---\n\n## Step 2: Validate Video Info (Recommended)\n\nAfter upload, call 'Validate Video Info' to check that the video matches the target platform's spec (resolution, duration, bitrate, etc.) and avoid publishing failures:\n\n```bash\ncurl -X POST \"https://openapi.gateway.trenz.com/open/v1/social/videos/check-info\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"bucket_name\": \"data-datanebula-object\", \"object_key\": \"upload/my_video.mp4_xxx\"}'\n```\n\n\u003e This endpoint checks encoding, resolution, duration, etc. against the requirements of TikTok, YouTube, Instagram and other platforms.\n\u003e Note: this endpoint's file path parameter is named `object_key`, unlike the `bucket_key` parameter of the Step 3 publish endpoint — both take the same value (the `object_key` returned in Step 1).\n\n---\n\n## Step 3: Call 'Upload and Publish Video'\n\n```bash\ncurl -X POST \"https://openapi.gateway.trenz.com/open/v1/social/publish/upload-and-publish\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"video_title\": \"My Video\",\n    \"video_description\": \"Check this out!\",\n    \"bucket_name\": \"data-datanebula-object\",\n    \"bucket_key\": \"upload/my_video.mp4_xxx\",\n    \"publications\": [\n      {\n        \"platform_account_id\": 4687,\n        \"title\": \"Check out this video!\",\n        \"platform_config\": \"{\\\"privacy\\\":\\\"PUBLIC_TO_EVERYONE\\\"}\"\n      }\n    ]\n  }'\n```\n\n\u003e `bucket_name` = the `s3_bucket` returned in Step 1, `bucket_key` = the `object_key` returned in Step 1.\n\u003e Supports publishing to multiple accounts in parallel via the `publications` array. The returned `session_token` is used to poll publishing progress.\n\n### Scheduled Publishing\n\nSet `scheduled_at` (Unix seconds) in each `publications` entry to schedule publishing. Each account can have its own schedule:\n\n```json\n{\n  \"video_title\": \"My Video\",\n  \"bucket_name\": \"data-datanebula-object\",\n  \"bucket_key\": \"upload/my_video.mp4_xxx\",\n  \"publications\": [\n    {\n      \"platform_account_id\": 4687,\n      \"title\": \"Publish now\",\n      \"platform_config\": \"{\\\"privacy\\\":\\\"PUBLIC_TO_EVERYONE\\\"}\"\n    },\n    {\n      \"platform_account_id\": 5678,\n      \"title\": \"Publish tomorrow\",\n      \"scheduled_at\": 1774100400,\n      \"platform_config\": \"{\\\"share_to_feed\\\":true}\"\n    }\n  ]\n}\n```\n\n\u003e `scheduled_at` must fall within 5 minutes to 90 days from now. Omit or set to 0 for immediate publishing; values under 5 minutes are auto-demoted to immediate.\n\u003e Scheduled publications can be rescheduled via the 'Reschedule' endpoint.\n\n---\n\n## Step 4: Poll 'Publish Session Status'\n\n```bash\ncurl -X POST \"https://openapi.gateway.trenz.com/open/v1/social/publish/session\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"session_token\": \"127169e7-35e3-40...\"}'\n```\n\n\u003e Recommended poll interval: 3–5 seconds. Repeat until status is completed or failed.\n\n### Cancel Publishing (Optional)\n\n- 'Cancel Publish Session' cancels an in-progress session: `POST /open/v1/social/publish/session/cancel`\n- 'Cancel Individual Publish' cancels a submitted publication: `POST /open/v1/social/publish/cancel`","name":"Social/2.Video Publishing"},{"name":"Social/3.Video Management"},{"name":"Social/4.Comment Management"},{"name":"Social/5.Analytics"},{"name":"Social/6.Creation Tools"},{"name":"Social/7.TikTok Shop"},{"description":"Send and receive direct messages across WhatsApp / WhatsApp Business / LINE / TikTok / Facebook / Instagram, with support for text, media (image/video/document) and quoted replies.\n\n## Core Concepts\n\n- **Channel**: one social media account bound to the DM system (one WhatsApp number / one TikTok account = one channel); a channel contains conversations with multiple contacts\n- **Conversation**: the message thread between a channel and a single contact (or group)\n- **Messaging window**: some platforms restrict business-initiated messages to a time window — 24h after the customer's last message for WhatsApp Business / Facebook / Instagram, 48h with a 10-message cap for TikTok, unlimited for WhatsApp personal / LINE. Sending outside the window fails\n\n## Step 1: List Channels\n\nCall 'DM Channel List' to see your bound social accounts and record the `channel_id`:\n\n```bash\ncurl -X POST \"https://openapi.gateway.trenz.com/open/v1/social/im/channels/list\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"limit\": 20, \"offset\": 0}'\n```\n\n\u003e `limit` and `offset` are required. Only active channels are returned by default.\n\n## Step 2: List Conversations\n\nUse the `channel_id` to call 'DM Conversation List' and get `conversation_id` plus the messaging-window state:\n\n```bash\ncurl -X POST \"https://openapi.gateway.trenz.com/open/v1/social/im/conversations/list\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"channel_id\": \"550e8400-e29b-41d4-a716-446655440000\", \"limit\": 20}'\n```\n\n\u003e Fixed ordering: pinned conversations first, then by last message time descending. Check `window_info.can_send_message` before sending.\n\n## Step 3: Fetch Messages\n\n```bash\ncurl -X POST \"https://openapi.gateway.trenz.com/open/v1/social/im/conversations/12345/messages\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"limit\": 20}'\n```\n\n\u003e Passing `mark_as_read: true` marks the conversation as read AND sends read receipts to the platform (e.g. WhatsApp blue ticks) visible to the contact — use deliberately.\n\n## Step 4: Send a Message\n\nText messages go directly:\n\n```bash\ncurl -X POST \"https://openapi.gateway.trenz.com/open/v1/social/im/messages/send\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"conversation_id\": \"12345\", \"message_type\": \"text\", \"content\": \"Hi, the item is in stock.\"}'\n```\n\nSending image/video/document takes three steps:\n\n1. Call 'DM Upload Presigned URL' to get an upload address (DM-dedicated storage — **not interchangeable** with the general upload endpoints under 'File Upload')\n2. HTTP PUT the file binary to the returned `presigned_url` (Content-Type must match the request)\n3. Send the message with the returned `object_key` and `s3_bucket` in `media`:\n\n```bash\ncurl -X POST \"https://openapi.gateway.trenz.com/open/v1/social/im/messages/send\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"conversation_id\": \"12345\",\n    \"message_type\": \"image\",\n    \"media\": {\n      \"s3_key\": \"im/2026/07/10/20260710153000_photo.jpg\",\n      \"s3_bucket\": \"datanebula-object\",\n      \"filename\": \"photo.jpg\",\n      \"mime_type\": \"image/jpeg\"\n    }\n  }'\n```\n\n\u003e Sending is synchronous; success returns `status: sent`. A closed messaging window returns business error code 20510; identical content sent to the same conversation within 10 seconds hits idempotent dedup.\n\n## Getting New Messages\n\nPush notifications are not available yet — poll instead: check 'DM Unread Count' for per-channel unread totals, locate conversations via 'DM Conversation List' with `filter_unread: true`, then fetch the message list.\n\n## More\n\nConversation remark (synced as the WhatsApp contact display name) and conversation tag counts (per AI insight tag) are available under this category.","name":"Social/8.Direct Messages"},{"name":"Social/9.Seller Analytics"},{"description":"AI conversational agent endpoint (streaming Server-Sent Events response).","name":"Trenz Agent/1.Chat"},{"description":"Read-only sessions \u0026 reports: list sessions, get session messages, get session reports, get a single report. Free endpoints.","name":"Trenz Agent/2.Sessions \u0026 Reports"}],"x-tagGroups":[{"name":"Data","tags":["Data/1.Products","Data/2.Creators","Data/3.Videos","Data/4.Sellers","Data/5.Ads \u0026 Creatives","Data/6.Lives"]},{"name":"Content","tags":["Content/1.AI Video","Content/2.AI Image","Content/3.AI Copywriting","Content/4.AI Analysis"]},{"name":"Social","tags":["Social/1.Account Management","Social/2.Video Publishing","Social/3.Video Management","Social/4.Comment Management","Social/5.Analytics","Social/6.Creation Tools","Social/7.TikTok Shop","Social/8.Direct Messages","Social/9.Seller Analytics"]},{"name":"Ads","tags":["Ads/1.Accounts","Ads/2.Delivery","Ads/3.GMV MAX"]},{"name":"Trenz Agent","tags":["Trenz Agent/1.Chat","Trenz Agent/2.Sessions \u0026 Reports"]},{"name":"General","tags":["Account","Async Tasks","File Upload"]}]}