API docs by Redocly

Lumilio-Photos API (1.0)

Download OpenAPI specification:

URL: http://www.github.com/EdwinZhanCN/Lumilio-Photos License: GPLv3.0

Media management system API with asset features

Queue

Get queue summaries

Get aggregated processing activity per queue, including recent error samples

query Parameters
error_limit
integer

Recent error samples per queue (default: 5, max: 20)

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "generated_at": "string",
  • "queues": [
    ]
}

Get job statistics

Get aggregated statistics about jobs by state

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "available": 0,
  • "cancelled": 0,
  • "completed": 0,
  • "discarded": 0,
  • "retryable": 0,
  • "running": 0,
  • "scheduled": 0
}

agent

Chat with Agent

Send a query to agent and receive streaming responses via SSE. Manages conversation threads.

Request Body schema: application/json
required

Chat request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Resume Agent Chat

Resume a conversation from an interrupt point (e.g., user confirmation for a tool call)

Request Body schema: application/json
required

Resume request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

List Agent Pins

List all pinned widgets for the current user, in creation order.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Pin an Agent Ref

Copy a session ref into a durable board widget. Live mode replays the producing plan on hydration when replayable; otherwise the pin freezes the snapshot.

Request Body schema: application/json
required

Pin request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "count": 24,
  • "created_at": "string",
  • "layout": {
    },
  • "mode": "frozen",
  • "pin_id": "7d4df41e-9aa2-4d44-9a3d-111111111111",
  • "summary": "string",
  • "title": "Kyoto 2025",
  • "truncated": true,
  • "widget": "asset_grid"
}

Delete Agent Pin

Remove a pinned widget from the board.

path Parameters
id
required
string

Pin ID

Responses

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Get Agent Pin Assets

Get a page of assets for a pinned widget. Frozen pins serve the stored snapshot; live pins replay their plan.

path Parameters
id
required
string

Pin ID

query Parameters
limit
integer

Page size (default 50, max 200)

offset
integer

Page offset (default 0)

Responses

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "pagination": {
    },
  • "total": 97
}

Update Agent Pin Layout

Persist the board grid placement for one or more pins.

Request Body schema: application/json
required

Layout updates

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Get Agent Ref Metadata

Get metadata and facet summary for an agent ref. Refs are scoped to the requesting user and thread.

path Parameters
id
required
string

Ref ID

query Parameters
thread_id
required
string

Thread (conversation) the ref belongs to

Responses

Response samples

Content type
application/json
{
  • "count": 97,
  • "created_at": "string",
  • "facets": {
    },
  • "op": "combine",
  • "ref_id": "r3_kyoto",
  • "truncated": true
}

Get Agent Ref Assets

Get a page of assets for an agent ref, in snapshot order.

path Parameters
id
required
string

Ref ID

query Parameters
thread_id
required
string

Thread (conversation) the ref belongs to

limit
integer

Page size (default 50, max 200)

offset
integer

Page offset (default 0)

Responses

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "pagination": {
    },
  • "total": 97
}

Get Available Tools

Get list of all registered agent tools

Responses

Response samples

Content type
application/json
[
  • {
    }
]

albums

List albums

Retrieve a paginated list of albums for the authenticated user

Authorizations:
BearerAuth
query Parameters
limit
integer
Default: 20

Maximum number of results (max 100)

offset
integer
Default: 0

Number of results to skip for pagination

repository_id
string

Optional repository UUID filter

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "albums": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Create a new album

Create a new album for the authenticated user

Authorizations:
BearerAuth
Request Body schema: application/json
required

Album creation data

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "album_id": 0,
  • "album_name": "string",
  • "album_type": "string",
  • "asset_count": 0,
  • "cover_asset_id": "string",
  • "created_at": "string",
  • "description": "string",
  • "display_cover_asset_id": "string",
  • "updated_at": "string",
  • "user_id": 0
}

Delete album

Delete an album by its ID

Authorizations:
BearerAuth
path Parameters
id
required
integer

Album ID

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Get album by ID

Retrieve a specific album by its ID

Authorizations:
BearerAuth
path Parameters
id
required
integer

Album ID

query Parameters
repository_id
string

Optional repository UUID filter

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "album_id": 0,
  • "album_name": "string",
  • "album_type": "string",
  • "asset_count": 0,
  • "cover_asset_id": "string",
  • "created_at": "string",
  • "description": "string",
  • "display_cover_asset_id": "string",
  • "updated_at": "string",
  • "user_id": 0
}

Update album

Update an existing album's information

Authorizations:
BearerAuth
path Parameters
id
required
integer

Album ID

Request Body schema: application/json
required

Album update data

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "album_id": 0,
  • "album_name": "string",
  • "album_type": "string",
  • "asset_count": 0,
  • "cover_asset_id": "string",
  • "created_at": "string",
  • "description": "string",
  • "display_cover_asset_id": "string",
  • "updated_at": "string",
  • "user_id": 0
}

