Wireless Debugging Endpoints

Overview

Android’s wireless debugging feature allows you to connect ADB to devices over Wi-Fi. This requires a two-step process:

Pairing - Authenticate with a pairing code (one-time setup)
Connecting - Connect to the device using its IP and port

Wireless debugging requires Android 11 or higher and must be enabled in Developer Options on the device.

POST /api/adb/pair

Pair with a device using wireless debugging. This is a one-time authentication step required before connecting.

Request Body

string

required

Device IP address (e.g., "192.168.1.100")

port

string

required

Pairing port shown in wireless debugging settings (usually 37xxx or 38xxx)

code

string

required

6-digit pairing code shown on the device (e.g., "123456")

Response

boolean

required

Whether pairing was successful

output

string

required

Raw output from the adb pair command

Example Request

curl -X POST http://localhost:3000/api/adb/pair \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "192.168.1.100",
    "port": "37589",
    "code": "123456"
  }'

const response = await fetch('http://localhost:3000/api/adb/pair', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ip: '192.168.1.100',
    port: '37589',
    code: '123456'
  })
});
const data = await response.json();

Example Response (Success)

{
  "ok": true,
  "output": "Successfully paired to 192.168.1.100:37589 [guid=adb-ABC123-XYZ456]"
}

Example Response (Failure)

{
  "ok": false,
  "output": "Failed: Wrong pairing code"
}

Error Response

Returns 400 if required fields are missing:

{
  "error": "Faltan campos requeridos"
}

Returns 500 if ADB command fails:

{
  "error": "Command timeout"
}

How to Get Pairing Information

On the Android device:

Go to Settings → Developer Options
Enable Wireless debugging
Tap Pair device with pairing code
Note the IP address, port, and 6-digit code
Use these values in the API request within 60 seconds

POST /api/adb/connect

Connect to a device via wireless debugging. The device must be paired first (or on the same network and previously paired).

Request Body

string

required

Device IP address (e.g., "192.168.1.100")

port

string

required

Connection port shown in wireless debugging settings (usually 5555 or 4xxxx)Note: This is different from the pairing port!

label

string

Optional custom label for the device. If not provided, the device brand and model will be auto-detected.

Response

boolean

required

Whether connection was successful

output

string

required

Raw output from the adb connect command

Side Effects

On successful connection, the device is automatically:

Added to the saved devices list (or updated if it exists)
Tagged with the current timestamp in lastConnected
Auto-labeled with brand and model if no custom label is provided

Example Request

curl -X POST http://localhost:3000/api/adb/connect \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "192.168.1.100",
    "port": "5555",
    "label": "My Phone"
  }'

const response = await fetch('http://localhost:3000/api/adb/connect', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ip: '192.168.1.100',
    port: '5555',
    label: 'My Phone'
  })
});
const data = await response.json();

Example Response (Success)

{
  "ok": true,
  "output": "connected to 192.168.1.100:5555"
}

Example Response (Already Connected)

{
  "ok": true,
  "output": "already connected to 192.168.1.100:5555"
}

Example Response (Failure)

{
  "ok": false,
  "output": "failed to connect to 192.168.1.100:5555: Connection refused"
}

Error Response

Returns 400 if required fields are missing:

{
  "error": "Faltan campos requeridos"
}

Returns 500 if ADB command fails:

{
  "error": "Command timeout"
}

How to Get Connection Information

On the Android device:

Go to Settings → Developer Options
Enable Wireless debugging
Note the IP address and port shown at the top (e.g., 192.168.1.100:5555)
Use these values in the API request

The connection port (shown at the top of wireless debugging settings) is different from the pairing port (shown when you tap “Pair device with pairing code”).

Workflow

First-Time Pairing

Enable wireless debugging on the device
Call /api/adb/pair with the pairing code
Call /api/adb/connect with the connection port
Device is now connected and saved

Reconnecting Later

Once paired, you only need to call /api/adb/connect on subsequent connections (as long as the device hasn’t been unpaired).

Example: Complete Pairing and Connection

// Step 1: Pair the device
const pairResponse = await fetch('http://localhost:3000/api/adb/pair', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ip: '192.168.1.100',
    port: '37589',  // Pairing port
    code: '123456'
  })
});
const pairResult = await pairResponse.json();

if (!pairResult.ok) {
  console.error('Pairing failed:', pairResult.output);
  return;
}

console.log('Paired successfully!');

// Step 2: Connect to the device
const connectResponse = await fetch('http://localhost:3000/api/adb/connect', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ip: '192.168.1.100',
    port: '5555',  // Connection port (different!)
    label: 'My Phone'
  })
});
const connectResult = await connectResponse.json();

if (connectResult.ok) {
  console.log('Connected successfully!');
} else {
  console.error('Connection failed:', connectResult.output);
}

Troubleshooting

“Failed: Wrong pairing code”

The pairing code expires after 60 seconds
Regenerate a new code on the device and try again

“Connection refused”

Device and computer must be on the same Wi-Fi network
Wireless debugging must still be enabled on the device
Try re-pairing the device

“Device offline”

Device may have gone to sleep
Re-enable wireless debugging on the device
Reconnect using /api/adb/connect

Overview

Endpoints

​Overview

​POST /api/adb/pair

​Request Body

​Response

​Example Request

​Example Response (Success)

​Example Response (Failure)

​Error Response

​How to Get Pairing Information

​POST /api/adb/connect

​Request Body

​Response

​Side Effects

​Example Request

​Example Response (Success)

​Example Response (Already Connected)

​Example Response (Failure)

​Error Response

​How to Get Connection Information

​Workflow

​First-Time Pairing

​Reconnecting Later

​Example: Complete Pairing and Connection

​Troubleshooting

Build docs developers (and LLMs) love

Overview

POST /api/adb/pair

Request Body

Response

Example Request

Example Response (Success)

Example Response (Failure)

Error Response

How to Get Pairing Information

POST /api/adb/connect

Request Body

Response

Side Effects

Example Request

Example Response (Success)

Example Response (Already Connected)

Example Response (Failure)

Error Response

How to Get Connection Information

Workflow

First-Time Pairing

Reconnecting Later

Example: Complete Pairing and Connection

Troubleshooting