# PicList API Endpoints: Complete Guide to the Web Server Interface

> Explore PicList API endpoints for its web server interface. Learn about remote file uploads, deletion, and health monitoring with this comprehensive guide.

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

---

**PicList exposes five main HTTP endpoints—GET /, GET /upload, POST /upload, POST /delete, and ANY /heartbeat—that enable remote file uploads, clipboard handling, deletion, and health monitoring through a lightweight embedded web server.**

PicList, an open-source image upload tool maintained by `kuingsmile/piclist`, includes a built-in HTTP server for remote uploading. Understanding the PicList API endpoints is essential for developers integrating automated upload workflows or building custom clients. This guide examines the server architecture, details each endpoint's payload structure, and provides runnable code examples derived directly from the source.

## PicList Web Server Architecture

The web server implementation resides in `src/main/server/` and follows a minimal, custom-routing pattern rather than relying on heavy frameworks.

**Router Implementation**

The core routing logic lives in [`src/main/server/router.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/router.ts). This file exports a simple router that stores handlers in a native JavaScript `Map` keyed by the combination of URL path and HTTP method. This design allows constant-time lookup when dispatching incoming requests.

**Route Registration**

All endpoint handlers are registered in [`src/main/server/routerManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/routerManager.ts). This module imports the router instance and binds specific functions to each path and method pair. It also imports utility functions from [`src/main/server/utils.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/utils.ts) (specifically `handleResponse`) to standardize JSON output and HTTP status codes.

**Server Bootstrap**

The entry point in [`src/main/server/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/index.ts) creates the HTTP server, listens on the configured port, and delegates incoming requests to `router.getHandler`. The server integrates with PicList's encryption layer via [`src/main/utils/aesHelper.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/utils/aesHelper.ts) for secure payload transmission.

## Main PicList API Endpoints

The server exposes five primary endpoints covering documentation, upload operations, deletion, and health checks.

### GET / and GET /upload — API Documentation

Both the root path `/` and `/upload` serve an HTML-rendered version of the API documentation.

- **Handler Location:** `responseForGet` function in [`src/main/server/routerManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/routerManager.ts)
- **Content Source:** Markdown source provided by [`src/main/server/apiDoc.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/apiDoc.ts)
- **Purpose:** Provides a human-readable reference for the API without requiring external documentation

### POST /upload — File and Clipboard Uploads

The `/upload` endpoint accepts multipart form data and supports two distinct upload modes.

**Payload Shapes:**

1. **File List Upload:** Include a `list` field containing a JSON array of absolute file paths. PicList uploads each file sequentially.
2. **Clipboard Upload:** Submit an empty `list` (or omit it). PicList reads the current clipboard content and uploads it as an image.

**Handler Details:**

- **Location:** Inline async handler in [`src/main/server/routerManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/routerManager.ts)
- **Core Dependencies:** 
  - [`src/main/apis/app/uploader/apis.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/uploader/apis.ts) provides `uploadChoosedFiles` and `uploadClipboardFiles`
  - [`src/main/apis/app/window/windowManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/window/windowManager.ts) supplies a window reference required for file-selection dialogs
- **Response:** Returns encrypted upload results using [`aesHelper.ts`](https://github.com/kuingsmile/piclist/blob/main/aesHelper.ts). Results include original URLs and optional shortened URLs if configured.

### POST /delete — Remove Uploaded Files

The `/delete` endpoint handles secure deletion of previously uploaded assets.

**Payload Structure:**

Submit a `list` field containing an array of encrypted delete-task objects. Each object typically includes properties like `isEncrypted` and `EncryptedData` that the server decrypts using [`src/main/utils/aesHelper.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/utils/aesHelper.ts).

**Handler Details:**

- **Location:** Inline async handler in [`src/main/server/routerManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/routerManager.ts)
- **Process:** Decrypts each task object, invokes the internal PicList delete APIs, and aggregates results
- **Response:** Returns a JSON summary indicating success or failure for each deletion task

### ANY /heartbeat — Health Check

The `/heartbeat` endpoint provides a simple liveness probe suitable for monitoring systems and load balancers.

- **Method Support:** Accepts any HTTP method (GET, POST, etc.)
- **Response:** Always returns HTTP 200 with JSON body `{ success: true, result: 'alive' }`
- **Handler Location:** Inline async handler in [`src/main/server/routerManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/routerManager.ts)

## How to Use PicList API Endpoints with Code Examples

The following examples demonstrate interacting with the PicList web server using Node.js and `node-fetch`. Replace `PORT` with your configured PicList server port (default is typically 36677).

### Uploading Clipboard Content

To upload the current clipboard image without specifying file paths, send an empty form body:

```typescript
import fetch from 'node-fetch';
import FormData from 'form-data';

const url = 'http://localhost:PORT/upload';
const form = new FormData();

// Empty list triggers clipboard upload
await fetch(url, {
  method: 'POST',
  body: form,
})
  .then(res => res.json())
  .then(data => console.log('Upload result:', data));

```