Get assets in album

Retrieve all assets in a specific album

Authorizations:
BearerAuth
path Parameters
id
required
integer

Album ID

query Parameters
repository_id
string

Optional repository UUID filter

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "album_id": 0,
  • "assets": [
    ],
  • "count": 0
}

Remove asset from album

Remove an asset from a specific album

Authorizations:
BearerAuth
path Parameters
id
required
integer

Album ID

assetId
required
string

Asset ID (UUID format)

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Add asset to album

Add an asset to a specific album

Authorizations:
BearerAuth
path Parameters
id
required
integer

Album ID

assetId
required
string

Asset ID (UUID format)

Request Body schema: application/json

Asset position in album

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Update asset position in album

Update the position of an asset within a specific album

Authorizations:
BearerAuth
path Parameters
id
required
integer

Album ID

assetId
required
string

Asset ID (UUID format)

Request Body schema: application/json
required

New position data

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Queue BioCLIP for a bio album

Queue BioCLIP processing for photo assets in a bio album that do not yet have species predictions.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Album ID

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "BioCLIP processing queued successfully",
  • "queued_assets": 12,
  • "status": "queued"
}

Get albums containing asset

Retrieve all albums that contain a specific asset

Authorizations:
BearerAuth
path Parameters
id
required
string

Asset ID (UUID format)

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "albums": [
    ],
  • "asset_id": "string",
  • "count": 0
}

assets

Upload a single asset

Upload a single photo, video, audio file, or document to the system. The file is staged in a repository and queued for processing.

header Parameters
X-Content-Hash
string

Client-calculated BLAKE3 hash of the file

Request Body schema:

Asset file to upload | Repository UUID (uses default repository if not provided)

One of
file (file)

Responses

Response samples

Content type
application/json
{
  • "content_hash": "abcd1234567890",
  • "file_name": "photo.jpg",
  • "message": "File received and queued for processing",
  • "size": 1048576,
  • "status": "processing",
  • "task_id": 12345
}

Delete asset

Soft delete an asset by marking it as deleted. The physical file is not removed.

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Get asset by ID

Retrieve detailed information about a specific asset. Optionally include thumbnails, tags, albums, species predictions, OCR results, face recognition, and captions.

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

query Parameters
include_thumbnails
boolean
Default: true

Include thumbnails

include_tags
boolean
Default: true

Include tags

include_albums
boolean
Default: true

Include albums

include_species
boolean
Default: true

Include species predictions

include_ocr
boolean
Default: false

Include OCR results

include_faces
boolean
Default: false

Include face recognition

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "albums": [
    ],
  • "asset_id": "string",
  • "capture_offset_minutes": 0,
  • "deleted_at": "string",
  • "duration": 0,
  • "face_result": {
    },
  • "file_size": 0,
  • "hash": "string",
  • "height": 0,
  • "is_deleted": true,
  • "liked": true,
  • "mime_type": "string",
  • "ocr_result": {
    },
  • "original_filename": "string",
  • "owner_id": 0,
  • "rating": 0,
  • "repository_id": "string",
  • "species_predictions": [
    ],
  • "specific_metadata": {
    },
  • "stack": {
    },
  • "status": [
    ],
  • "storage_path": "string",
  • "tags": [
    ],
  • "taken_time": "string",
  • "thumbnails": [
    ],
  • "type": "string",
  • "upload_time": "string",
  • "width": 0
}

Update asset metadata

Update the specific metadata of an asset (e.g., photo EXIF data, video metadata).

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

Request Body schema: application/json
required

Asset metadata

dbtypes.PhotoSpecificMetadata (object) or dbtypes.VideoSpecificMetadata (object) or dbtypes.AudioSpecificMetadata (object)

Responses

Request samples

Content type
application/json
{
  • "specific_metadata": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Add asset to album

Associate an asset with a specific album by asset ID and album ID.

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

albumId
required
integer
Example: 123

Album ID

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Get web-optimized audio

Serve the web-optimized MP3 audio version for an asset by asset ID.

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

Responses

Update asset description

Update the description metadata of an asset

path Parameters
id
required
string

Asset ID

Request Body schema: application/json
required

Description data

description
string

Responses

Request samples

Content type
application/json
{
  • "description": "A beautiful sunset photo"
}

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Get raw asset EXIF

Retrieve the full exiftool JSON object stored for an asset during metadata processing.

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "asset_id": "string",
  • "exif_raw": { }
}

Export asset

Re-encode an asset's original file to JPEG, PNG, WebP, or AVIF with optional max dimensions and quality, and stream it back as a download.

path Parameters
id
required
string

Asset ID

query Parameters
format
required
string

Output format (jpeg, png, webp, avif)

quality
integer

Quality 1-100 for lossy formats

max_width
integer

Maximum output width in pixels

max_height
integer

Maximum output height in pixels

filename
string

Base download filename (without extension)

Responses

Update asset like status

Update the like/favorite status of a specific asset

