TinyPilot REST API

Overview

The TinyPilot REST API enables clients to create custom integrations for their TinyPilot device.

Clients can use the REST API to interact with their TinyPilot device independently of TinyPilot's native web interface.

Requirements

The TinyPilot REST API requires a TinyPilot Automation License for each API-accessible device.

Activation

To activate your Automation License key and enable the REST API, run the following commands:

LICENSE_KEY="YOUR-LICENSE-KEY"
sudo su tinypilot bash -c \
  "/opt/tinypilot/scripts/activate-license ${LICENSE_KEY}"

Endpoints

• Authentication Token
• Screenshot
• Keystroke
• Mouse Event
• Paste

Authentication token

POST /api/v1/auth

Retrieve an API token for interacting with the REST API.

Tokens remain valid until the next restart of the TinyPilot server process.

Clients can request multiple tokens. Requesting a new token does not invalidate any previous tokens.

Note: The authentication token API does not support password-based authentication. When TinyPilot is configured to require a username and password for access, the REST API is inaccessible. TinyPilot requires an authentication token even in passwordless mode to prevent CSRF attacks.

Headers

No additional headers are required, but the request must not include an Origin header.

Returns

On success, returns status code 200 with a HTTP body of a TinyPilot API token as a JSON object. The object contains a single field, token that contains a string value.

Example: Retrieve API token

POST /api/v1/auth HTTP/1.1
Host: tinypilot

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

{
  "token": "4e77f593-a8e0-4262-8a32-911110087060"
}

Screenshot

GET /api/v1/screenshot

Retrieve the current image on the target computer's display output.

Headers

• Authorization (required): A TinyPilot API token obtained from /api/v1/auth in the format Bearer [TOKEN]

Returns

On success, returns status code 200 with a HTTP body of the current image on TinyPilot's remote screen as a JPEG image.

If TinyPilot is not receiving video input from the target computer, returns status code 204 and an empty response body.

Example: Retrieve current screenshot

GET /api/v1/screenshot HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 13845

[binary JPEG data]

Keystroke

POST /api/v1/keystroke

Generate a keystroke on the target computer.

Headers

• Authorization (required): A TinyPilot API token obtained from /api/v1/auth in the format Bearer [TOKEN]
• Content-Type (required): Must be application/json

Request Body

A JSON object representing a keystroke:

Returns

• 200 on success with an empty response body.
• 400 if the client request was malformed.
• 500 if the server failed to forward the keystroke to the target computer.

Example: Type text

The following request sequences causes TinyPilot to type Hi!<Enter> on a target system configured for an en-US keyboard.

POST /api/v1/keystroke HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "code": "KeyH",
  "shiftLeft": true
}

HTTP/1.1 200 OK

POST /api/v1/keystroke HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "code": "KeyI"
}

HTTP/1.1 200 OK

POST /api/v1/keystroke HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "code": "Digit1",
  "shiftRight": true
}

HTTP/1.1 200 OK

POST /api/v1/keystroke HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "code": "Enter"
}

HTTP/1.1 200 OK

Example: Send Ctrl+Alt+Del

The following exchange shows the caller sending a Ctrl+Alt+Del key sequence to the remote computer:

POST /api/v1/keystroke HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "code": "Delete",
  "ctrlLeft": true,
  "altRight": true
}

HTTP/1.1 200 OK

Example: Keystroke forwarding failure

The following exchange shows the caller sending a keystroke to a TinyPilot device that is disconnected from the target computer:

POST /api/v1/keystroke HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "code": "KeyA"
}

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=utf-8

Failed to forward keystroke: could not access /dev/hidg0 (is
cable connected?)

Mouse Event

POST /api/v1/mouseEvent

Generate a mouse event on the target computer to move the mouse cursor and/or to issue mouse clicks.

Headers

• Authorization (required): A TinyPilot API token obtained from /api/v1/auth in the format Bearer [TOKEN]
• Content-Type (required): Must be application/json

Request Body

A JSON object representing a mouse event:

Returns

• 200 on success with an empty response body.
• 400 if the client request was malformed.
• 500 if the server failed to forward the mouse event to the target computer.

Example: Move mouse

The following sequence of requests moves the mouse to the 4 corners of the screen on the target system, starting in the top-left corner and moving clock-wise:

POST /api/v1/mouseEvent HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "buttons": 0,
  "relativeX": 0.0,
  "relativeY": 0.0,
  "verticalWheelDelta": 0,
  "horizontalWheelDelta": 0
}

HTTP/1.1 200 OK

