# How to Integrate PicList with Typora or Obsidian: API and Configuration Guide

> Integrate PicList with Typora or Obsidian using its local HTTP API. Upload images seamlessly via POST requests to the /upload endpoint for efficient markdown editing. Learn how now.

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

---

**PicList exposes a local HTTP server on port 36677 that accepts image uploads via a REST API, enabling seamless integration with markdown editors like Typora and Obsidian through simple POST requests to the `/upload` endpoint.**

PicList, an enhanced fork of PicGo maintained by [Kuingsmile](https://github.com/kuingsmile), includes a built-in HTTP server that transforms the desktop application into a local image hosting gateway. Understanding how to leverage this **PicList Typora Obsidian integration** allows you to automate image uploads directly from your favorite markdown editors without manual intervention. The server supports both multipart form data and JSON payloads, making it compatible with a wide range of external tools.

## The Local Server Architecture

PicList runs a lightweight HTTP server locally to handle incoming upload requests from external applications.

### Server Initialization and Default Port

The server initializes on `127.0.0.1` with a default **port 36677**. This configuration is defined in the core server file:

```typescript
// src/main/server/index.ts#L15-L16
const host = config.host || '127.0.0.1'
const port = config.port || 36677

```

You can view the exact implementation in [`src/main/server/index.ts#L15-L16`](https://github.com/kuingsmile/piclist/blob/dev/src/main/server/index.ts#L15-L16).

### Request Handling with Multer

The server uses **multer** middleware to process multipart/form-data uploads. This allows editors to send images directly as file attachments rather than base64 strings:

```typescript
// src/main/server/index.ts#L22-L35
const upload = multer({
  storage: multer.diskStorage({
    destination: (req, file, cb) => {
      cb(null, app.getPath('temp'))
    },
    filename: (req, file, cb) => {
      cb(null, Date.now() + '-' + file.originalname)
    }
  })
})

```

See the multipart configuration in [`src/main/server/index.ts#L22-L35`](https://github.com/kuingsmile/piclist/blob/dev/src/main/server/index.ts#L22-L35).

## The Upload API Endpoint

The primary integration point is the `/upload` endpoint, which receives images and returns public URLs after processing through your configured picbed (cloud storage).

### Route Registration

The upload route is registered in the RPC router and forwards file lists to PicList’s uploader logic:

```typescript
// src/main/events/rpc/routes/upload/index.ts#L25-L30
router.post('/upload', upload.array('list'), async (req, res) => {
  const list = req.files || req.body.list
  const result = await uploadManager.upload(list)
  res.json(result)
})

```

View the route handler in [`src/main/events/rpc/routes/upload/index.ts#L25-L30`](https://github.com/kuingsmile/piclist/blob/dev/src/main/events/rpc/routes/upload/index.ts#L25-L30).

### Supported Payload Formats

The endpoint accepts two formats:

1. **Multipart/form-data**: Send files as form fields named `list` (supports multiple files).
2. **JSON payload**: Send `{"list": ["/absolute/path/to/image.png"]}` for server-side file path resolution.

## Configuring PicList for Editor Integration

Before connecting external editors, verify the server settings in PicList’s configuration interface.

### Server Settings UI

The default port and host values are exposed in the settings page:

```vue
<!-- src/renderer/pages/PicGoSetting.vue#L1036 -->
<el-input v-model="form.port" placeholder="36677" />

```

Access the configuration UI at [`src/renderer/pages/PicGoSetting.vue#L1036`](https://github.com/kuingsmile/piclist/blob/dev/src/renderer/pages/PicGoSetting.vue#L1036). You can disable the server or change the port if 36677 conflicts with other services.

### Configuration Paths

PicList stores server configuration using centralized path constants defined in [[`src/main/utils/configPaths.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/utils/configPaths.ts)](https://github.com/kuingsmile/piclist/blob/dev/src/main/utils/configPaths.ts). This ensures consistent config file locations across operating systems.

## Typora Integration Steps

Typora supports PicList natively in recent versions and via PicGo compatibility mode in older releases.

### Typora 1.6.0 and Above

For version 1.6.0+, select **PicList** directly from the Image Settings dropdown:

> "For Typora version >= 1.6.0, you can select PicList directly in the Image Settings." — [`README.md#L27-L31`](https://github.com/kuingsmile/piclist/blob/dev/README.md#L27-L31)

### Typora Below 1.6.0

For older versions:
1. Open **Preferences → Image**.
2. Set **Image Upload** to **PicGo(app)**.
3. Point the uploader path to your PicList executable.

Reference the legacy instructions in [`README.md#L27-L31`](https://github.com/kuingsmile/piclist/blob/dev/README.md#L27-L31).

## Obsidian Integration Steps

Obsidian requires the **Image Auto Upload Plugin** to communicate with PicList.

1. Install the plugin from the Obsidian community plugins.
2. Set **Default Uploader** to **PicGo(app)**.
3. Configure the API endpoint to `http://127.0.0.1:36677/upload`.

The exact configuration is documented in [`README.md#L33-L36`](https://github.com/kuingsmile/piclist/blob/dev/README.md#L33-L36).

Once configured, any pasted or dragged images automatically upload through PicList and return public URLs.

## Practical API Examples

Test your integration using these cURL commands before configuring editors.

### Multipart Upload (Typora Default)

```bash
curl -X POST http://127.0.0.1:36677/upload \
  -F "list=@/Users/username/Desktop/screenshot.png"

```

### JSON Upload (Path-Based)

```bash
curl -X POST http://127.0.0.1:36677/upload \
  -H "Content-Type: application/json" \
  -d '{"list":["/Users/username/Desktop/screenshot.png"]}'

```

### Query Parameter for Specific Picbed

Override the default picbed by adding the `picbed` query parameter:

```bash
curl -X POST "http://127.0.0.1:36677/upload?picbed=aws-s3" \
  -F "list=@image.png"

```

## Summary

- PicList runs an **HTTP server** on **port 36677** by default, configurable via the settings UI ([[`src/main/server/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/index.ts)](https://github.com/kuingsmile/piclist/blob/dev/src/main/server/index.ts)).
- The **`/upload`** endpoint accepts both **multipart form data** and **JSON payloads** ([[`src/main/events/rpc/routes/upload/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/events/rpc/routes/upload/index.ts)](https://github.com/kuingsmile/piclist/blob/dev/src/main/events/rpc/routes/upload/index.ts)).
- **Typora 1.6.0+** supports PicList natively, while older versions use PicGo(app) mode ([[`README.md`](https://github.com/kuingsmile/piclist/blob/main/README.md)](https://github.com/kuingsmile/piclist/blob/dev/README.md)).
- **Obsidian** integrates via the Image Auto Upload Plugin pointing to `http://127.0.0.1:36677/upload`.
- The server utilizes **multer** for file handling and supports custom picbed selection via query parameters.

## Frequently Asked Questions

### What port does PicList use for editor integrations?

PicList uses **port 36677** by default. You can modify this in the PicList settings interface under the server configuration section ([`src/renderer/pages/PicGoSetting.vue#L1036`](https://github.com/kuingsmile/piclist/blob/dev/src/renderer/pages/PicGoSetting.vue#L1036)). If this port is occupied, change it to any available port and update your editor settings accordingly.

### Does PicList support both JSON and multipart uploads?

Yes. The upload endpoint handles **multipart/form-data** for direct file transfers (used by most editors) and **JSON payloads** containing file paths (useful for CLI workflows). Both methods return a JSON response containing the uploaded image URLs.

### Can I use PicList with Typora versions older than 1.6.0?

Yes. For older Typora versions, configure the editor to use **PicGo(app)** mode instead of the native PicList option. Point the uploader executable path to the PicList binary location. This compatibility mode uses the same HTTP API on port 36677.

### Is the PicList server available when running in Docker?

Yes. When running PicList in a Docker container, expose port 36677 using the `-p 36677:36677` flag. External editors can then connect to the container's mapped port. Ensure the container has access to the image files or volumes mounted from the host system.