path Parameters
id
required
string

Asset ID

Request Body schema: application/json
required

Like data

liked
boolean

Responses

Request samples

Content type
application/json
{
  • "liked": true
}

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Get original file

Serve the original file content for an asset by asset ID. Returns the file as an octet-stream.

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

Responses

Update asset rating

Update the rating (0-5) of a specific asset

path Parameters
id
required
string

Asset ID

Request Body schema: application/json
required

Rating data

rating
integer [ 0 .. 5 ]

Responses

Request samples

Content type
application/json
{
  • "rating": 5
}

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Update asset rating and like status

Update both the rating (0-5) and like/favorite status of a specific asset

path Parameters
id
required
string

Asset ID

Request Body schema: application/json
required

Rating and like data

liked
boolean
rating
integer [ 0 .. 5 ]

Responses

Request samples

Content type
application/json
{
  • "liked": true,
  • "rating": 5
}

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Reprocess asset

Reprocess a failed or warning asset by resetting its status and re-enqueuing for processing

path Parameters
id
required
string

Asset ID

Request Body schema: application/json

Reprocessing tasks (optional)

force_full_retry
boolean
tasks
Array of strings

Responses

Request samples

Content type
application/json
{
  • "force_full_retry": false,
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "failed_tasks": [
    ],
  • "message": "Reprocessing job queued successfully",
  • "retry_tasks": [
    ],
  • "status": "queued"
}

Restore asset

Restore a soft-deleted asset from Trash. The original file is not moved.

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Get asset edit sidecar

Retrieve the non-destructive Studio edit sidecar stored under the asset repository .lumilio directory.

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "exists": true,
  • "sidecar": {
    }
}

Update asset edit sidecar

Store non-destructive Studio edit data under the asset repository .lumilio directory.

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

Request Body schema: application/json
required

Sidecar payload

object (dto.StudioEditAdjustmentsDTO)
asset_id
string
object (dto.LumilioSidecarSourceDTO)
updated_at
string
version
integer

Responses

Request samples

Content type
application/json
{
  • "adjustments": {
    },
  • "asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "source": {
    },
  • "updated_at": "2026-05-26T10:00:00Z",
  • "version": 1
}

Response samples

Content type
application/json
{
  • "asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "exists": true,
  • "sidecar": {
    }
}

Remove asset from stack

Removes an asset from its stack, making it standalone

Authorizations:
BearerAuth
path Parameters
id
required
string

Asset ID

Responses

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Get asset stack

Returns the stack (group) that contains the specified asset

Authorizations:
BearerAuth
path Parameters
id
required
string

Asset ID

Responses

Response samples

Content type
application/json
{
  • "asset_id": "string",
  • "stack": {
    }
}

Get asset thumbnail

Retrieve a specific thumbnail image for an asset by asset ID and size parameter. Returns the image file directly.

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

query Parameters
size
string
Default: "medium"
Enum: "small" "medium" "large"

Thumbnail size

Responses

Get web-optimized video

Serve the web-optimized MP4 video version for an asset by asset ID.

path Parameters
id
required
string
Example: "550e8400-e29b-41d4-a716-446655440000"

Asset ID (UUID format)

Responses

Batch upload assets with chunk support

Unified batch upload endpoint that supports both small files and chunked large files. Field names should follow format: single_{session_id} for single files or chunk_{session_id}{index}{total} for chunks.

Request Body schema:

Repository UUID (uses default repository if not provided) | Single file upload - use format: single_{session_id} | Chunked file upload - use format: chunk_{session_id}{index}{total}

One of
string (repository_id)

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Get upload configuration

Get current upload configuration including chunk size and concurrency limits based on system memory

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "chunk_size": 0,
  • "max_concurrent": 0,
  • "max_in_flight_requests": 0,
  • "memory_buffer": 0,
  • "merge_concurrency": 0
}

Get upload progress

Get detailed progress information for upload sessions

query Parameters
session_ids
string

Comma-separated session IDs (optional)

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "sessions": [
    ],
  • "summary": {
    }
}

Download assets

Serve original files for the requested asset IDs as a zip archive.

Request Body schema: application/json
required

Asset IDs to download

asset_ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "asset_ids": [
    ]
}

Get featured photos

Select a small set of featured photos using deterministic weighted sampling (A-ES) with diversity constraints.

query Parameters
count
integer
Default: 8

Number of featured photos to return

candidate_limit
integer
Default: 240

Max candidate photos considered before selection

days
integer
Default: 3650

Only consider photos from the last N days (0 disables date cutoff)

seed
string

Deterministic seed (default: current UTC date YYYY-MM-DD)

repository_id
string

Optional repository UUID filter

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "candidate_count": 240,
  • "count": 8,
  • "generated_at_time": "2026-02-10T12:00:00Z",
  • "seed": "2026-02-10",
  • "strategy": "weighted_aes_v1"
}

Get filter options

