LocalSend Protocol Documentation

When the receiver cannot act as an HTTP server, the sender sets up an HTTP server and provides a URL for the receiver to download files via a browser.

Note: This uses unencrypted HTTP because browsers reject self-signed certificates.

1. Browser URL

The receiver opens: http://<sender_ip>:<sender_port>

2. Prepare Download

To get the list of available files, the downloader sends a request to the sender.

Endpoint: POST /api/localsend/v2/prepare-download (Optional: Add ?sessionId=<sessionId> to resume/refresh a specific session).

Response Body:

{
  "info": {
    "alias": "Nice Orange",
    "version": "2.0",
    "deviceModel": "Samsung",
    "deviceType": "mobile",
    "fingerprint": "random_string",
    "download": true
  },
  "sessionId": "mySessionId",
  "files": {
    "file_id_1": {
      "id": "file_id_1",
      "fileName": "image.png",
      "size": 324242,
      "fileType": "image/jpeg",
      "sha256": "hash",
      "preview": "data"
    }
  }
}

3. Receive File

Download the actual binary data.

Endpoint: GET /api/localsend/v2/download?sessionId=<sessionId>&fileId=<fileId>

Response Body: Raw binary data.

The Upload API is the default file transfer method where the receiver hosts the HTTP server and the sender uploads files.

1. Preparation (Metadata Only)

Before sending, the sender must POST metadata to the receiver to get permission and session tokens.

Endpoint: POST /api/localsend/v2/prepare-upload Query Param: Add ?pin=123456 if a PIN is required.

Request Body:

{
  "info": { /* device info */ },
  "files": {
    "file_id_1": {
      "id": "file_id_1",
      "fileName": "image.png",
      "size": 1024,
      "fileType": "image/png"
    }
  }
}

Response:

{
  "sessionId": "mySessionId",
  "files": {
    "file_id_1": "file_token_1"
  }
}

2. Send File

Once you have the sessionId, fileId, and token, perform the actual binary upload.

Endpoint: POST /api/localsend/v2/upload?sessionId=mySessionId&fileId=file_id_1&token=file_token_1 Body: Binary data

3. Cancel

To abort a session: Endpoint: POST /api/localsend/v2/cancel?sessionId=mySessionId

{
  "sessionId": "mySessionId",
  "files": {
    "someFileId": "someFileToken"
  }
}

The Download API is used when the receiver does not have the LocalSend app. The sender hosts an HTTP server, and the receiver (e.g., a web browser) downloads files via a URL.

Note: This uses unencrypted HTTP because browsers reject self-signed certificates for HTTPS.

1. Browser URL

The receiver accesses the sender via: http://<sender-ip>:<sender-port>

2. Receive Request (Metadata Only)

To get the list of available files, the receiver calls: POST /api/localsend/v2/prepare-download

Query Params:

• ?sessionId=mySessionId: Use this if the user refreshes the page to maintain the session.
• ?pin=123456: Use this if a PIN is required.

Response: Returns a JSON object containing info, sessionId, and a files map (containing id, fileName, size, etc.).

3. Receive File

To download a specific file: GET /api/localsend/v2/download?sessionId=mySessionId&fileId=someFileId Response: Binary data

In the standard file transfer flow, the receiver acts as the HTTP server and the sender acts as the client.

1. Prepare Upload (Metadata Only)

Before sending files, the sender must send metadata to the receiver to get permission and session tokens.

Endpoint: POST /api/localsend/v2/prepare-upload

Request Body:

{
  "info": {
    "alias": "Nice Orange",
    "version": "2.0",
    "deviceModel": "Samsung",
    "deviceType": "mobile",
    "fingerprint": "random_string",
    "port": 53317,
    "protocol": "https",
    "download": true
  },
  "files": {
    "file_id_1": {
      "id": "file_id_1",
      "fileName": "image.png",
      "size": 324242,
      "fileType": "image/jpeg",
      "sha256": "hash",
      "preview": "data"
    }
  }
}

Response Body:

{
  "sessionId": "my_session_id",
  "files": {
    "file_id_1": "file_token_1"
  }
}

Prepare Upload Error Codes:

• 204: Completed (No files need to be transferred).
• 400: Invalid request body.
• 403: Rejected.
• 500: Unknown receiver error.

2. Send File

Once you have the sessionId, fileId, and token, upload the binary data.

Endpoint: POST /api/localsend/v2/upload?sessionId=<sessionId>&fileId=<fileId>&token=<token>

Request Body: Raw binary data.

Response: No response body.

Send File Error Codes:

• 400: Missing parameters.
• 403: Invalid token or IP address.
• 409: Blocked by another session.
• 500: Unknown receiver error.

3. Cancel Session

To cancel an ongoing session, use the sessionId obtained during preparation.

Endpoint: POST /api/localsend/v2/cancel?sessionId=<sessionId>

Response: No response body.