Core HTTP server

Configure a destination with the CLI before starting picgo-server. The Core server supports uploads and heartbeat checks; it does not provide the desktop gallery or desktop deletion endpoint.

Start the server

picgo-server --host 127.0.0.1 --port 36677 -c /path/to/data.json

Option	Purpose
-c, --config	JSON configuration file
-p, --port	Port; default 36677
--host	Bind address; default 0.0.0.0
-k, --key	Access key for remote uploads

Bind explicitly to 127.0.0.1 for local integrations. Loopback uploads bypass key validation. For remote access, set your own key and connect over a controlled network or an HTTPS reverse proxy.

Upload a file

curl -X POST "http://127.0.0.1:36677/upload" \
  -F "file=@./image.png"

multipart/form-data sends file contents, making it suitable for remote clients. Supply multiple file fields to upload several images.

Upload server paths or 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"]}'

Local paths must exist on the server or inside its container. An omitted file list attempts clipboard upload, which is unsuitable for a headless server.

Select a provider and configuration

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

Use the provider's programmatic ID and the exact saved configuration name. Remote requests pass the key you configured in the key query parameter. Remove it from examples, screenshots, and shared logs.

Response

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

Check success and the result list. A Core success response returns URLs; do not assume it includes desktop fullResult objects or deletion metadata.

Heartbeat and documentation

curl http://127.0.0.1:36677/heartbeat

A successful heartbeat returns {"success":true,"result":"alive"}. Open the server's root URL in a browser to see usage examples.