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

API

PicHost exposes REST endpoints and a Twikoo-compatible upload. After sign-in, open API in the nav: a sidebar lists endpoints and token controls, the center shows parameters and copyable cURL, and the right panel supports live debugging.

Authentication

All REST calls use:

Auth-Token: YOUR_TOKEN

Token	How to obtain	Notes
API token	API page after sign-in (one per account, auto-created)	Auth-Token header; uploads and tagNames belong to that account
Legacy site token	API_UPLOAD_TOKEN env or old admin setting	Still accepted; uploads belong to the first admin. Twikoo form token also accepts each user’s API token

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" \
  -F 'tagNames=["blog","screenshot"]'

Optional form field tagNames: JSON array or comma-separated names. Tags apply to the user bound to the token (global token cannot tag). Tags do not change storage paths under images/.

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"

Optional query: tagIds (comma-separated, OR by default), tagMode=and, untagged=1. Each item includes a tags array.

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"]}'

6. Tags

Method	Path	Description
GET	/api/tags	List current user’s tags
POST	/api/tags	Create { "name": "work", "color": "#22c55e" }
PATCH	/api/tags/:id	Rename or recolor
DELETE	/api/tags/:id	Delete tag (images remain)
POST	/api/tags/merge	Merge tags into a target

7. Image tags

Method	Path	Description
POST	/api/images/tags	Add tags to an image
PATCH	/api/images/tags	Replace tag set
DELETE	/api/images/tags	Remove one tag
POST	/api/images/batch-tags	Batch add/remove

GET /api/stats accepts the same tag filter query params as the list API.

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