POST /api/v1/mouseEvent HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "buttons": 0,
  "relativeX": 1.0,
  "relativeY": 0.0,
  "verticalWheelDelta": 0,
  "horizontalWheelDelta": 0
}

HTTP/1.1 200 OK

POST /api/v1/mouseEvent HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "buttons": 0,
  "relativeX": 1.0,
  "relativeY": 1.0,
  "verticalWheelDelta": 0,
  "horizontalWheelDelta": 0
}

HTTP/1.1 200 OK

POST /api/v1/mouseEvent HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "buttons": 0,
  "relativeX": 0.0,
  "relativeY": 1.0,
  "verticalWheelDelta": 0,
  "horizontalWheelDelta": 0
}

HTTP/1.1 200 OK

Example: Left-click mouse

The following exchange performs a left-click of the mouse in the center of the screen on the target system:

POST /api/v1/mouseEvent HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "buttons": 1,
  "relativeX": 0.5,
  "relativeY": 0.5,
  "verticalWheelDelta": 0,
  "horizontalWheelDelta": 0
}

HTTP/1.1 200 OK

Example: Right-click mouse

The following exchange performs a right-click of the mouse in the center of the screen on the target system:

POST /api/v1/mouseEvent HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "buttons": 2,
  "relativeX": 0.5,
  "relativeY": 0.5,
  "verticalWheelDelta": 0,
  "horizontalWheelDelta": 0
}

HTTP/1.1 200 OK

Example: Mouse event forwarding failure

The following exchange shows the caller sending a mouse event to a TinyPilot device that is disconnected from the target computer:

POST /api/v1/mouseEvent HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "buttons": 0,
  "relativeX": 0.5,
  "relativeY": 0.5,
  "verticalWheelDelta": 0,
  "horizontalWheelDelta": 0
}

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=utf-8

Failed to forward mouse event: could not access /dev/hidg1 (is cable connected?)

Paste

POST /api/v1/paste

Paste text onto the target computer by sending the corresponding keystrokes.

The API sends keystrokes in a "fire and forget" manner, so a successful response does not guarantee that all keystrokes have reached the target computer by the time you receive the response. As a rule of thumb, wait about 100ms per character before assuming the pasted text has arrived.

Headers

• Authorization (required): A TinyPilot API token obtained from /api/v1/auth in the format Bearer [TOKEN]
• Content-Type (required): Must be application/json

A JSON object representing the text to paste:

Returns

• 200 on success with an empty response body.
• 400 if the client request was malformed or contains characters that cannot be converted to keystrokes for the specified language.

Example: Paste text

POST /api/v1/paste HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "text": "Hello, World!",
  "language": "en-US"
}

HTTP/1.1 200 OK

Example: Unsupported character

The following exchange shows the caller attempting to paste a character that cannot be represented as a keystroke for the specified language:

POST /api/v1/paste HTTP/1.1
Host: tinypilot
Authorization: Bearer 4e77f593-a8e0-4262-8a32-911110087060
Content-Type: application/json

{
  "text": "こんにちは",
  "language": "en-US"
}

HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8

These characters are not supported: 'こ', 'ん', 'に', 'ち', 'は'

Sample script

The following is a Python script that exercises all the functionality of the TinyPilot REST API:

#!/usr/bin/env python3
"""Exercise all the functionality of the TinyPilot REST API.

This script performs the following actions:

1. Fetch an auth token.
2. Open a terminal on the target machine by pressing `Ctrl` + `Alt` + `T`.
3. Paste `echo "Hello, World!"` and then press the `Enter` key on the target machine.
4. Open Firefox.
5. Navigate to https://paint.js.org.
6. Draw a rectangle in paint.
7. Save a screenshot of the target machine display.
"""

import json
import ssl
import sys
import time
import urllib.error
import urllib.request

BASE_URL = 'https://tinypilot/api/v1'

# Seconds to wait after each keystroke to allow it to finish delivering
# before sending subsequent input.
SECONDS_PER_KEYSTROKE = 0.1

# Disable SSL verification
# This is not necessary if you install your TinyPilot device's CA
# certificate:
# https://tinypilotkvm.com/faq/fix-browser-privacy-errors
# Example:
#   ctx = ssl.create_default_context(cafile='/path/to/tinypilot/ca.crt')
ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE


