TCP Scan API

The TCP Scan API scans a range of IPv4 addresses for TCP connectivity and automatically connects reachable Android devices via ADB over the network. This is useful for discovering and connecting wireless Android devices without manual adb connect commands.

Endpoint

POST /api/v1/device/tcp-scan

Requirements

License Requirement

This API requires a Pro, Team, or Business plan. Starter plan does not have access.

Request Body

All fields are optional. When omitted, the app uses the IP range and port configured in Settings.

Field	Type	Required	Description
start_ip	string	No	Starting IPv4 address (e.g., "192.168.1.2"). Defaults to app stored settings.
end_ip	string	No	Ending IPv4 address (e.g., "192.168.1.254"). Defaults to app stored settings.
port	integer	No	TCP port to scan (e.g., 5555). Defaults to app stored scan_port (default: 5555).

Subnet Constraint

The scan is limited to a single /24 subnet. If start_ip and end_ip belong to different /24 subnets, the range is automatically truncated to start_ip.x.x.255.

Examples

Use App Settings (recommended)

Send an empty body to use the IP range and port configured in the app:

curl -X POST http://localhost:50809/api/v1/device/tcp-scan \
  -H "Content-Type: application/json" \
  -d '{}'

Custom IP Range

curl -X POST http://localhost:50809/api/v1/device/tcp-scan \
  -H "Content-Type: application/json" \
  -d '{
    "start_ip": "192.168.1.2",
    "end_ip": "192.168.1.254",
    "port": 5555
  }'

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 3,
    "success": 2,
    "failed": 1,
    "details": [
      {
        "ip": "192.168.1.100",
        "success": true,
        "message": "already connected to 192.168.1.100:5555"
      },
      {
        "ip": "192.168.1.101",
        "success": true,
        "message": "connected to 192.168.1.101:5555"
      },
      {
        "ip": "192.168.1.102",
        "success": false,
        "message": "failed to connect to 192.168.1.102:5555"
      }
    ]
  }
}

Response Fields

Field	Type	Description
data.total	integer	Total IPs that responded on the TCP port
data.success	integer	IPs successfully connected via ADB
data.failed	integer	IPs that failed ADB connection
data.details	array	Per-IP result list
data.details[].ip	string	Scanned IP address
data.details[].success	boolean	true if ADB connection succeeded
data.details[].message	string	ADB output or error message

Error Responses

HTTP Status	Code	Description
403	403	API access requires Pro+ plan

How It Works

1. TCP probe — Each IP in the range is tested with a 1-second TCP connection timeout (concurrent).
2. ADB connect — For each IP that responds, adb connect <ip>:<port> is attempted (up to 2 retries).
3. Result aggregation — All per-IP results are collected and returned.

After a successful scan, connected devices appear in TikMatrix automatically.