Get available camera models and lenses for filter dropdowns

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "camera_models": [
    ],
  • "lenses": [
    ]
}

Queue asset index rebuild

Queue a background batch that backfills AI indexing for existing photos.

Request Body schema: application/json

Reindex request

limit
integer [ 1 .. 500 ]
missing_only
boolean
repository_id
string
tasks
Array of strings

Responses

Request samples

Content type
application/json
{
  • "limit": 200,
  • "missing_only": true,
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "disabled_tasks": [
    ],
  • "job_id": 123,
  • "limit": 200,
  • "message": "Index rebuild job queued successfully",
  • "missing_only": true,
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "requested_tasks": [
    ],
  • "status": "queued"
}

List indexing repositories

Return repositories that can be used to scope indexing stats and reindex requests.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "repositories": [
    ]
}

Get asset indexing stats

Return indexing coverage and queued job counts for photo AI tasks.

query Parameters
repository_id
string

Optional repository UUID filter

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "photo_total": 2400,
  • "reindex_jobs": 1,
  • "tasks": {
    }
}

Get liked assets

Get all assets that have been liked/favorited

query Parameters
limit
integer
Default: 20

Number of assets to return

offset
integer
Default: 0

Number of assets to skip

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "limit": 20,
  • "offset": 0,
  • "total": 150
}

Query assets (unified endpoint)

Unified endpoint for listing, filtering, and searching assets. Replaces separate /filter and /search endpoints.

Request Body schema: application/json
required

Query parameters

object (dto.AssetFilterDTO)

Unified filter options

object (dto.PaginationDTO)

limit, offset

query
string

Search keyword (optional)

search_type
string
Enum: "filename" "semantic"

"filename" (default) | "semantic"

sort_by
string
Enum: "recently_added" "date_captured"
stack_mode
string
Enum: "collapsed" "expanded"
viewer_timezone
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "pagination": {
    },
  • "query": "sunset photo",
  • "search_type": "filename",
  • "sort_by": "date_captured",
  • "stack_mode": "collapsed",
  • "viewer_timezone": "America/New_York"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 20,
  • "offset": 0,
  • "stack_mode": "collapsed",
  • "total_assets": 150,
  • "total_visible": 120
}

Get photo map points

Return lightweight paginated photo records containing only map-related fields (asset ID, filename, times, GPS lat/lon).

query Parameters
limit
integer
Default: 1000

Page size (1-5000)

offset
integer
Default: 0

Page offset

repository_id
string

Optional repository UUID filter

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "limit": 1000,
  • "offset": 0,
  • "points": [
    ],
  • "total": 1500
}

Get assets by rating

Get assets with a specific rating (0-5)

path Parameters
rating
required
integer

Rating (0-5)

query Parameters
limit
integer
Default: 20

Number of assets to return

offset
integer
Default: 0

Number of assets to skip

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "limit": 20,
  • "offset": 0,
  • "total": 150
}

Search assets

Search assets with optional top results enhancement and filename fallback.

Request Body schema: application/json
required

Search parameters

debug
boolean
enhancement_mode
string
Enum: "auto" "off" "only"
object (dto.AssetFilterDTO)

Unified filter options

object (dto.PaginationDTO)

limit, offset

query
string
sort_by
string
Enum: "recently_added" "date_captured"
stack_mode
string
Enum: "collapsed" "expanded"
top_results_limit
integer [ 1 .. 200 ]
viewer_timezone
string

Responses

Request samples

Content type
application/json
{
  • "debug": true,
  • "enhancement_mode": "auto",
  • "filter": {
    },
  • "pagination": {
    },
  • "query": "red bird on branch",
  • "sort_by": "date_captured",
  • "stack_mode": "collapsed",
  • "top_results_limit": 200,
  • "viewer_timezone": "America/New_York"
}

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "result_items": [
    ],
  • "results_total_assets": 150,
  • "results_total_visible": 120,
  • "stack_mode": "collapsed",
  • "top_items": [
    ],
  • "top_results_meta": {
    }
}

Create manual stack

Manually groups the specified assets into a new stack

Authorizations:
BearerAuth
Request Body schema: application/json
required

Asset IDs to stack

asset_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "asset_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "member_count": 3,
  • "members": [
    ],
  • "stack_id": "550e8400-e29b-41d4-a716-446655440000",
  • "stack_kind": "live_photo"
}

Get supported asset types

Retrieve a list of all supported asset types in the system.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "types": [
    ]
}

auth

Login user

Authenticate user with username and password. Returns an MFA challenge instead of session tokens when TOTP is enabled.

Request Body schema: application/json
required

Login credentials

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "bootstrap_admin": true,
  • "expiresAt": "string",
  • "mfa_methods": [
    ],
  • "mfa_token": "string",
  • "refreshToken": "string",
  • "requires_mfa": true,
  • "token": "string",
  • "user": {
    }
}

Logout user

Revoke the user's refresh token

Request Body schema: application/json
required

Refresh token to revoke

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Get current user

