Desktop HTTP API

The desktop app exposes upload, heartbeat, and gallery deletion endpoints. Keep PicList running in the background. For a standalone deployment, use the Core HTTP server.

Enable the service

Enable the upload API in advanced settings and choose its bind address and port. The default port is 36677. Use 127.0.0.1 for local integrations.

If the port is occupied, the app can detect an existing PicList server or try subsequent ports. Check the actual listening port in logs if a connection fails.

Endpoints

Method	Path	Purpose
GET / POST	/heartbeat	Availability check
GET	/ or /upload	Browser usage documentation
POST	/upload	Files, server paths, URLs, or clipboard
POST	/delete	Delete using desktop upload and gallery metadata

curl http://127.0.0.1:36677/heartbeat

{"success":true,"result":"alive"} confirms reachability, not a correctly configured destination.

Upload files

curl -X POST "http://127.0.0.1:36677/upload?picbed=aws-s3-plist&configName=Docs" \
  -F "file=@./image.png"

picbed is a provider ID; configName is a saved configuration name. Omitting both uses the default destination. In 3.6, request selection does not change persistent defaults.

JSON paths and URLs

curl -X POST "http://127.0.0.1:36677/upload" \
  -H "Content-Type: application/json" \
  -d '{"list":["/absolute/path/image.png","https://example.com/photo.jpg"]}'

Paths must exist on the computer running PicList. Escape Windows backslashes in JSON or use forward slashes. An empty or omitted list triggers clipboard upload.

Success response

{
  "success": true,
  "result": ["https://images.example.com/image.png"]
}

This example omits fullResult. The desktop service also returns detailed gallery and deletion metadata, which can contain sensitive information. Keep it private. Check success and the result count rather than only the HTTP status.

Remote access and authentication

Remote uploads pass the configured upload key in the key query parameter. The app bypasses this requirement for loopback requests. The key is not uniform authorization for every API route: do not assume every endpoint is protected or expose the service directly to an untrusted network.

When using a proxy, check its authentication, listener scope, and request logging so the key is not disclosed.

Finalization recovery

In 3.6, remote delivery can finish while a later gallery save or success-stage script fails. The response can be:

{
  "success": false,
  "stage": "finalization",
  "finalizationId": "EXAMPLE_FINALIZATION_ID",
  "message": "Remote upload completed. Retry with finalizationId to finish without uploading again."
}

Keep the ID and send POST /upload?finalizationId=EXAMPLE_FINALIZATION_ID to finish that job rather than uploading the file again.

Delete endpoint

POST /delete accepts {"list":[...]}, using objects from the desktop upload response's fullResult. Preserve original metadata such as isEncrypted and EncryptedData. Do not send URL strings alone or invent deletion fields.

Deletion can break published images. Confirm the object and destination, then inspect success and failure details. The Core server does not provide this desktop deletion endpoint.