### Uploading Specific Files

To upload a predefined list of local files, include the `list` parameter as a JSON array:

```typescript
import fetch from 'node-fetch';
import FormData from 'form-data';

const url = 'http://localhost:PORT/upload';
const form = new FormData();

// Specify absolute paths to files
const fileList = ['/path/to/image1.png', '/path/to/image2.jpg'];
form.append('list', JSON.stringify(fileList));

await fetch(url, { method: 'POST', body: form })
  .then(res => res.json())
  .then(data => console.log('Upload result:', data));

```

### Deleting Uploaded Files

Deletion requires the encrypted objects returned by the upload endpoint. Pass them in the `list` parameter:

```typescript
import fetch from 'node-fetch';
import FormData from 'form-data';

// encryptedItems comes from previous upload response
const encryptedItems = [
  { isEncrypted: 1, EncryptedData: '...encrypted_string...' }
];

const url = 'http://localhost:PORT/delete';
const form = new FormData();
form.append('list', JSON.stringify(encryptedItems));

await fetch(url, { method: 'POST', body: form })
  .then(res => res.json())
  .then(data => console.log('Delete result:', data));

```

### Checking Server Health

Use the heartbeat endpoint to verify the PicList server is running:

```typescript
import fetch from 'node-fetch';

fetch('http://localhost:PORT/heartbeat')
  .then(res => res.json())
  .then(data => console.log(data));
  // Output: { success: true, result: 'alive' }

```

## Key Source Files in the PicList Repository

Understanding the codebase structure helps when extending or debugging the PicList API endpoints.

| File | Role |
|------|------|
| [`src/main/server/router.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/router.ts) | Custom router implementation using a `Map` for O(1) handler lookup by URL and method. |
| [`src/main/server/routerManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/routerManager.ts) | Registers all API routes and implements business logic for `/upload`, `/delete`, and `/heartbeat`. |
| [`src/main/server/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/index.ts) | Bootstraps the HTTP server and delegates requests to the router. |
| [`src/main/server/apiDoc.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/apiDoc.ts) | Contains the Markdown source rendered at the documentation endpoints. |
| [`src/main/server/utils.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/utils.ts) | Provides `handleResponse` for standardized JSON responses and status codes. |
| [`src/main/apis/app/uploader/apis.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/uploader/apis.ts) | Core upload functions including `uploadChoosedFiles` and `uploadClipboardFiles`. |
| [`src/main/apis/app/window/windowManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/window/windowManager.ts) | Supplies window references required for native file dialogs during upload. |
| [`src/main/utils/aesHelper.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/utils/aesHelper.ts) | Handles AES encryption/decryption for secure payload transmission. |

## Summary

- PicList exposes five primary **PicList API endpoints**: `GET /`, `GET /upload`, `POST /upload`, `POST /delete`, and `ANY /heartbeat`.
- The server uses a lightweight custom router defined in [`src/main/server/router.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/router.ts) with handlers registered in [`src/main/server/routerManager.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/routerManager.ts).
- **POST /upload** supports dual modes: uploading a specific file list or reading directly from the clipboard when the list is empty.
- **POST /delete** requires encrypted task objects returned by the upload endpoint, utilizing [`src/main/utils/aesHelper.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/utils/aesHelper.ts) for decryption.
- All endpoints return JSON via the `handleResponse` utility in [`src/main/server/utils.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/utils.ts), ensuring consistent response formatting.

## Frequently Asked Questions

### What port does the PicList web server use by default?

PicList typically runs its embedded HTTP server on port **36677** by default, though this can be configured in the application settings. When constructing API requests, replace `PORT` in the code examples with your configured port number.

### How does the PicList upload endpoint handle clipboard images?

When you send a **POST** request to `/upload` with an empty `list` parameter or omit the list entirely, PicList triggers `uploadClipboardFiles` from [`src/main/apis/app/uploader/apis.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/apis/app/uploader/apis.ts). This function reads the current system clipboard and uploads any image data found there, returning encrypted URLs in the response.

### Why are upload and delete payloads encrypted in PicList API endpoints?

PicList uses AES encryption via [`src/main/utils/aesHelper.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/utils/aesHelper.ts) to secure sensitive data transmission between client and server. Upload responses contain encrypted objects that include deletion tokens, and the **POST /delete** endpoint expects these same encrypted objects to authorize file removal. This ensures that only clients with the correct encryption keys can delete previously uploaded assets.

### Can I use the PicList API endpoints for health monitoring?

Yes. The **`/heartbeat`** endpoint accepts any HTTP method and always returns `{ success: true, result: 'alive' }` with a 200 status code. This makes it ideal for load balancer health checks, Docker health probes, or simple uptime monitoring scripts.