PicHost/docs-site/en/guide/api.md

API

PicHost exposes REST endpoints and a Twikoo-compatible upload. After deployment, open the in-app API page for your token and copyable cURL snippets.

Authentication

All REST calls use:

Auth-Token: YOUR_TOKEN

Token type	How to obtain	Notes
Global	Admin API page or API_UPLOAD_TOKEN env	Env wins and blocks UI regenerate
Personal	Each user’s API page	Uploads belong to that user

Form uploads may use field token (Twikoo protocol).

Endpoints

1. Upload images

POST /api/images/upload

Upload one or more images via image; also accepts file, files. Stored under images/.

curl -X POST "https://admin.example.com/api/images/upload" \
  -H "Auth-Token: YOUR_TOKEN" \
  -F "image=@./demo.png"

2. List images

GET /api/images

Paginated gallery. limit default 20, max 100.

curl "https://admin.example.com/api/images?limit=20&page=1" \
  -H "Auth-Token: YOUR_TOKEN"

3. Search images

GET /api/images/search

Search by filename or path; q is required.

curl "https://admin.example.com/api/images/search?q=demo&limit=20&page=1" \
  -H "Auth-Token: YOUR_TOKEN"

4. Delete image

DELETE /api/images

Delete by key (storage path, e.g. images/2026/08/xxx.webp).

curl -X DELETE "https://admin.example.com/api/images?key=images/2026/08/xxxx.webp" \
  -H "Auth-Token: YOUR_TOKEN"

5. Batch delete

POST /api/images/batch-delete

JSON body: {"keys":["images/2026/08/a.webp","images/2026/08/b.webp"]}

curl -X POST "https://admin.example.com/api/images/batch-delete" \
  -H "Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keys":["images/2026/08/a.webp","images/2026/08/b.webp"]}'

Errors

REST responses are JSON with code and message (UNAUTHORIZED, FORBIDDEN, INVALID_REQUEST, etc.). Twikoo uses EasyImage-compatible JSON.

Visibility

• User token: list/search/delete own images only
• Admin token: all images
• Global token uploads belong to admin

See Users & permissions.

Twikoo

POST /api/index.php — Twikoo.

See also

• Environment variables
• Reverse proxy