# What Is the /heartbeat API Endpoint in PicList?

> Discover the purpose of the PicList /heartbeat API endpoint. This health check confirms the local server is alive, enabling the frontend to detect and recover from unresponsive states.

- Repository: [Kuingsmile/piclist](https://github.com/kuingsmile/piclist)
- Tags: api-reference
- Published: 2026-03-05

---

**The `/heartbeat` endpoint acts as a lightweight health check that returns a simple JSON payload to confirm the PicList local server is alive, allowing the Electron frontend to detect unresponsive states and trigger recovery actions.**

The PicList image upload tool runs a tiny local HTTP server to bridge the Electron frontend with system-level operations. According to the [kuingsmile/piclist](https://github.com/kuingsmile/piclist) source code, the `/heartbeat` route provides a critical keep-alive mechanism that enables the UI to verify server responsiveness without consuming significant resources.

## How the /heartbeat Endpoint Works

The endpoint serves three primary responsibilities within PicList's architecture:

- **Keep-alive verification** – The UI periodically pings `/heartbeat` to confirm the local server process hasn't crashed or entered a zombie state.
- **Health status reporting** – It returns a minimal JSON response that the renderer process evaluates to decide whether to retry requests, restart the server, or display connection warnings.
- **Zero-overhead design** – No authentication requirements, empty request bodies, and fast `200 OK` responses make the endpoint suitable for polling every few seconds.

## Implementation in the Source Code

### Route Registration in routerManager.ts

The endpoint definition lives in [`src/main/server/routerManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/routerManager.ts), where the application registers the route using the shared `Router` instance:

```typescript
// src/main/server/routerManager.ts
import router from './router'

router.any('/heartbeat', (req, res) => {
  // Simply answer that the service is alive
  res.json({ success: true })
})

```

### Router Configuration in router.ts

The `any` method used above is defined in [`src/main/server/router.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/router.ts). This method registers the handler for both **GET** and **POST** HTTP verbs, ensuring the frontend can call the endpoint regardless of its specific HTTP client configuration.

### Server Initialization in index.ts

The actual HTTP server that listens for these requests starts in [`src/main/server/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/index.ts). This file bootstraps the Express-like server that exposes the `/heartbeat` endpoint alongside other internal API routes.

## Practical Usage Examples

### Polling with fetch

From the renderer process or any frontend script, you can implement periodic health monitoring using the native `fetch` API:

```typescript
// Example: periodic health check
function pingServer() {
  fetch('http://127.0.0.1:12345/heartbeat')
    .then(r => r.json())
    .then(data => {
      if (!data.success) {
        console.warn('PicList server heartbeat failed')
      }
    })
    .catch(err => console.error('Heartbeat error', err))
}

// Call every 5 seconds
setInterval(pingServer, 5000)

```

### Using axios for Health Checks

If your integration prefers a library approach, `axios` provides cleaner async/await syntax:

```typescript
import axios from 'axios'

async function checkHeartbeat() {
  try {
    const { data } = await axios.get('http://127.0.0.1:12345/heartbeat')
    console.log('Server OK:', data)
  } catch (e) {
    console.error('Heartbeat failed', e)
  }
}

```

## Summary

- The `/heartbeat` endpoint in PicList returns `{ success: true }` to signal that the local server is operational.
- It is registered in [`src/main/server/routerManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/routerManager.ts) using `router.any()`, supporting both GET and POST requests.
- The implementation prioritizes minimal overhead, making it safe to poll every few seconds from the Electron frontend.
- Source files [`src/main/server/router.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/router.ts) and [`src/main/server/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/index.ts) provide the routing logic and server initialization respectively.

## Frequently Asked Questions

### What response does the /heartbeat endpoint return?

The endpoint returns a JSON object with a `success` boolean set to `true`. According to the implementation in [`src/main/server/routerManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/routerManager.ts), the response is generated via `res.json({ success: true })`, indicating the server process is alive and capable of handling requests.

### Which HTTP methods does the /heartbeat endpoint support?

The endpoint accepts both **GET** and **POST** requests. The route registration uses `router.any('/heartbeat', ...)`, defined in [`src/main/server/router.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/router.ts), which attaches the handler to multiple HTTP verbs simultaneously.

### Where is the /heartbeat route defined in the PicList codebase?

The route handler is registered in [`src/main/server/routerManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/routerManager.ts). The underlying `Router` class that provides the `any` method is defined in [`src/main/server/router.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/router.ts), while the server startup logic resides in [`src/main/server/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/index.ts).

### Why does PicList use a simple heartbeat instead of WebSockets?

The heartbeat approach minimizes complexity and resource usage. A stateless HTTP call to `/heartbeat` requires no persistent connection management, works reliably through corporate proxies, and provides sufficient latency detection for detecting a crashed local server process.