Get information about the currently authenticated user

Authorizations:
BearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "avatar_asset_id": "string",
  • "created_at": "string",
  • "display_name": "string",
  • "is_active": true,
  • "last_login": "string",
  • "permissions": [
    ],
  • "role": "string",
  • "updated_at": "string",
  • "user_id": 0,
  • "username": "string"
}

Get media access token

Generate a short-lived media token for image/video/audio URL authorization in browser media elements.

Authorizations:
BearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "expires_at": "string",
  • "token": "string"
}

Get MFA status

Get the authenticated user's MFA status, including TOTP enablement and remaining recovery codes.

Authorizations:
BearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "available_methods": [
    ],
  • "passkey_count": 0,
  • "recovery_codes_generated_at": "string",
  • "recovery_codes_remaining": 0,
  • "totp_enabled": true
}

List passkeys

List the authenticated user's enrolled passkeys.

Authorizations:
BearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "credentials": [
    ],
  • "total": 0
}

Delete passkey

Delete one enrolled passkey for the authenticated user.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Passkey ID

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Begin passkey enrollment

Create WebAuthn registration options to add a new passkey to the authenticated account.

Authorizations:
BearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "challenge_token": "string",
  • "options": null
}

Verify passkey enrollment

Verify a passkey enrollment response and attach the new passkey to the authenticated account.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Passkey enrollment verification payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "label": "string",
  • "last_used_at": "string",
  • "passkey_id": 0,
  • "transports": [
    ]
}

Regenerate recovery codes

Generate a fresh set of recovery codes for the authenticated user.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Recovery code regeneration payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "generated_at": "string",
  • "recovery_codes": [
    ],
  • "status": {
    }
}

Disable TOTP

Disable TOTP MFA and invalidate recovery codes for the authenticated user.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Disable TOTP payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "available_methods": [
    ],
  • "passkey_count": 0,
  • "recovery_codes_generated_at": "string",
  • "recovery_codes_remaining": 0,
  • "totp_enabled": true
}

Enable TOTP

Verify a TOTP setup code and enable TOTP MFA for the authenticated user.

Authorizations:
BearerAuth
Request Body schema: application/json
required

TOTP enable payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "generated_at": "string",
  • "recovery_codes": [
    ],
  • "status": {
    }
}

Begin TOTP setup

Generate a new TOTP secret and setup token for the authenticated user.

Authorizations:
BearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "account_name": "string",
  • "issuer": "string",
  • "otpauth_uri": "string",
  • "secret": "string",
  • "setup_token": "string"
}

Verify MFA challenge

Verify a pending MFA login challenge with a TOTP code or recovery code.

Request Body schema: application/json
required

MFA verification payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "bootstrap_admin": true,
  • "expiresAt": "string",
  • "mfa_methods": [
    ],
  • "mfa_token": "string",
  • "refreshToken": "string",
  • "requires_mfa": true,
  • "token": "string",
  • "user": {
    }
}

Begin passkey login

Create WebAuthn login options for a username-first passkey login flow.

Request Body schema: application/json
required

Username for passkey login

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "challenge_token": "string",
  • "options": null
}

Verify passkey login

Verify a passkey login assertion and issue session tokens.

Request Body schema: application/json
required

Passkey login verification payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "bootstrap_admin": true,
  • "expiresAt": "string",
  • "mfa_methods": [
    ],
  • "mfa_token": "string",
  • "refreshToken": "string",
  • "requires_mfa": true,
  • "token": "string",
  • "user": {
    }
}

Refresh access token

Generate a new access token using a valid refresh token

Request Body schema: application/json
required

Refresh token

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "bootstrap_admin": true,
  • "expiresAt": "string",
  • "mfa_methods": [
    ],
  • "mfa_token": "string",
  • "refreshToken": "string",
  • "requires_mfa": true,
  • "token": "string",
  • "user": {
    }
}

Register a new account

Create a new account from a username and password and issue session tokens. MFA (TOTP/passkey) is optional and added afterwards.

Request Body schema: application/json
required

Registration data

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "bootstrap_admin": true,
  • "expiresAt": "string",
  • "mfa_methods": [
    ],
  • "mfa_token": "string",
  • "refreshToken": "string",
  • "requires_mfa": true,
  • "token": "string",
  • "user": {
    }
}

capabilities

Get public runtime capabilities

Return a de-sensitized view of backend ML and LLM runtime capabilities without exposing secrets.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "llm": {
    },
  • "ml": {
    }
}

classifiers

Preview a zero-shot classifier

Embed positive/negative prompts with semantic and return library assets whose contrastive score exceeds the threshold. Used to tune prompts and thresholds before persisting a smart album. Requires the semantic embedding pipeline and a reachable semantic text-embed task.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Prompts and threshold

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "count": 0,
  • "matches": [
    ]
}

cloud

List cloud credentials

List configured cloud credentials without exposing secrets.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "credentials": [
    ]
}

