Unofficial Tapo REST Api

This program exposes a REST API to control your Tapo devices (light bulbs, strips, plugs, etc.). It is NOT affiliated in any way with the Tapo or TP-Link brands and is only made as a best-effort for personal use.

It is based on the unofficial Tapo API.

If you have any issue with this program, please open an issue!

Usage

You can either use a prebuilt binary from the latest release and copy it to a folder in your PATH, or use the docker image.

Start by creating a JSON config file (anywhere) with the following structure:

{
    "tapo_credentials": {
        "email": "<your Tapo account's email address>",
        "password": "<your Tapo account's password>"
    },
    "server_password": "<whatever you want, must be unguessable>",
    "devices": [
        {
            "name": "living-room-bulb",
            "device_type": "L530",
            "ip_addr": "<ip address of the device>"
        },
        {
            "name": "kitchen-bulb",
            "device_type": "L530",
            "ip_addr": "<ip address of the device>"
        }
    ]
}

For devices, the name field can be set to whatever name you want, while device_type can be any of:

• L510, L520, L610 (light bulbs)
• L530, L535, L630 (light bulbs with customizable colors)
• L900 (RGB light strips)
• L920, L930 (RGB light strips with individually colored segments)
• P100, P105 (smart plugs)
• P110, P110M, P115 (smart plugs with energy monitoring)
• P300, P304, P304M, P316 (power strips)

You can then run the server with:

docker run -it -v ./path-to-your-config.json:/app/devices.json -p 8000:80 clementnerma/tapo-rest

This will run the server on port 8000 (you can chose any port you like) and will require clients to use the potatoes password to log in.

The prebuilt binary works the same, but requires the additional --port (-p) flag.

Please note though that the server is not using SSL certificates (only plain HTTP/1 and HTTP/2), so you absolutely need to use a proxy (such as Caddy) if you don't want this secret password to appear in plain text on your network.

Before exposing the REST API, the server starts by connecting to all the devices specicified in your config file, to ensure they are reachable and caching the authentication results. Unreachable devices won't prevent the server from starting ; rather, when trying to communicate with them, a new connection will try to be established in real time.

Client usage

Clients call the POST /login route with a body of { "password": "potatoes" }. This returns a raw string, which is the session ID.

curl -i -X POST -H 'Content-Type: application/json' --data '{ "password": "potatoes" }' http://localhost:8000/login

All subsequent calls to the API must include an Authorization header containing the session ID (Authorization: Bearer <session ID>). Sessions are preserved after server restart.

You can then access all your devices through the /actions routes. Each route takes a ?device=<name> query parameter to know which device you are trying to interact with. The <name> is the same as the one you provided in your config file.

curl -i -X GET -H 'Authorization: Bearer <your session ID>' 'http://localhost:8000/actions/l530/on?device=living-room-bulb'

You can find the list of all available actions by checking /actions, and the list of all configured devices on /devices.

Query parameters

Some routes (such as get-hourly-usage) require timestamps. These must be provided in RFC 3339 format (e.g. 2023-12-31).

Session timeout

Once connected to a Tapo device, a session is maintained between the server and the device. But Tapo devices set an expiration time, which means the session will eventually expire.

If this happens, you can hit the /refresh-session?device=... route to refresh the session.

Live-reloading configuration

You can live-reload the configuration file without restarting the server, by using POST on /reload-config (bearer token is required):

curl -i -X POST -H 'Authorization: Bearer <your session ID>' 'http://localhost:8000/reload-config'

Existing devices will be connected to again.

Cinammon applet

@smiklosovic published a Cinnamon control applet.

This applet is entirely done by him, only using tapo-rest as the underlying server.