API overview
The Analog WakaTime Gateway exposes the production API under:
https://api.testingmyproject.space/main/api/v1
Self-hosted deployments replace the hostname while keeping the /main/api/v1 prefix.
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 | session JWT or personal analog-wakatime_live_... API token |
| 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 |
| Generated clients | Python and Go | Python SDK, Go SDK |
Authentication model (summary)
- User session token — obtained via website login or plugin device flow; sent as Bearer token.
- API token — independently revocable
analog-wakatime_live_...token; also sent as Bearer and recommended for scripts and server-side integrations. - 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.
SDK organization
The OpenAPI contract is shared by every generated client, but installation and code examples are maintained per language:
- Python SDK — asynchronous
httpxclient, available now - Go SDK — generated typed Go client, available now
Each language page documents the method names produced by its current generated package without mixing language-specific code into the HTTP reference.
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.