Create cloud credential

Authenticate with a cloud provider and save a repo-reusable credential. Provider-specific challenges return auth_status=challenge_required.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Cloud credential

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "auth_status": "connected",
  • "challenge": {
    },
  • "credential": {
    }
}

Remove cloud credential

Permanently delete a cloud credential, its session data, and unbind associated repositories.

Authorizations:
BearerAuth
path Parameters
id
required
string

Credential UUID

Responses

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Verify cloud credential challenge

Submit challenge inputs to complete cloud credential creation.

Authorizations:
BearerAuth
path Parameters
id
required
string

Credential UUID

Request Body schema: application/json
required

Challenge inputs

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "auth_status": "connected",
  • "credential": {
    }
}

Disconnect cloud credential

Pause a cloud credential so it cannot start new imports. Can be reconnected later.

Authorizations:
BearerAuth
path Parameters
id
required
string

Credential UUID

Responses

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Reconnect cloud credential

Re-authenticate a disconnected or errored credential. If no password is provided, attempts to reuse the existing session.

Authorizations:
BearerAuth
path Parameters
id
required
string

Credential UUID

Request Body schema: application/json
required

Reconnect inputs

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "auth_status": "connected",
  • "challenge": {
    },
  • "credential": {
    }
}

Get cloud import run

Return a cloud import run by ID.

Authorizations:
BearerAuth
path Parameters
id
required
string

Import run UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "credential_id": "550e8400-e29b-41d4-a716-446655440000",
  • "downloaded_count": 80,
  • "error": "string",
  • "failed_count": 5,
  • "finished_at": "string",
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "imported_count": 75,
  • "provider": "icloud",
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "skipped_count": 40,
  • "started_at": "string",
  • "status": "running",
  • "total_seen": 120,
  • "updated_at": "string"
}

List cloud providers

List cloud provider descriptors for credential creation.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ]
}

Deprecated cloud sync endpoint

Deprecated. Use repo-scoped cloud import endpoints instead.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "error": "validation failed",
  • "message": "Bad request"
}

Get repository cloud status

Return cloud credential binding and latest import run for a repository.

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Responses

Response samples

Content type
application/json
{
  • "credential": {
    },
  • "enabled": true,
  • "last_import_run_id": "string",
  • "latest_run": {
    },
  • "provider": "icloud"
}

Start repository cloud import

Start an import run for the repository's configured cloud credential.

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Responses

Response samples

Content type
application/json
{
  • "run": {
    }
}

duplicates

Detect duplicates for a repository

Rebuilds the pending duplicate graph for a repository by combining exact-hash and pHash edges.

Request Body schema: application/json
required

Repository to scan

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "assets_affected": 18,
  • "exact_groups": 4,
  • "generated_at": "2026-05-12T08:23:45Z",
  • "groups": 7,
  • "mixed_groups": 1,
  • "phash_groups": 2
}

List duplicate groups

Paginated list of duplicate groups, scoped by repository and status (default pending).

query Parameters
repository_id
string

Repository UUID

status
string

pending | merged | dismissed (defaults to pending)

limit
integer
Default: 20

Page size

offset
integer
Default: 0

Page offset

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "limit": 20,
  • "offset": 0,
  • "total": 7
}

Get a duplicate group

Returns one duplicate group with all assets and evidence edges.

path Parameters
id
required
string

Duplicate group UUID

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "asset_count": 3,
  • "assets": [
    ],
  • "detected_at": "2026-05-12T08:23:45Z",
  • "detection_version": "duplicates-v2",
  • "edges": [
    ],
  • "group_id": "7c0a4220-1f15-4eb5-94e1-1f4b1d3e4f12",
  • "keeper_asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "method": "mixed",
  • "recommended_keeper_asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "recoverable_bytes": 10485760,
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "resolved_at": "2026-05-12T08:25:00Z",
  • "status": "pending",
  • "total_size": 15728640
}

Dismiss a duplicate group

Marks a duplicate group as dismissed without merging any assets.

path Parameters
id
required
string

Duplicate group UUID

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Merge a duplicate group

Keeps the chosen asset, unions metadata from duplicates, and soft-deletes the remaining members.

path Parameters
id
required
string

Duplicate group UUID

Request Body schema: application/json
required

Merge configuration

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "group_id": "7c0a4220-1f15-4eb5-94e1-1f4b1d3e4f12",
  • "keeper_asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "merged_duplicates": [
    ],
  • "recovered_bytes": 10485760
}

Get duplicate detection summary

Returns counts and recoverable space for pending duplicate groups, scoped by optional repository_id.

query Parameters
repository_id
string

Repository UUID to scope the summary

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "dismissed_groups": 0,
  • "last_detected_at": "2026-05-12T08:23:45Z",
  • "merged_groups": 2,
  • "pending_assets": 18,
  • "pending_groups": 7,
  • "recoverable_assets": 11,
  • "recoverable_bytes": 68157440
}

Health

