Skip to main content
Version: 1.0.0

WhatPulse Client API

The WhatPulse Client API is a lightweight JSON REST API embedded in the WhatPulse desktop application. Use it to retrieve real-time activity statistics, trigger actions like pulsing, and integrate WhatPulse data with your own tools and dashboards.

Getting Started​

The Client API runs as a local HTTP server on your machine. It is disabled by default and must be enabled in the WhatPulse client settings under Settings > Client API.

Once enabled, the API is available at:

http://localhost:3490

The port is configurable in the client settings.

Access Control​

The Client API does not use token-based authentication. Instead, access is controlled by an IP allowlist configured in the client settings. By default, only 127.0.0.1 (localhost) is allowed.

If a request comes from a non-allowed IP address, the API returns a 401 response:

{ "error": "This IP address is not allowed to connect. Please check the allowed IPs settings." }

Response Format​

All responses are JSON. Many statistics fields include both a raw numeric value and a _formatted string with locale-appropriate formatting:

{
  "keys": 512752,
  "keys_formatted": "512,752",
  "download": 512752569,
  "download_formatted": "489.00 MB"
}

Status Codes​

  • 200 — Successful request
  • 400 — Invalid request parameters
  • 401 — IP address not in the allowlist
  • 404 — Endpoint not found
  • 405 — HTTP method not allowed