Skip to content
Vetroscope Docs

Local API

The Local API serves your tracked data over HTTP on your own machine, so you can build whatever the app doesn’t do for you.

Enabling

Section titled “Enabling”

Settings → Local API → Enable local API. The panel shows everything a client needs:

  • Base URL — http://127.0.0.1:[PORT]/v1 (port defaults to 47823).
  • Token — every request needs Authorization: Bearer <token>. Show, copy, or Refresh it there — refreshing invalidates the old token everywhere it was used.
  • Allow writes — optional. Off by default. When on, clients can create, update, and delete notes and note folders (POST, PATCH, DELETE). Reads stay available either way.

First call:

Terminal window
curl -H "Authorization: Bearer <token>" \
  "http://127.0.0.1:47823/v1/report?period=today"

Local API endpoints

Section titled “Local API endpoints”
  • Current status
  • Reports (apps, tags, categories, hourly, devices, music, and more)
  • Chart and calendar data
  • Sessions
  • Breakdowns / projects
  • Tags and their stats
  • Categories (list and logged apps)
  • Goals and progress
  • Events
  • Notes and note folders
  • Devices
  • Media links
  • App stats and icons

View full endpoint list in Local API settings. It opens the complete OpenAPI JSON (/v1/openapi.json).

Two conventions worth knowing: most routes take ?period=today|week|month|YYYY-MM-DD (and ranges), and ?icons=false strips embedded icons for much smaller responses. If you don’t need icons, use ?icons=false.

Good to know

Section titled “Good to know”
  • The server binds to 127.0.0.1 only — never reachable from another device or the internet.
  • GET routes work whenever the API is on. Writes need Allow writes.
  • The API is up only while Vetroscope runs.
  • Treat the token like a password; Refresh it if it ends up somewhere it shouldn’t.

Prefer asking in plain language from an AI tool? That’s the MCP server.