Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.
NectarLink Local Authenticated Automation API (docs/api.md)
NectarLink for Windows includes an opt-in, loopback-only HTTP/JSON API (127.0.0.1:<port>, default port 53320) designed for local desktop automation tools:
- PowerToys Command Palette / PowerToys Run (
tools/powertoys-extension) - AutoHotkey / Raycast for Windows / Flow Launcher
- PowerShell & CLI scripts
1. Enabling the API & Discovering the Token
The Local API is off by default. Enable it in Settings → Local automation API (or set "localApiEnabled": true in %LOCALAPPDATA%\Nectarlink\desktop-settings.json).
When enabled, NectarLink binds strictly to 127.0.0.1:<localApiPort> (default 53320) and writes <data-dir>\api-token.json (%LOCALAPPDATA%\Nectarlink\api-token.json):
{
"port": 53320,
"token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
When disabled, the listener stops immediately and api-token.json is removed.
2. Security Model
- Loopback-only binding: The server binds to
127.0.0.1and is never exposed to LAN interfaces. - 256-bit Bearer Token: Every request must include:
Tokens are compared in constant time. Missing or invalid tokens receiveAuthorization: Bearer <64-hex-char-token>401 Unauthorized({"ok":false,"error":"unauthorized"}). - Browser Cross-Origin Protection: Any HTTP request containing an
Originheader (automatically attached by web browsers on cross-originfetch/XMLHttpRequestcalls) is rejected before routing with403 Forbidden({"ok":false,"error":"forbidden"}).
3. Endpoints
GET /v1/devices
Lists paired devices with connection state and battery status.
Response (200 OK):
{
"ok": true,
"devices": [
{
"id": "a1b2c3...",
"name": "Pixel 9 Pro",
"platform": "android",
"online": true,
"link": "lan",
"battery": {
"level": 84,
"charging": false
}
}
]
}
POST /v1/send
Sends files, a URL, or text to a paired phone (defaults to the first online or paired phone when device is omitted).
Request Body:
{
"device": "Pixel 9 Pro",
"paths": ["C:\\Users\\Alice\\Pictures\\diagram.png"],
"url": "https://nectarlink.dev",
"text": "Meeting notes"
}
Response (200 OK):
{ "ok": true }
GET /v1/clipboard
Returns the current PC clipboard text and up to 20 recent clipboard history entries.
Response (200 OK):
{
"ok": true,
"text": "Current clipboard text",
"history": [
{
"id": "clip_00000022",
"kind": "text",
"preview": "Current clipboard text",
"deviceName": "Pixel 9 Pro",
"incoming": true,
"timestamp": 1730000000,
"pinned": false
}
]
}
history holds the 20 most recent items, newest first. kind is text or
image (an image's preview is empty), incoming says whether it came from
deviceName or was sent to it, and timestamp is in Unix seconds.
POST /v1/clipboard
Copies text to the PC clipboard and pushes it to the target phone.
Request Body:
{
"text": "Copied from script",
"device": "Pixel 9 Pro"
}
Response (200 OK):
{ "ok": true }
POST /v1/notify
Sends a task/alert notification to the paired phone.
Request Body:
{
"title": "Build completed",
"body": "cargo test finished in 14s",
"device": "Pixel 9 Pro"
}
Response (200 OK):
{ "ok": true }
POST /v1/ring
Rings the paired phone ("Find my phone").
Request Body:
{
"device": "Pixel 9 Pro"
}
Response (200 OK):
{ "ok": true }
POST /v1/play-on-phone
Play on phone: what one of this PC's players plays moves to the phone, streamed from the PC, or for protected streaming services, opened in the service's app while the PC pauses. The phone shows a notification to tap.
Request Body (optional):
{
"player": "Chrome"
}
Without player, the player that's playing (else the first one).
Response (200 OK):
{ "ok": true, "player": "Chrome" }
404 with "nothing_playing" when no player is there, 409 with
"no_phone" when no phone is online.
POST /v1/camera
Triggers Continuity Camera on the paired phone ("photo" or "scan").
Request Body:
{
"mode": "scan",
"device": "Pixel 9 Pro"
}
Response (200 OK):
{
"ok": true,
"mode": "scan"
}
GET /v1/timeline
Returns recent cross-device timeline items. Accepts optional query parameters ?limit=20&q=<filter>.
Response (200 OK):
{
"ok": true,
"items": [
{
"id": 42,
"kind": "file",
"direction": "incoming",
"deviceId": "a1b2c3...",
"timestamp": 1730000000,
"title": "notes.txt",
"detail": "File",
"target": "C:\\Users\\you\\Downloads\\Nectarlink\\notes.txt",
"sizeBytes": 5
}
]
}
kind is one of file, clip, link, photo, recording or session.
timestamp is in Unix seconds, and target is the saved path (several are
separated by newlines) or the link.
4. Examples
PowerShell
$cfg = Get-Content "$env:LOCALAPPDATA\Nectarlink\api-token.json" | ConvertFrom-Json
$headers = @{ Authorization = "Bearer $($cfg.token)" }
# List paired devices
Invoke-RestMethod -Uri "http://127.0.0.1:$($cfg.port)/v1/devices" -Headers $headers
# Ring your phone
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:$($cfg.port)/v1/ring" `
-Headers $headers -ContentType "application/json" -Body '{}'
curl
TOKEN=$(jq -r .token "$LOCALAPPDATA/Nectarlink/api-token.json")
PORT=$(jq -r .port "$LOCALAPPDATA/Nectarlink/api-token.json")
curl -s -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:$PORT/v1/devices"
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"mode":"photo"}' "http://127.0.0.1:$PORT/v1/camera"