API Reference
Tenrankai provides HTTP APIs for gallery data, authentication, administration, and file uploads.
Authentication
API requests use the same session-based authentication as the web interface. Include the session cookie from a web login:
curl -b "session=your-session-cookie" http://localhost:3000/api/gallery/main/preview
Public galleries can be accessed without authentication.
Gallery API
Gallery API routes are prefixed with /api/gallery/{gallery_name}.
Gallery Preview
GET /api/gallery/{name}/preview
Returns preview data for a gallery (used by homepage widgets).
Gallery Data
GET /api/gallery/{name}/data/{path}
Returns JSON data for a gallery folder, including images and subfolders. Supports query parameters for pagination and filtering. The response includes grid_mode (string: "masonry" or "square") and max_columns (integer) reflecting the resolved settings for the folder (folder override > gallery setting > default).
Image Detail
GET /api/gallery/{name}/image/{path}
Returns JSON detail data for a specific image, including metadata, EXIF data, and available sizes.
Composite Preview
GET /api/gallery/{name}/composite/{path}
Returns a composite preview image for a folder (multiple thumbnails combined).
Image Metadata
GET /api/gallery/{name}/metadata/{path}
Returns metadata for an image (comments, picks, tags).
PUT /api/gallery/{name}/metadata/{path}
Updates metadata for an image. Requires appropriate permissions.
Comments
POST /api/gallery/{name}/comments/{path}
Adds a comment to an image. Requires can_add_comments permission. Supports area-specific comments with coordinate data.
PUT /api/gallery/{name}/comment/{comment_id}/edit/{image_path}
Edits an existing comment. Requires can_edit_own_comments or can_edit_any_comments permission.
DELETE /api/gallery/{name}/comment/{comment_id}/delete/{image_path}
Deletes a comment. Requires can_delete_own_comments or can_delete_any_comments permission.
Content Editing
PUT /api/gallery/{name}/folder-description/{path}
Updates a folder’s title and description. Requires can_edit_content permission.
PUT /api/gallery/{name}/image-description/{path}
Updates an image’s title and description. Requires can_edit_content permission.
AI Analysis
POST /api/gallery/{name}/analyze/{path}
Triggers AI analysis for a single image. Requires owner_access permission and OpenAI configuration.
POST /api/gallery/{name}/analyze-folder/{path}
Triggers AI analysis for all images in a folder. Requires owner_access permission.
Posts
POST /api/posts/{name}/refresh
Triggers a refresh of the posts index for the named posts system.
Gallery Web Routes
These routes serve HTML pages and images (not JSON APIs):
| Route | Description |
|---|---|
{prefix}/ | Gallery root (folder listing) |
{prefix}/{path} | Gallery subfolder |
{prefix}/image/{path} | Image file (with ?size= query parameter) |
{prefix}/_image/{path} | Image file (path-based size format) |
{prefix}/detail/{path} | Image detail view (React SPA) |
{prefix}/_download/{path} | Download folder as ZIP archive |
{prefix}/_raw/{path} | Download associated RAW file |
Authentication Routes
Email Login
| Route | Method | Description |
|---|---|---|
/_login | GET | Login page |
/_login/request | POST | Request email magic link |
/_login/verify | GET | Verify login token from email |
/_login/logout | GET | Log out and clear session |
/_login/profile | GET | User profile and passkey management |
/_login/passkey-enrollment | GET | Passkey enrollment page |
WebAuthn/Passkeys
| Route | Method | Description |
|---|---|---|
/api/webauthn/check-passkeys | POST | Check if user has registered passkeys |
/api/webauthn/register/start | POST | Start passkey registration ceremony |
/api/webauthn/register/finish/{reg_id} | POST | Complete passkey registration |
/api/webauthn/authenticate/start | POST | Start passkey authentication |
/api/webauthn/authenticate/finish/{auth_id} | POST | Complete passkey authentication |
/api/webauthn/passkeys | GET | List user’s registered passkeys |
/api/webauthn/passkeys/{passkey_id} | DELETE | Delete a passkey |
/api/webauthn/passkeys/{passkey_id}/name | PUT | Rename a passkey |
Auth Status
GET /api/verify
Check if the current session is authenticated. Returns user info if logged in.
Upload API (TUS Protocol)
Tenrankai supports resumable file uploads using the TUS protocol. Upload routes require can_manage_images permission.
| Route | Method | Description |
|---|---|---|
/_upload | OPTIONS | TUS capability discovery |
/_upload/{gallery} | OPTIONS, POST | Create a new upload |
/_upload/{gallery}/{upload_id} | OPTIONS, HEAD, PATCH, DELETE | Resume, check, or cancel upload |
The folder path is passed in the Upload-Metadata header (key: folderPath), not in the URL. Chunk size limit is 10MB.
Upload Example
# Create upload
curl -X POST "http://localhost:3000/_upload/main" \
-b "session=..." \
-H "Upload-Length: 1048576" \
-H "Upload-Metadata: filename dGVzdC5qcGc=,folderPath L3ZhY2F0aW9u" \
-H "Tus-Resumable: 1.0.0"
# Upload chunk
curl -X PATCH "http://localhost:3000/_upload/main/{upload_id}" \
-b "session=..." \
-H "Upload-Offset: 0" \
-H "Content-Type: application/offset+octet-stream" \
-H "Tus-Resumable: 1.0.0" \
--data-binary @file.jpg
Admin API
Admin routes are prefixed with /_admin/api and require authentication with owner_access permission.
User Management
| Route | Method | Description |
|---|---|---|
/_admin/api/users | GET | List all users |
/_admin/api/users | POST | Create a new user |
/_admin/api/users/{username} | GET | Get user details |
/_admin/api/users/{username} | PUT | Update user |
/_admin/api/users/{username} | DELETE | Delete user |
/_admin/api/users/{username}/invite | POST | Send login invitation email |
Gallery Management
| Route | Method | Description |
|---|---|---|
/_admin/api/galleries | GET | List all galleries |
/_admin/api/galleries/{name} | GET | Get gallery details |
/_admin/api/galleries/{name}/permissions | PUT | Update gallery permissions |
/_admin/api/galleries/{gallery}/users/{username}/roles | GET, PUT | Get or assign user roles |
/_admin/api/galleries/{gallery}/watermark-folder | POST | Create watermark folder |
Image Management (Admin)
| Route | Method | Description |
|---|---|---|
/_admin/api/galleries/{gallery}/images | DELETE | Delete images |
/_admin/api/galleries/{gallery}/folders/{path}/images/hide | POST | Hide/unhide images |
/_admin/api/galleries/{gallery}/folders/{path}/create | POST | Create folder |
/_admin/api/galleries/{gallery}/folders/{path} | DELETE | Delete folder |
/_admin/api/galleries/{gallery}/folders/{path}/rename | POST | Rename folder |
/_admin/api/galleries/{gallery}/folders/{path}/images/move | POST | Move images |
/_admin/api/galleries/{gallery}/folders/{path}/images/copy | POST | Copy images |
Role Management
| Route | Method | Description |
|---|---|---|
/_admin/api/roles | GET, POST | List or create roles |
/_admin/api/roles/{name} | GET, PUT, DELETE | Get, update, or delete a role |
/_admin/api/permission-groups | GET | List permission groups (for UI) |
Site Management (ConfigStorage)
| Route | Method | Description |
|---|---|---|
/_admin/api/sites | GET | List all sites |
/_admin/api/sites/{name} | GET, PUT | Get or update site config |
/_admin/api/sites/{site}/galleries | GET | List galleries for a site |
/_admin/api/sites/{site}/galleries/{name} | GET, PUT, DELETE | Manage site gallery config |
/_admin/api/sites/{site}/galleries/{gallery}/folders | GET | List gallery folders |
/_admin/api/sites/{site}/galleries/{gallery}/folders/{path} | GET, PUT | Get or update folder permissions |
/_admin/api/sites/{site}/galleries/{gallery}/folders/{path}/share | POST | Generate share link for folder |
/_admin/api/sites/{site}/galleries/{gallery}/folders/{path}/images | GET | List images in folder |
/_admin/api/sites/{site}/permissions | GET, PUT | Get or update site permissions |
/_admin/api/sites/{site}/reload | POST | Reload site configuration |
Theme Management
| Route | Method | Description |
|---|---|---|
/_admin/api/theme | GET | Get current theme |
/_admin/api/theme | PUT | Update theme |
/_admin/api/theme | DELETE | Reset theme to defaults |
Admin UI
The Admin UI is a React SPA served at /_admin/ and /_admin/{*path}.
Other Routes
| Route | Method | Description |
|---|---|---|
/ | GET | Homepage (template) |
/{path} | GET | Template page (catch-all) |
/static/{path} | GET | Static file serving |
/theme.css | GET | Generated theme CSS |
/robots.txt | GET | Robots.txt |
/api/verify | GET | Auth status check |
/api/refresh-static-versions | POST | Refresh static file cache-busting versions |
Next Steps
- Authentication - Configure user authentication
- Permissions - Set up access control
- Advanced Features - Admin UI, theme editor