Tiiny API notes (unofficial)

Field notes on the network API of the Tiiny Pocket: every endpoint I've found, what was actually tested, recipes, quirks, and a tool to see what changed after a TiinyOS update.

These are my personal findings, from my own Tiiny, and a work in progress. I'll keep updating them as I learn more about the device and as new features turn up. They are not official documentation and may be wrong or out of date for your TiinyOS version.

Not affiliated with Tiiny. Everything here comes from calling my own device with its own API key, the specs it publishes, Tiiny's public docs and the TiinyOS desktop app. Behaviour can change with any update; each section says which version it was checked against. Corrections welcome (issues/PRs).

Contents

file	what
docs/API.md	the reference: services and ports, auth, system/power, models, inference (OpenAI, Anthropic, Ollama styles), model containers, the vault (/kb), connectors, apps, known quirks
docs/endpoints/gateway.md, kb.md	every endpoint the device's two published specs list, regenerated by the tool below
docs/RECIPES.md	copy-paste: power off, vault file flow, delete captured chats, use the Tiiny from Hermes / Cline / OpenAI SDKs
docs/MODELS.md	every model in the Tiiny Model Store: type, size, NPU share, context, what it can do
docs/PRIVACY.md	what the device keeps about your chats, and what you can delete through the API
tools/api_test.py	walk through the API and check each feature really works (chat, embeddings, OCR, images, voice, music, 3D); run one section or all
tools/api_compare.py	put api_test reports side by side (e.g. USB vs Wi-Fi, or before/after an update) and mark what differs
tools/model_list.py	regenerate docs/MODELS.md from your device's Model Store catalogue
tools/cli_compare.py	run the same tests through the Tiiny CLI and the direct API, side by side (plus tiiny bench vs the API's own speed)
tools/usb_download_test.py	check whether the Tiiny can download a model over the USB cable with its Wi-Fi off (turns Wi-Fi back on afterwards)
tools/api_snapshot.py	fetch the device's specs, list added/removed/changed endpoints since last time, regenerate the endpoint lists, probe the read-only routes

See also: AntAttack's documentation map, which covers where Tiiny's own documentation lives and how API-call logging works.

Checking your own device

export TIINY_URL=http://192.168.1.50 TIINY_KEY=your-api-key   # TiinyOS → Settings → API Key
python tools/api_snapshot.py            # first run saves a baseline in snapshots/ (not committed)
python tools/api_snapshot.py --check    # later: what changed?

Something not working? Test just that part, or everything:

python tools/api_test.py ocr             # one section: info chat embeddings ocr image audio music 3d
python tools/api_test.py                 # full run (loads ~10 models in turn; 20-40 minutes)
python tools/api_test.py --list          # every check and the model it uses
python tools/api_test.py --via usb       # label the run; then --via wifi, and compare:
python tools/api_compare.py snapshots/api-test-*/report.json
python tools/cli_compare.py              # CLI vs API (needs the Tiiny CLI, signed in)
python tools/usb_download_test.py        # over the USB cable: download with Wi-Fi off?

It loads the models it needs (and puts back what was loaded before), checks each answer against known inputs in tools/assets/, and prints PASS/FAIL/SKIP per check; a report and the outputs land in snapshots/. Don't use the Tiiny for anything else while it runs.

Python 3.10+, standard library only. The key is only sent to the address you give.

Ground rules for this repo

• Only things anyone can check with their own device and API key. No root/firmware internals, nobody's addresses, keys or data, and security issues go to Tiiny privately first.
• Mark what was tested versus only seen in a spec or the docs.

License: Apache-2.0.