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, including a script_config that fails validation
40002Bad Request - Missing script_name
40003Bad Request - Script not supported on this build or platform, has no implementation, 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. Discover the Scripts and Their Parameters​

GET /api/v1/schema describes every script this build can run and the exact script_config fields each one takes — names, types, defaults, allowed values and which fields are required. It is generated from the same catalog the server validates against, so it cannot drift from what task creation accepts.

curl http://localhost:50809/api/v1/schema

Two optional query parameters:

ParameterEffect
platformRestrict the listing to tiktok or instagram. A platform this build does not ship is rejected with 40001. Defaults to everything the build ships.
include_unavailableSet to true to also list script names the API accepts but that have no working implementation. Each carries an unavailable_reason.

Response (abridged):

{
  "code": 0,
  "message": "success",
  "data": {
    "build": { "platforms": ["tiktok"] },
    "scripts": [
      {
        "name": "follow",
        "internal_name": "follow",
        "summary": "Follow the given users. One task per target.",
        "platforms": ["tiktok", "instagram"],
        "available": true,
        "fan_out": { "kind": "per_item", "key": "target_users", "alt_key": "target_user" },
        "any_of": [["target_users", "target_user"]],
        "fields": [
          {
            "key": "access_method",
            "type": "string",
            "required": false,
            "default": "direct",
            "choices": ["direct", "search"],
            "description": "How to reach the profile: direct (via URL) or search."
          }
        ]
      }
    ]
  }
}

fan_out tells you how many tasks a request will produce: per_device creates one task per device (or per account in multi-account mode), per_item creates one per entry of the named field, per device.

3. 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"
  }'

4. 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 videos✅ Supported — TikTok only
messageSend direct messages❌ Not available §
follow_suggestedFollow suggested accounts✅ Supported — TikTok only
custom_scriptRun a program you registered yourself✅ 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.

§ message has no implementation

message was accepted by task creation but the script binary has no handler for it on either platform, so every such task failed on the device with "Unknown script". It is now rejected at creation with that reason instead. To send direct messages today, use super_marketing, which drives DMs through a target dataset.

Platform-specific scripts

repost and follow_suggested are implemented for TikTok only. Creating one against an Instagram target is rejected rather than queued — previously the task was created and then failed on the device.

‡ Custom scripts must be registered first

custom_script runs a program you registered under Devices → Custom Scripts. Pass its id in script_config.custom_script_id — see Custom Scripts.

script_config Validation​

Task creation validates script_config against the schema above before writing anything, so a bad parameter comes back as a 400 naming the field instead of a task that fails on the phone later. Three things are rejected:

  • a required field that is missing or empty,
  • an either-or group where none of the members is set (for example follow needs one of target_users / target_user),
  • a value outside a field's documented choices.

Keys the schema does not list are ignored, not rejected — the desktop app threads its own keys through the same object, and rejecting unknown keys would break existing integrations. They are logged server-side so you can spot a typo in the app log.

Numbers may be sent as strings ("20" as well as 20), matching what the scripts already accept.

Task Status​

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

Next Steps​