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, instagram or threads. 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", "threads"],
        "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 videos, images, or Threads text-only posts✅ 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 or Threads posts✅ Supported — TikTok and Threads
messageSend direct messages✅ Supported — Threads only
follow_backFollow accounts from the follower list✅ Supported — TikTok, Instagram and Threads
follow_suggestedFollow suggested accounts✅ Supported — TikTok only
custom_scriptRun a program you registered yourself✅ Supported ‡
super_marketingSuper marketing campaign✅ Supported †
scrape_usersExport follower, following, or search usernames✅ Supported — TikTok, Instagram and Threads
† 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.

Threads-only direct messaging

The standalone message task drives the Threads profile → Message flow. For TikTok and Instagram, use super_marketing with a target dataset instead.

Platform-specific scripts

repost is implemented for TikTok and Threads; follow_suggested remains TikTok-only. follow_back and scrape_users use each platform's real-device follower/search UI and are available on TikTok, Instagram and Threads.

‡ 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​