TinyPilot Device Web API

Overview

The TinyPilot Device Web API exposes the HTTP routes the TinyPilot web interface uses to manage the device.

Clients can call these endpoints to manage virtual media, read device status, and run user scripts without using the web UI.

Requirements

• Network access to your TinyPilot device
• HTTPS (recommended). TinyPilot ships with a self-signed certificate; install the device CA from https://<device>/ca.crt to verify TLS.

Authentication

TinyPilot Device Web API requests use a browser session and a CSRF token on writes.

Session

Load the TinyPilot homepage. The response sets a session cookie and includes a CSRF token:

<meta name="csrf-token" content="IjQ1YjNkZWM5..." />

CSRF on writes

All POST, PUT, and DELETE requests to /api/* must include:

X-CSRFToken: <token from meta tag>

If the CSRF token is missing or invalid, returns status code 403.

No users configured

When TinyPilot has no users configured, the device runs in passwordless mode:

• GET requests do not require a session cookie.
• POST, PUT, and DELETE requests require the session cookie and CSRF token from the homepage.

Every client has administrator access.

Users configured

When users are configured, log in before calling protected endpoints.

Pass the session cookie on authenticated requests.

Unauthenticated requests to protected endpoints, or requests from a user whose role lacks permission, return status code 401.

Example: Log in

POST /api/auth HTTP/1.1
Host: tinypilot
Cookie: session=...
Content-Type: application/json
X-CSRFToken: ...

{
  "username": "admin",
  "password": "your-password"
}

HTTP/1.1 200 OK
Content-Type: application/json

{}

Example: Not authorized

GET /api/network/status HTTP/1.1
Host: tinypilot

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Not authorized",
  "code": null
}

Roles

When user authentication is enabled:

When no users are configured, every client has administrator access.

Endpoints

• Status
• Version
• Network status
• Video settings
• Video state
• Virtual media inventory
• Virtual media from URL
• Virtual media mount
• Virtual media eject
• User scripts

Status

GET /api/status

Check whether the TinyPilot server is running. No session is required.

Headers

No headers are required.

Returns

On success, returns status code 200 with an empty JSON object.

Example: Retrieve status

GET /api/status HTTP/1.1
Host: tinypilot

HTTP/1.1 200 OK
Content-Type: application/json

{}

Version

GET /api/version

Retrieve the TinyPilot software version.

Requires operator access when user authentication is enabled.

Headers

• Cookie (required when users are configured): Session cookie.

Returns

On success, returns status code 200 with a JSON object containing a version string.

Example: Retrieve version

GET /api/version HTTP/1.1
Host: tinypilot
Cookie: session=...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "version": "3.0.2"
}

Network status

GET /api/network/status

Retrieve network interface status for the TinyPilot device.

Requires administrator access when user authentication is enabled.

Headers

• Cookie (required when users are configured): Session cookie.

Returns

On success, returns status code 200 with a JSON object containing an interfaces array. Each interface has:

Example: Retrieve network status

GET /api/network/status HTTP/1.1
Host: tinypilot
Cookie: session=...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "interfaces": [
    {
      "name": "eth0",
      "isConnected": true,
      "ipAddress": "192.168.2.41",
      "macAddress": "e4-5f-01-98-65-03"
    },
    {
      "name": "wlan0",
      "isConnected": false,
      "ipAddress": null,
      "macAddress": null
    }
  ]
}

Video settings

GET /api/settings/video

Retrieve the current video streaming settings.

Requires administrator access when user authentication is enabled.

Headers

• Cookie (required when users are configured): Session cookie.

Returns

On success, returns status code 200 with a JSON object:

Example: Retrieve video settings

GET /api/settings/video HTTP/1.1
Host: tinypilot
Cookie: session=...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "streamingMode": "H264",
  "mjpegFrameRate": 12,
  "defaultMjpegFrameRate": 30,
  "mjpegQuality": 80,
  "defaultMjpegQuality": 80,
  "h264Bitrate": 450,
  "defaultH264Bitrate": 5000
}

Video state

GET /state

Retrieve whether the target is sending video and the current display resolution.

This path is not under /api. nginx proxies it to the video service after validating your session.

Requires operator access when user authentication is enabled.

Headers

• Cookie (required when users are configured): Session cookie.

Returns

On success, returns status code 200 with a JSON object. The exact shape depends on the streaming backend; resolution is typically nested under result.source:

Example: Retrieve video state

GET /state HTTP/1.1
Host: tinypilot
Cookie: session=...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": {
    "source": {
      "online": true,
      "resolution": {
        "width": 1920,
        "height": 1080
      }
    }
  }
}

Virtual media inventory

GET /api/massStorage/backingFiles

List disk images on the TinyPilot device and whether an image is currently mounted to the target.

Requires administrator access when user authentication is enabled.

Headers

• Cookie (required when users are configured): Session cookie.

Returns

On success, returns status code 200 with a JSON object containing:

Example: List virtual media

GET /api/massStorage/backingFiles HTTP/1.1
Host: tinypilot
Cookie: session=...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "backingFiles": [
    {
      "name": "proxmox-ve_6.3-1.iso",
      "mounted": false,
      "totalBytes": 812000000
    }
  ],
  "intermediateFiles": [],
  "mountMode": "FLASH_READ_ONLY"
}

Virtual media from URL

PUT /api/massStorage/backingFiles/<file_name>/fetchFromUrl

Download a disk image from a URL and store it on the TinyPilot device.

Requires administrator access when user authentication is enabled.

Headers

• Cookie (required when users are configured): Session cookie.
• Content-Type (required): Must be application/json.
• X-CSRFToken (required): CSRF token.

Request Body

Returns

• 200 on success with an empty JSON object.
• 400 if the URL is invalid or unreachable.
• 409 if a file with that name already exists.
• 507 if the device has insufficient storage.

Example: Download from URL

PUT /api/massStorage/backingFiles/debian-12.iso/fetchFromUrl HTTP/1.1
Host: tinypilot
Cookie: session=...
Content-Type: application/json
X-CSRFToken: ...

{
  "url": "https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-12.5.0-amd64-netinst.iso"
}

HTTP/1.1 200 OK
Content-Type: application/json

{}

Virtual media mount

PUT /api/massStorage/mount/<file_name>?mode=<mode>

Mount a disk image to the target computer as a virtual USB drive.

Requires administrator access when user authentication is enabled.

Headers

• Cookie (required when users are configured): Session cookie.
• X-CSRFToken (required): CSRF token.

Query Parameters

Returns

• 200 on success with an empty JSON object.
• 400 if the file name or mount mode is invalid.
• 500 if the mount operation fails.

Example: Mount an ISO

PUT /api/massStorage/mount/debian-12.iso?mode=CDROM HTTP/1.1
Host: tinypilot
Cookie: session=...
X-CSRFToken: ...

HTTP/1.1 200 OK
Content-Type: application/json

{}

Virtual media eject

PUT /api/massStorage/eject

Eject the currently mounted virtual media from the target computer.

Requires administrator access when user authentication is enabled.

Headers

• Cookie (required when users are configured): Session cookie.
• X-CSRFToken (required): CSRF token.

Returns

• 200 on success with an empty JSON object.
• 500 if the eject operation fails.

Example: Eject virtual media

PUT /api/massStorage/eject HTTP/1.1
Host: tinypilot
Cookie: session=...
X-CSRFToken: ...

HTTP/1.1 200 OK
Content-Type: application/json

{}

User scripts

User scripts must be installed on the device under /usr/bin/tinypilot-user-scripts/.

List scripts

GET /api/userScripts

List installed user scripts.

Requires operator access when user authentication is enabled.

Headers

• Cookie (required when users are configured): Session cookie.

Returns

On success, returns status code 200 with a JSON object containing a userScripts array of script names.

Example: List user scripts

GET /api/userScripts HTTP/1.1
Host: tinypilot
Cookie: session=...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "userScripts": [
    "atx-power-on",
    "atx-power-off"
  ]
}

Run script

POST /api/userScripts/<script_name>/run

Run a user script on the device. A 200 response means the script started, not that it finished.

Requires operator access when user authentication is enabled.

Headers

• Cookie (required when users are configured): Session cookie.
• X-CSRFToken (required): CSRF token.

Returns

• 200 on success with an empty JSON object.
• 400 if the script name is invalid.
• 500 if the script could not be started.

Example: Run a user script

POST /api/userScripts/atx-power-on/run HTTP/1.1
Host: tinypilot
Cookie: session=...
X-CSRFToken: ...

HTTP/1.1 200 OK
Content-Type: application/json

{}

Support

This reference is not covered by TinyPilot support. Endpoints may change or disappear in any release.

For keyboard, mouse, and screenshot control, use the TinyPilot REST API with an Automation License.