API Reference
PicFast exposes a REST API at /api/v1. All endpoints require authentication unless marked as public. The API accepts JWT access tokens or scoped API tokens (prefixed img_) via the Authorization: Bearer header.
System
| Method | Path | Auth | Description |
|---|
| GET | /health | No | Health check (database + storage) |
| GET | /metrics | No | Prometheus metrics endpoint |
| GET | /api/v1/config | No | Public site configuration |
| GET | /api/v1/version | No | Server version info |
| GET | /openapi.yaml | No | OpenAPI spec (YAML) |
| GET | /openapi.json | No | OpenAPI spec (JSON) |
| GET | /docs | No | Scalar API docs UI (interactive) |
Setup
| Method | Path | Auth | Description |
|---|
| GET | /api/v1/setup/status | No | Check if first-run setup is needed (no admin exists) |
| POST | /api/v1/setup | No | Create the first admin account (only available when no users exist) |
Auth
| Method | Path | Auth | Description |
|---|
| POST | /api/v1/auth/register | No | Register a new account |
| POST | /api/v1/auth/login | No | Log in, returns JWT + refresh token |
| POST | /api/v1/auth/refresh | No | Refresh access token |
| POST | /api/v1/auth/logout | JWT | Revoke all refresh tokens |
| POST | /api/v1/auth/verify-email | No | Verify email with token |
| POST | /api/v1/auth/resend-verification | No | Resend verification email |
User
| Method | Path | Auth | Description |
|---|
| GET | /api/v1/users/me | JWT | Get current user profile |
| PUT | /api/v1/users/me | JWT | Update profile (name, password, settings) |
API Tokens
| Method | Path | Auth | Description |
|---|
| GET | /api/v1/api-tokens | JWT | List your API tokens |
| POST | /api/v1/api-tokens | JWT | Create API token (scopes, expiration) |
| DELETE | /api/v1/api-tokens/{id} | JWT | Delete an API token |
Images
| Method | Path | Auth | Description |
|---|
| POST | /api/v1/images | JWT / token | Upload an image (multipart) |
| GET | /api/v1/images | JWT / token | List your images (paginated, filterable by album_id) |
| GET | /api/v1/images/{key} | JWT / token | Get image details by key |
| PATCH | /api/v1/images/{key} | JWT / token | Update image (album_id, permission) |
| DELETE | /api/v1/images/{key} | JWT / token | Delete an image by key |
Upload fields
POST /api/v1/images accepts multipart/form-data:
| Field | Type | Description |
|---|
file | file | Image file (required) |
album_id | int | Album ID to group the image |
permission | int | 0 = private, 1 = public (default) |
expires_in | string | Duration like 24h, 7d |
strategy_id | int | Storage backend to use |
Albums
| Method | Path | Auth | Description |
|---|
| GET | /api/v1/albums | JWT / token | List your albums |
| POST | /api/v1/albums | JWT / token | Create an album |
| PUT | /api/v1/albums/{id} | JWT / token | Update album (name, intro) |
| DELETE | /api/v1/albums/{id} | JWT / token | Delete an album |
Strategies
| Method | Path | Auth | Description |
|---|
| GET | /api/v1/strategies | JWT / token | List strategies available to your group |
Guest upload
| Method | Path | Auth | Description |
|---|
| POST | /api/v1/upload | Optional | Guest upload (when enabled in admin settings) |
ShareX
| Method | Path | Auth | Description |
|---|
| GET | /api/v1/sharex/config | No | Download ShareX .sxcu config file |
| POST | /api/v1/sharex/upload | Optional | ShareX-compatible upload endpoint |
Admin API
All admin endpoints require a JWT with admin role. Prefix: /api/v1/admin.
| Method | Path | Description |
|---|
| GET | /admin/users | List users (filter by keyword, status) |
| GET / PUT / DELETE | /admin/users/{id} | View, update, or delete a user |
| GET / POST | /admin/groups | List or create groups |
| GET / PUT / DELETE | /admin/groups/{id} | View, update, or delete a group |
| GET / POST | /admin/strategies | List or create storage strategies |
| GET / PUT / DELETE | /admin/strategies/{id} | View, update, or delete a strategy |
| GET | /admin/images | List all images (filter by keyword, email, extension) |
| DELETE | /admin/images/{id} | Delete any image by ID |
| GET | /admin/moderation/pending | List images pending moderation |
| POST | /admin/moderation/{id}/approve | Approve an image |
| POST | /admin/moderation/{id}/reject | Reject an image (optional reason) |
| GET / PUT | /admin/settings | View or update site settings (runtime hot-reload) |
| GET | /admin/audit-logs | List audit logs (filter by action, resource_type) |
| GET | /admin/observability/summary | System overview (uptime, health, DB pool, usage stats) |
AI agent integration (MCP)
PicFast ships an MCP server for AI agent integration (Claude, Cursor, VS Code Copilot). See the dedicated MCP Integration page for setup instructions, tool reference, and configuration.
OpenAPI spec
The full machine-readable API spec is available at:
/openapi.yaml — YAML format/openapi.json — JSON format/docs — Interactive Scalar UI for live API testing