def main():
    # 1. Fetch an auth token.
    print('Fetching auth token...', end='', flush=True)
    req = urllib.request.Request(f'{BASE_URL}/auth', method='POST')
    try:
        with urllib.request.urlopen(req, context=ctx) as response:
            response_text = response.read().decode()
            response_data = json.loads(response_text)
            token = response_data['token']
    except urllib.error.HTTPError as e:
        print(f'HTTP Error {e.status}: {e.read().decode()}', file=sys.stderr)
        return
    print(' done.')

    # 2. Open a terminal by pressing `Ctrl` + `Alt` + `T`.
    print('Opening terminal...', end='', flush=True)
    payload = {
        'code': 'KeyT',
        'ctrlLeft': True,
        'altLeft': True,
    }
    req = urllib.request.Request(url=f'{BASE_URL}/keystroke',
                                 method='POST',
                                 headers={
                                     'Authorization': f'Bearer {token}',
                                     'Content-Type': 'application/json'
                                 },
                                 data=json.dumps(payload).encode())
    try:
        with urllib.request.urlopen(req, context=ctx) as response:
            pass
    except urllib.error.HTTPError as e:
        print(f'HTTP Error {e.status}: {e.read().decode()}', file=sys.stderr)
        return
    time.sleep(SECONDS_PER_KEYSTROKE)
    print(' done.')

    print('Waiting 3s for the terminal to open...', end='', flush=True)
    time.sleep(3)
    print(' done.')

    # 3. Paste `echo "Hello, World!"` then press `Enter`.
    print('Pasting text...', end='', flush=True)
    text = 'echo "Hello, World!"'
    payload = {
        'text': text,
        'language': 'en-US',
    }
    req = urllib.request.Request(url=f'{BASE_URL}/paste',
                                 method='POST',
                                 headers={
                                     'Authorization': f'Bearer {token}',
                                     'Content-Type': 'application/json'
                                 },
                                 data=json.dumps(payload).encode())
    try:
        with urllib.request.urlopen(req, context=ctx) as response:
            pass
    except urllib.error.HTTPError as e:
        print(f'HTTP Error {e.status}: {e.read().decode()}', file=sys.stderr)
        return
    time.sleep(len(text) * SECONDS_PER_KEYSTROKE)
    payload = {'code': 'Enter'}
    req = urllib.request.Request(url=f'{BASE_URL}/keystroke',
                                 method='POST',
                                 headers={
                                     'Authorization': f'Bearer {token}',
                                     'Content-Type': 'application/json'
                                 },
                                 data=json.dumps(payload).encode())
    try:
        with urllib.request.urlopen(req, context=ctx) as response:
            pass
    except urllib.error.HTTPError as e:
        print(f'HTTP Error {e.status}: {e.read().decode()}', file=sys.stderr)
        return
    time.sleep(SECONDS_PER_KEYSTROKE)
    print(' done.')

    print('Waiting 1s for command to execute...', end='', flush=True)
    time.sleep(1)
    print(' done.')

    # 4. Open Firefox.
    print('Opening Firefox...', end='', flush=True)
    text = 'firefox'
    payload = {
        'text': text,
        'language': 'en-US',
    }
    req = urllib.request.Request(url=f'{BASE_URL}/paste',
                                 method='POST',
                                 headers={
                                     'Authorization': f'Bearer {token}',
                                     'Content-Type': 'application/json'
                                 },
                                 data=json.dumps(payload).encode())
    try:
        with urllib.request.urlopen(req, context=ctx) as response:
            pass
    except urllib.error.HTTPError as e:
        print(f'HTTP Error {e.status}: {e.read().decode()}', file=sys.stderr)
        return
    time.sleep(len(text) * SECONDS_PER_KEYSTROKE)
    payload = {'code': 'Enter'}
    req = urllib.request.Request(url=f'{BASE_URL}/keystroke',
                                 method='POST',
                                 headers={
                                     'Authorization': f'Bearer {token}',
                                     'Content-Type': 'application/json'
                                 },
                                 data=json.dumps(payload).encode())
    try:
        with urllib.request.urlopen(req, context=ctx) as response:
            pass
    except urllib.error.HTTPError as e:
        print(f'HTTP Error {e.status}: {e.read().decode()}', file=sys.stderr)
        return
    time.sleep(SECONDS_PER_KEYSTROKE)
    print(' done.')

    print('Waiting 3s for command to execute...', end='', flush=True)
    time.sleep(3)
    print(' done.')

    # 5. Navigate to paint.js.org.
    print('Navigating to paint.js.org...', end='', flush=True)
    payload = {
        'code': 'KeyL',
        'ctrlLeft': True,
    }
    req = urllib.request.Request(url=f'{BASE_URL}/keystroke',
                                 method='POST',
                                 headers={
                                     'Authorization': f'Bearer {token}',
                                     'Content-Type': 'application/json'
                                 },
                                 data=json.dumps(payload).encode())
    try:
        with urllib.request.urlopen(req, context=ctx) as response:
            pass
    except urllib.error.HTTPError as e:
        print(f'HTTP Error {e.status}: {e.read().decode()}', file=sys.stderr)
        return
    time.sleep(SECONDS_PER_KEYSTROKE)
    text = 'https://paint.js.org/'
    payload = {
        'text': text,
        'language': 'en-US',
    }
    req = urllib.request.Request(url=f'{BASE_URL}/paste',
                                 method='POST',
                                 headers={
                                     'Authorization': f'Bearer {token}',
                                     'Content-Type': 'application/json'
                                 },
                                 data=json.dumps(payload).encode())
    try:
        with urllib.request.urlopen(req, context=ctx) as response:
            pass
    except urllib.error.HTTPError as e:
        print(f'HTTP Error {e.status}: {e.read().decode()}', file=sys.stderr)
        return
    time.sleep(len(text) * SECONDS_PER_KEYSTROKE)
    payload = {'code': 'Enter'}
    req = urllib.request.Request(url=f'{BASE_URL}/keystroke',
                                 method='POST',
                                 headers={
                                     'Authorization': f'Bearer {token}',
                                     'Content-Type': 'application/json'
                                 },
                                 data=json.dumps(payload).encode())
    try:
        with urllib.request.urlopen(req, context=ctx) as response:
            pass
    except urllib.error.HTTPError as e:
        print(f'HTTP Error {e.status}: {e.read().decode()}', file=sys.stderr)
        return
    time.sleep(SECONDS_PER_KEYSTROKE)
    print(' done.')

    print('Waiting 5s for command to execute...', end='', flush=True)
    time.sleep(5)
    print(' done.')

    # 6. Draw a rectangle in paint.
    print('Drawing rectangle...', end='', flush=True)
    payloads = [
        {
            'relativeX': 0.25,
            'relativeY': 0.25,
            'buttons': 0,
            'verticalWheelDelta': 0,
            'horizontalWheelDelta': 0,
        },
        {
            'relativeX': 0.25,
            'relativeY': 0.25,
            'buttons': 1,
            'verticalWheelDelta': 0,
            'horizontalWheelDelta': 0,
        },
        {
            'relativeX': 0.75,
            'relativeY': 0.25,
            'buttons': 1,
            'verticalWheelDelta': 0,
            'horizontalWheelDelta': 0,
        },
        {
            'relativeX': 0.75,
            'relativeY': 0.75,
            'buttons': 1,
            'verticalWheelDelta': 0,
            'horizontalWheelDelta': 0,
        },
        {
            'relativeX': 0.25,
            'relativeY': 0.75,
            'buttons': 1,
            'verticalWheelDelta': 0,
            'horizontalWheelDelta': 0,
        },
        {
            'relativeX': 0.25,
            'relativeY': 0.25,
            'buttons': 1,
            'verticalWheelDelta': 0,
            'horizontalWheelDelta': 0,
        },
        {
            'relativeX': 0.25,
            'relativeY': 0.25,
            'buttons': 0,
            'verticalWheelDelta': 0,
            'horizontalWheelDelta': 0,
        },
    ]
    for payload in payloads:
        req = urllib.request.Request(url=f'{BASE_URL}/mouseEvent',
                                     method='POST',
                                     headers={
                                         'Authorization': f'Bearer {token}',
                                         'Content-Type': 'application/json'
                                     },
                                     data=json.dumps(payload).encode())
        try:
            with urllib.request.urlopen(req, context=ctx) as response:
                pass
        except urllib.error.HTTPError as e:
            print(f'HTTP Error {e.status}: {e.read().decode()}',
                  file=sys.stderr)
            return
    print(' done.')

    print('Waiting 1s for command to execute...', end='', flush=True)
    time.sleep(1)
    print(' done.')

    # 7. Save a screenshot of the display.
    print('Taking a screenshot...', end='', flush=True)
    req = urllib.request.Request(url=f'{BASE_URL}/screenshot',
                                 method='GET',
                                 headers={'Authorization': f'Bearer {token}'})
    try:
        with urllib.request.urlopen(req, context=ctx) as response:
            with open('screenshot.jpeg', 'wb') as f:
                f.write(response.read())
    except urllib.error.HTTPError as e:
        print(f'HTTP Error {e.status}: {e.read().decode()}', file=sys.stderr)
        return
    print(' done.')


if __name__ == '__main__':
    main()