API overview
The Analog WakaTime Gateway exposes a versioned HTTP API under:
https://<gateway-host>/main/api/v1
Production clients typically use the public Analog gateway that backs analogwakatime.com. Self-hosted deployments use your own gateway base URL.
This documentation describes client-facing surfaces used by:
- IDE plugins (VS Code, JetBrains, compatible editors)
- the Desktop Agent
- the web app / dashboard (at a high level)
We intentionally do not publish every internal, administrative, billing-webhook, or privileged operations path here. Those routes exist for first-party services and are not part of the supported public integration surface.
If you are building a plugin or automation, stick to the endpoints documented in this section. Prefer device-flow or user API tokens issued from the product UI — never hard-code service credentials.
Conventions
| Topic | Detail |
|---|---|
| Protocol | HTTPS |
| Prefix | /main/api/v1 |
| Formats | JSON request/response bodies unless noted |
| Auth | Authorization: Bearer <token> on private routes |
| Errors | JSON error payloads with HTTP 4xx/5xx |
Interactive OpenAPI UI may be available on a deployment at /main/api/v1/docs/ for operators. Treat unpublished paths as unsupported.
Capability map
| Area | Who uses it | Doc page |
|---|---|---|
| Health / hello | Probes, smoke tests | Authentication & basics |
| Device authorization | IDE plugins, Desktop Agent | Authentication & basics |
| IDE activity sync | VS Code / JetBrains plugins | Activities |
| Desktop activity sync | Desktop Agent | Activities |
| Personal stats & profile reads | Dashboard / account tools | Stats & profile |
| Public badges & public charts | README badges, landing widgets | Public endpoints |
Authentication model (summary)
- User session token — obtained via website login or plugin device flow; sent as Bearer token.
- API token — long-lived token from the user profile; also sent as Bearer for plugins that prefer token paste.
- Device flow — plugin shows a user code; user confirms in the browser; plugin polls until a token is issued.
Password login and OAuth browser callbacks are used by the first-party web app. Plugin authors should use device flow or API tokens, not scrape website login forms.
Versioning
All documented routes live under /main/api/v1. Breaking changes are introduced with a new version prefix when required. Additive fields in JSON responses should be tolerated by clients.