Kova°
Devices Account

Manuals

Clicker API

A script never talks to the iPhone. It calls this panel. The panel tells the Clicker, and the Clicker moves the phone as a USB mouse and keyboard.

01

Get an API key

  1. Sign in at panel.kovaclicker.com.
  2. Open Account and click Create key.
  3. Copy the key. It starts with kova_sk_ and is shown once. The panel stores only a hash.
  4. Use the Device ID printed on the stick, for example KV-F6JMD1DP. The stick must be claimed on this same account.

Send the key on every request as the header X-API-Key. Do not put it in the URL. A revoked key answers 401.

02

What one call does

your script
  → HTTPS  https://panel.kovaclicker.com/api/v1
  → the relay checks the key and that you own this Device ID
  → the Clicker, already connected over Wi-Fi, sends USB HID to the iPhone

Base URL: https://panel.kovaclicker.com/api/v1. Device IDs in the path are case-insensitive. Taps, swipes, typing, and screenshots are free. Reading the screen, find-and-click, open-app, and each agent step cost one credit.

Check status before you tap. connected means the stick is online. streaming means Kova Viewer is broadcasting. Raw taps need only connected. Anything that looks at the screen needs both.

curl -s https://panel.kovaclicker.com/api/v1/devices \
  -H "X-API-Key: kova_sk_…"

curl -s https://panel.kovaclicker.com/api/v1/devices/KV-XXXXXXXX/status \
  -H "X-API-Key: kova_sk_…"

curl -s -X POST https://panel.kovaclicker.com/api/v1/devices/KV-XXXXXXXX/tap \
  -H "X-API-Key: kova_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"left":16383,"top":16383}'

A successful action answers {"success":true}.

03

Coordinates

Positions are HID units, 0 to 32767 on each axis. (0, 0) is the top left. (32767, 32767) is the bottom right. (16383, 16383) is the centre. These are the same numbers the Control page uses. The stick has an absolute pointer, so a coordinate lands on that point of the screen. There is no calibration step.

left is X. top is Y. Durations are milliseconds, capped at 5000.

04

Quick start with Python

Python 3.10 or newer. The client lives in this project at sdk/python. It is not on PyPI yet.

cd sdk/python
pip install -e .

Put a config.json next to your script, or export the same values. Environment variables win over the file.

{
  "API_KEY": "kova_sk_…",
  "DEVICE_ID": "KV-XXXXXXXX",
  "API_URL": "https://panel.kovaclicker.com/api/v1"
}
from kova import Clicker, DEVICE_ID

clicker = Clicker(DEVICE_ID)
clicker.tap((16383, 16383))
clicker.type("hello from a script")

type sends keystrokes into whatever text field is already focused on the phone. Click that field first, with tap or from the Control page.

05

Python library

Clicker(device_id) is one stick. Pass another Device ID to drive a second stick from the same script. The key still has to own it.

MethodWhat it does
tap((left, top), duration=100)Move to that point and click. duration is how long the button stays down, in milliseconds.
double_tap((left, top), duration=50, gap=100)Two taps. Both are timed on the stick, so the gap is not your network delay.
swipe((left, top), up=, down=, left=, right=, duration=300)Press at the start point and drag. Distances are HID units. Use one direction per call.
type(text)Type into the focused field. Up to 10,000 characters. Standard keyboard characters only. Emoji and most non-English letters are skipped by the stick.
key_combo(["Enter"])Named keys the stick actually sends: Enter, Backspace, Tab, Escape, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight. One to eight names. Other names are ignored by the stick.
release_all()Drop every held mouse button and key. Call this if a script dies mid-swipe.
screenshot()Latest JPEG from Kova Viewer, or None if the phone is not broadcasting. Free.
parse_screen()App name, the words on screen, and each element with a center you can pass to tap. Costs one credit. Returns None on failure.

parse_screen() returns app_name, screen_description, text, and elements. Each element has content, interactive, center as {"left", "top"}, and bbox as {"left", "top", "right", "bottom"}. Feed center straight into tap:

state = clicker.parse_screen()
if state:
    for el in state["elements"]:
        if "Settings" in el["content"]:
            c = el["center"]
            clicker.tap((c["left"], c["top"]))
            break

Agent(device_id).run("Open Notes and write a packing list") starts a plain-language task and prints each step until it finishes. Stopping the script with Ctrl-C cancels the task and releases the phone. Each step costs one credit. Kova Viewer must be broadcasting.