Health check

Check if the server is healthy

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "status": "ok"
}

locations

Get location clusters

Return paginated persisted photo location clusters with cached labels when available.

query Parameters
limit
integer
Default: 100

Page size (1-1000)

offset
integer
Default: 0

Page offset

repository_id
string

Optional repository UUID filter

geohash
string

Optional geohash filter

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "clusters": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 150
}

Queue location cluster rebuild

Queue a location cluster rebuild for all photos or one repository.

Request Body schema: application/json

Rebuild request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "job_id": 123,
  • "message": "Location cluster rebuild queued successfully",
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "queued"
}

people

List people

List recognized people for the current repository scope.

query Parameters
repository_id
string

Optional repository UUID filter

limit
integer
Default: 24

Maximum number of results (max 100)

offset
integer
Default: 0

Number of results to skip

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "people": [
    ],
  • "total": 0
}

Get person

Get a single recognized person by cluster ID.

path Parameters
id
required
integer

Person ID

query Parameters
repository_id
string

Optional repository UUID filter

Responses

Response samples

Content type
application/json
{
  • "asset_count": 0,
  • "cover_face_image_path": "string",
  • "created_at": "string",
  • "is_confirmed": true,
  • "member_count": 0,
  • "name": "string",
  • "person_id": 0,
  • "representative_asset_id": "string",
  • "updated_at": "string"
}

Update person

Rename a recognized person. Successful updates mark the person as confirmed.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Person ID

query Parameters
repository_id
string

Optional repository UUID filter

Request Body schema: application/json
required

Person update payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "asset_count": 0,
  • "cover_face_image_path": "string",
  • "created_at": "string",
  • "is_confirmed": true,
  • "member_count": 0,
  • "name": "string",
  • "person_id": 0,
  • "representative_asset_id": "string",
  • "updated_at": "string"
}

List person assets

List assets scoped to a specific person while reusing the unified asset query filters.

path Parameters
id
required
integer

Person ID

Request Body schema: application/json
required

Asset query parameters

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 20,
  • "offset": 0,
  • "stack_mode": "collapsed",
  • "total_assets": 150,
  • "total_visible": 120
}

Get person cover

Serve the representative face crop image for a recognized person.

path Parameters
id
required
integer

Person ID

query Parameters
repository_id
string

Optional repository UUID filter

Responses

Rebuild people clusters

Rebuild recognized people for the selected repository scope using HDBSCAN over face embeddings.

Authorizations:
BearerAuth
query Parameters
repository_id
string

Optional repository UUID filter

Responses

Response samples

Content type
application/json
{
  • "algorithm": "string",
  • "candidate_faces": 0,
  • "clustered_faces": 0,
  • "clusters_created": 0,
  • "clusters_reused": 0,
  • "clusters_total": 0,
  • "duration_ms": 0,
  • "noise_faces": 0,
  • "repository_id": "string"
}

repositories

List repositories

Return all registered repositories.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "repositories": [
    ]
}

Create repository

Create a repository folder under the server storage root. If the target folder already contains a .lumiliorepo file, it is registered instead.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Repository name

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "cloud_import_error": "string",
  • "cloud_import_run_id": "string",
  • "repository": {
    }
}

Delete repository

Remove a repository from the registry. Does not delete files on disk.

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Responses

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Get repository

Return a single repository.

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Responses

Response samples

Content type
application/json
{
  • "default_owner_id": 0,
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "is_primary": false,
  • "local_settings": {
    },
  • "name": "Family Photos",
  • "path": "/data/storage/family-photos",
  • "role": "regular",
  • "storage_strategy": "date"
}

Update repository

Update mutable repository fields (name, storage_strategy, local_settings, default_owner_id).

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Request Body schema: application/json
required

Fields to update

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "default_owner_id": 0,
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "is_primary": false,
  • "local_settings": {
    },
  • "name": "Family Photos",
  • "path": "/data/storage/family-photos",
  • "role": "regular",
  • "storage_strategy": "date"
}

Queue repository scan

Queue a manual scan for a repository free workspace.

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Request Body schema: application/json

Scan request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "job_id": 12345,
  • "mode": "manual",
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "queued"
}

List repository scans

List recent scan runs for a repository.

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

query Parameters
limit
integer
Default: 20

Limit

offset
integer
Default: 0

Offset

Responses

Response samples

Content type
application/json
{
  • "scans": [
    ]
}

Get latest repository scan

Return the latest scan run for a repository.

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Responses

Response samples

Content type
application/json
{
  • "deleted_count": 1,
  • "discovered_count": 10,
  • "error": "string",
  • "finished_at": "string",
  • "mode": "manual",
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "requested_by": "edwin",
  • "scan_id": "550e8400-e29b-41d4-a716-446655440000",
  • "skipped_count": 4,
  • "started_at": "string",
  • "status": "completed",
  • "updated_count": 2
}

Auto-detect stacks

