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.
Interactive API docs
When your PicFast instance is running, visit /docs for the full interactive Scalar API reference — browse every endpoint, fill in parameters, and send live requests directly from your browser.
The machine-readable OpenAPI spec is also available at /openapi.yaml and /openapi.json.
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 keyword, extension, date range, tag, 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, date range, tags) |
| 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/audit-logs/events | List available audit event types |
| GET | /admin/observability/summary | System overview (uptime, health, DB pool, usage stats) |
Audit log events
The audit log records the following event types (enabled by default via audit_upload_logs):
| Event | Description |
|---|
upload.success | Image uploaded successfully |
upload.delete | Image deleted |
tag.create | Tag created |
image.tag_add | Tag added to an image |
image.tag_remove | Tag removed from an image |
webhook.create | Webhook created |
webhook.delete | Webhook deleted |
user.register | New user registration |
user.password_change | User changed their password |
user.password_reset | User reset their password |
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.