Agent methodWhat it does
execute(task)Queue the task. Returns the task id. HTTP 202.
get_status(task_id)Status, result, and the step log.
poll(task_id, interval=1)Print new steps until the task is completed, failed, or cancelled.
cancel(task_id)Stop the task.
run(task)execute then poll.

06

HTTP reference

All paths are under /api/v1. Action calls accept X-API-Key or a panel session token. The device list accepts an API key only. A key is limited to 600 requests per minute.

MethodPathBodyResult
GET/devicesdevices[] with id, name, connected, streaming, firmwareVersion. Free.
GET/devices/:id/statusconnected, streaming, absolutePointer, hidMax (32767). Free.
POST/devices/:id/tapleft, top, optional duration (default 100){"success":true}. Free.
POST/devices/:id/double-tapleft, top, optional duration (50) and gap (100)Free.
POST/devices/:id/movestart_left, start_top, end_left, end_top, is_pressed (true for a swipe), optional duration (300)Free.
POST/devices/:id/clickoptional button: left, right, or middle. Optional duration.Clicks wherever the pointer already is. Free.
POST/devices/:id/scrolldirection: up or down. Optional distance 1–1000 (default 300) and duration (500).Free.
POST/devices/:id/keyboard/typetext, 1–10,000 charactersTypes into the focused field. Free.
POST/devices/:id/keyboard/combocodes: 1–8 names. See the library table for names the stick sends.Free.
GET/devices/:id/screenshotJPEG body. Free. Viewer must be broadcasting.
POST/devices/:id/release-allRelease held buttons and keys. Free.
POST/devices/:id/releaseGive the device back now, so the panel or another script can take it. Free.

A swipe from the centre upward:

curl -s -X POST https://panel.kovaclicker.com/api/v1/devices/KV-XXXXXXXX/move \
  -H "X-API-Key: kova_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"start_left":16383,"start_top":20000,"end_left":16383,"end_top":8000,"is_pressed":true,"duration":300}'

07

Reading the screen

Hard-coded coordinates break when the phone model or an iOS update moves a button. These calls look at the Kova Viewer broadcast and return points in the same HID units as tap. The phone must be broadcasting. DRM video stays black. Each look costs one credit.

MethodPathBodyResult
POST/devices/:id/screen-stateapp_name, screen_description, text, elements[] with content, interactive, center, bbox.
POST/devices/:id/find-and-clickquery, what to tap, in wordssuccess, message, element.
POST/devices/:id/open-appapp_nameOpens the app through Spotlight.
POST/devices/:id/close-appApp switcher, swipe the front app away.
POST/devices/:id/swipe-backLeft-edge back gesture.
POST/devices/:id/homeHome indicator swipe.
curl -s -X POST https://panel.kovaclicker.com/api/v1/devices/KV-XXXXXXXX/find-and-click \
  -H "X-API-Key: kova_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"query":"Settings"}'

If AI is not enabled on the relay, these answers are 501 with vision_unavailable. Taps and typing still work.

08

Agent

One prompt, many steps. The agent looks, taps or types, and looks again. Same rules as screen reading: the stick online, Viewer broadcasting, credits on the account, and AI enabled on the relay. One task per device at a time. Opening Control and clicking the video takes the phone back and stops the task.

MethodPathBodyResult
POST/devices/:id/agent/runprompt, up to 2,000 characters202 and a task object with id and status.
GET/devices/:id/agent/:taskIdstatus is pending, running, completed, failed, or cancelled. events[] has step, action, result.
DELETE/devices/:id/agent/:taskIdStop the task.
curl -s -X POST https://panel.kovaclicker.com/api/v1/devices/KV-XXXXXXXX/agent/run \
  -H "X-API-Key: kova_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Open the Calculator and work out 25 times 4"}'

09

Errors

Failed actions use {"success":false,"error":"…","message":"…"}. Auth failures use {"error":"…"} only.

HTTPerrorMeaning
400invalid_requestMissing or out-of-range field. The message names it.
401No key, or the key is invalid or revoked.
402no_creditsA screen look or agent step needs a credit and the balance is empty.
404not_foundThat Device ID is not on this account.
409offlineThe Clicker is not connected. It needs Wi-Fi and power.
409busyThe panel or another script is already controlling this stick.
409video_agent_offlineKova Viewer is not broadcasting.
409not_streamingThe agent refused to start because it cannot see the screen.
409device_busyAn agent task is already running on this stick.
429This key is over 600 requests in the current minute. Retry-After says how long to wait.
501vision_unavailableScreen reading and the agent are turned off on this relay.
502vision_failedThe screen could not be read.
504snapshot_timeoutThe phone did not return a frame in time.

10

Rules