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 (Requires port to be configured, 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.

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 (with per-app, per-tag, hourly, device, and music views)
  • Chart and calendar data
  • Sessions
  • Breakdowns
  • Tags and their stats
  • Goals and progress
  • Events
  • Devices
  • Media links
  • App stats and icons

View full endpoint list in the local API settings. It opens the complete 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, it is recommended to use ?icons=false.

Good to know

Section titled “Good to know”
  • GET only — nothing behind this API can modify your data.
  • 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.