Scans a repository for RAW+JPEG pairs and creates stacks automatically

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository ID

Responses

Response samples

Content type
application/json
{
  • "repository_id": "string",
  • "stacks_created": 0
}

settings

Get runtime info

Read-only effective runtime-immutable configuration (changed only via TOML + restart).

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "environment": "production",
  • "geocoding_provider": "disabled",
  • "hardware_accel": "none",
  • "log_level": "info",
  • "lumen_discovery_enabled": true,
  • "repository_scan_enabled": true,
  • "repository_scan_interval_seconds": 300,
  • "server_port": "8080",
  • "storage_root": "/data/storage"
}

Get system settings

Return persisted system settings without exposing secret values.

Authorizations:
BearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "llm": {
    },
  • "ml": {
    },
  • "updated_at": "string",
  • "updated_by": 0
}

Update system settings

Update persisted system settings. API keys are write-only and never returned.

Authorizations:
BearerAuth
Request Body schema: application/json
required

System settings patch

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "llm": {
    },
  • "ml": {
    },
  • "updated_at": "string",
  • "updated_by": 0
}

Validate LLM settings

Validate the persisted LLM configuration by issuing a lightweight test request.

Authorizations:
BearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "valid": true
}

setup

Initialize the system

Run first-run bootstrapping: generate and rotate the database credential, then persist the secret. Refused once the system is already initialized.

Request Body schema: application/json

Optional empty setup payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "database_user": "string",
  • "password_length": 0
}

Get system setup status

Report whether Lumilio has rotated the temporary database credential. The web frontend runs setup as a preflight while uninitialized.

Responses

Response samples

Content type
application/json
{
  • "admin_initialized": true,
  • "database_initialized": true,
  • "initialized": true,
  • "next_registration_role": "string",
  • "primary_repository_initialized": true,
  • "repository_defaults": {
    }
}

species

Get species reference

Fetch a species wiki summary and reference image from iNaturalist by scientific name, with optional common name fallback.

query Parameters
scientific_name
string
Example: scientific_name="Rucervus duvaucelii"

Scientific name

common_name
string
Example: common_name="Barasingha"

Common name fallback

locale
string
Example: locale="zh"

iNaturalist locale for localized common names and wiki summaries

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{}

stats

Get available years

Get list of years that have photo data

query Parameters
repository_id
string

Optional repository UUID filter

Responses

Response samples

Content type
application/json
{
  • "years": [
    ]
}

Get camera lens combination stats

Get top N camera+lens combinations

query Parameters
limit
integer
Default: 20

Number of results to return

repository_id
string

Optional repository UUID filter

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": 0
}

Get daily activity heatmap

Get daily shooting activity heatmap data for a calendar year or custom date range.

query Parameters
year
integer

Calendar year (e.g. 2024)

start_date
string

Start date in YYYY-MM-DD (must be used with end_date)

end_date
string

End date in YYYY-MM-DD, inclusive (must be used with start_date)

days
integer

Deprecated fallback: number of days to look back (used only when year/start_date/end_date are absent)

repository_id
string

Optional repository UUID filter

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get focal length distribution

Get distribution of commonly used focal lengths

query Parameters
repository_id
string

Optional repository UUID filter

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": 0
}

Get time distribution

Get shooting time distribution by hour or month

query Parameters
type
string
Default: "hourly"
Enum: "hourly" "monthly"

Distribution type: hourly or monthly

repository_id
string

Optional repository UUID filter

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "type": "string"
}

users

List users

List users with ownership statistics for administrator management views.

Authorizations:
BearerAuth
query Parameters
limit
integer
Default: 20

Maximum number of results

offset
integer
Default: 0

Number of results to skip

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "total": 0,
  • "users": [
    ]
}

Update user

Update user identity, role, status, and avatar fields as an administrator.

Authorizations:
BearerAuth
path Parameters
id
required
integer

User ID

Request Body schema: application/json
required

User update payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "avatar_asset_id": "string",
  • "created_at": "string",
  • "display_name": "string",
  • "is_active": true,
  • "last_login": "string",
  • "permissions": [
    ],
  • "role": "string",
  • "updated_at": "string",
  • "user_id": 0,
  • "username": "string"
}

Reset user access

Generate a temporary password and clear passkeys, TOTP, recovery codes, and refresh tokens for a user.

Authorizations:
BearerAuth
path Parameters
id
required
integer

User ID

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "cleared_passkeys": true,
  • "cleared_totp": true,
  • "temporary_password": "string"
}

Change my password

Verify the current password, set a new password, and revoke all refresh tokens for the current user.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Password change payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Update my profile

Update the current user's profile fields such as display name and avatar photo.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Profile update payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "avatar_asset_id": "string",
  • "created_at": "string",
  • "display_name": "string",
  • "is_active": true,
  • "last_login": "string",
  • "permissions": [
    ],
  • "role": "string",
  • "updated_at": "string",
  • "user_id": 0,
  • "username": "string"
}