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).

Astro Solution and Overlay

GET /api/gallery/{name}/astro/{path}

Returns the plate solution and object overlay for an astronomical image: the fitted WCS, scale_arcsec_px, rms_arcsec, matched_stars, and the list of overlay objects (deep-sky objects, named stars, transients, comets, asteroids) with pixel coordinates, ellipse geometry, and a near_capture flag on each transient. Images that cannot be solved return {"solved": false}.

Requires can_see_technical_details. Returns 404 when [astro] is not configured. See the Astrophotography guide.

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.

Posts also serve public web routes alongside the JSON API:

Route	Description
`{prefix}`	Posts index
`{prefix}/category/{slug}`	Category index (404 for unknown categories)
`{prefix}/feed.xml`	RSS 2.0 feed
`{prefix}/category/{slug}/feed.xml`	Per-category RSS feed
`{prefix}/{slug}`	Post detail

Posts Editing

All write endpoints require the can_edit_content permission, resolved from the posts system’s permission configuration and any _folder.md overrides in the target directory (see Permissions).

GET /api/posts/{name}/source/{slug}

Returns the raw markdown and metadata for a post, for use by editors:

{
  "slug": "travel/first-trip",
  "title": "First Trip",
  "summary": "A short summary",
  "date": "2026-01-15T00:00:00+00:00",
  "categories": ["Travel"],
  "hero_image": "gallery:main:vacation/beach.jpg",
  "content": "# First Trip\n\nMarkdown body..."
}

POST /api/posts/{name}/source

Creates a new post. The body is the same shape plus the target slug (letters, digits, hyphens, and underscores; / for subdirectories; segments may not start with _). date is optional and defaults to now. Returns 409 Conflict if the slug exists and 400 for invalid slugs.

{
  "slug": "travel/second-trip",
  "title": "Second Trip",
  "summary": "Another journey",
  "categories": ["Travel"],
  "hero_image": "https://example.com/hero.jpg",
  "content": "Markdown body..."
}

PUT /api/posts/{name}/source/{slug}

Updates an existing post with the same body shape (minus slug). The original publication date is preserved unless a date is supplied.

DELETE /api/posts/{name}/source/{slug}

Deletes the post’s markdown file from storage.

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
Astrophotography - Plate solving and object overlays