PicList API Endpoints: Complete Guide to the Web Server Interface

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. 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. 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 (specifically handleResponse) to standardize JSON output and HTTP status codes.

Server Bootstrap

The entry point in 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 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
• Content Source: Markdown source provided by 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
• Core Dependencies:
  • src/main/apis/app/uploader/apis.ts provides uploadChoosedFiles and uploadClipboardFiles
  • src/main/apis/app/window/windowManager.ts supplies a window reference required for file-selection dialogs
• Response: Returns encrypted upload results using 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.

Handler Details:

• Location: Inline async handler in 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

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:

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:

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:

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:

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	Custom router implementation using a Map for O(1) handler lookup by URL and method.
src/main/server/routerManager.ts	Registers all API routes and implements business logic for /upload, /delete, and /heartbeat.
src/main/server/index.ts	Bootstraps the HTTP server and delegates requests to the router.
src/main/server/apiDoc.ts	Contains the Markdown source rendered at the documentation endpoints.
src/main/server/utils.ts	Provides handleResponse for standardized JSON responses and status codes.
src/main/apis/app/uploader/apis.ts	Core upload functions including uploadChoosedFiles and uploadClipboardFiles.
src/main/apis/app/window/windowManager.ts	Supplies window references required for native file dialogs during upload.
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 with handlers registered in 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 for decryption.
• All endpoints return JSON via the handleResponse utility in 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}