Skip to main content

Local API Overview

TikMatrix provides a local RESTful API that allows you to manage tasks programmatically. This is useful for integrating TikMatrix with your own automation systems, building custom workflows, or creating batch operations.

Requirements​

License Requirement

The Local API is only available for Pro, Team, and Business plan subscribers. Starter plan does not have access to the API.

Base URL​

The API runs on your local machine at:

http://localhost:50809/api/v1/
note

The port 50809 is the default port. Make sure TikMatrix is running before making API requests.

Response Format​

All API responses follow this format:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Response Codes​

CodeDescription
0Success
40001Bad Request - Invalid parameters
40002Bad Request - Missing script_name
40003Bad Request - Script not supported, or invalid task state for the action
40004Bad Request - Only running tasks can be stopped
40005Bad Request - task_ids cannot be empty
40301Forbidden - API access requires Pro+ plan
40401Not Found - Resource not found
50001Internal Server Error

Quick Start​

1. Check API Access​

First, verify your license supports API access:

curl http://localhost:50809/api/v1/license/check

Response:

{
  "code": 0,
  "message": "success",
  "data": {
    "plan_name": "Pro",
    "api_enabled": true,
    "device_limit": 20,
    "message": "API access enabled"
  }
}

2. Create a Task​

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1", "device_serial_2"],
    "script_name": "post",
    "script_config": {
      "content_type": 1,
      "captions": "Check out my new video! #viral"
    },
    "enable_multi_account": false,
    "start_time": "14:30"
  }'

3. List Tasks​

curl http://localhost:50809/api/v1/task?status=0&page=1&page_size=20

Available Scripts​

The script_name parameter accepts the following values:

Script NameDescriptionAPI Support
postPublish content✅ Supported
followFollow users✅ Supported
unfollowUnfollow users✅ Supported
account_warmupWarm up accounts✅ Supported
commentPost a new comment on posts✅ Supported
boost_commentLike / reply to existing comments✅ Supported
loginLogin to account✅ Supported
profileUpdate profile✅ Supported
match_accountMatch accounts on device✅ Supported
likeLike posts✅ Supported
viewWatch a post for a duration✅ Supported
favoriteSave a post to Favorites✅ Supported
repostRepost TikTok videos✅ Supported
messageSend direct messages✅ Supported
follow_suggestedFollow suggested accounts✅ Supported
super_marketingSuper marketing campaign✅ Supported †
scrape_userScrape user data🔜 Coming Soon
† Super marketing uses dedicated endpoints

The super marketing campaign is not created through POST /api/v1/task. It runs off a reusable target dataset and has its own endpoints — see the Super Marketing Script Configuration.

Task Status​

Status CodeStatus TextDescription
0pendingTask is waiting to be executed
1runningTask is currently running
2completedTask completed successfully
3failedTask failed

Next Steps​