Skip to content

Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.

6.0 KB
Raw Blame

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

  1. Loopback-only binding: The server binds to 127.0.0.1 and is never exposed to LAN interfaces.
  2. 256-bit Bearer Token: Every request must include:
    Authorization: Bearer <64-hex-char-token>
    
    Tokens are compared in constant time. Missing or invalid tokens receive 401 Unauthorized ({"ok":false,"error":"unauthorized"}).
  3. Browser Cross-Origin Protection: Any HTTP request containing an Origin header (automatically attached by web browsers on cross-origin fetch / XMLHttpRequest calls) is rejected before routing with 403 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"