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
{ }

Cancel Agent Chat

Request Body schema: application/json
required

Cancel request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "run_id": "string",
  • "status": "cancel_requested",
  • "thread_id": "string"
}

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
{ }

Get Agent Effect Status

path Parameters
id
required
string

Effect ID

query Parameters
thread_id
required
string

Thread that owns the effect

Responses

Response samples

Content type
application/json
{
  • "effect_id": "string",
  • "receipt": {
    },
  • "status": "pending"
}

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",
  • "facets": {
    },
  • "fallback_reason": "string",
  • "hydration_source": "live_replay",
  • "last_successful_refresh_at": "string",
  • "layout": {
    },
  • "mode": "frozen",
  • "pin_id": "7d4df41e-9aa2-4d44-9a3d-111111111111",
  • "summary": "string",
  • "title": "Kyoto 2025",
  • "truncated": true,
  • "widget": "cover_card"
}

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 Metadata

Get metadata and facet summary for a pinned widget. Frozen pins serve the stored snapshot; live pins replay their plan before facets are computed.

path Parameters
id
required
string

Pin ID

Responses

Response samples

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

Update Agent Pin

Patch one pinned widget. Send title to rename it, widget to switch which view it renders through; both are optional.

path Parameters
id
required
string

Pin ID

Request Body schema: application/json
required

Pin update

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

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
}

Query Agent Pin Assets

Query a pinned widget with the same list/filter/sort semantics as the assets gallery. Snapshot-order hydration remains available through GET /agent/pins/{id}/assets.

path Parameters
id
required
string

Pin ID

Request Body schema: application/json
required

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_files": 213,
  • "total_media_items": 150,
  • "total_visible": 120
}

Search Agent Pin Assets

Search a pinned widget with optional top results enhancement and filename fallback, constrained to the pin's asset set.

path Parameters
id
required
string

Pin ID

Request Body schema: application/json
required

Search parameters

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

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 the agent tools visible in the given quick-action mode. An empty or unknown mode returns the full toolset.

query Parameters
mode
string
Enum: "review" "organize" "analyze" "curate"

Quick-action mode

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.

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, BioCLIP Species Recognition predictions, OCR Text Recognition results, Person Recognition results, 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 Text Recognition results

include_faces
boolean
Default: false

Include Person Recognition results

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 logical media item

Returns the logical media item and its RAW/JPEG, Live Photo, or edited components

Authorizations:
BearerAuth
path Parameters
id
required
string

Asset ID

Responses

Response samples

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

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.StudioCanvasDTO)
Array of objects (dto.StudioLayerDTO)
object (dto.LumilioSidecarSourceDTO)
updated_at
string
version
integer

Responses

Request samples

Content type
application/json
{
  • "adjustments": {
    },
  • "asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "canvas": {
    },
  • "layers": [
    ],
  • "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 tags

Get all tags (manual and AI-generated) attached to an asset

path Parameters
id
required
string

Asset ID

Responses

Response samples

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

Add a manual tag to an asset

Resolve (creating if needed) a tag by name and link it to the asset with the manual source

path Parameters
id
required
string

Asset ID

Request Body schema: application/json
required

Tag to add

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "confidence": 0,
  • "source": "string",
  • "tag_id": 0,
  • "tag_name": "string"
}

Remove a tag from an asset

Unlink a tag from an asset by tag ID

path Parameters
id
required
string

Asset ID

tagId
required
integer

Tag ID

Responses

Response samples

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

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 materialization status

Get backend ingest lifecycle state for upload task IDs owned by the current caller

query Parameters
task_ids
required
string

Comma-separated upload task IDs

Responses

Response samples

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

Stream upload materialization status

query Parameters
task_ids
required
string

Comma-separated upload task IDs

Responses

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": {
    }
}

Create or resume an upload session

Request Body schema: application/json
required

Upload metadata

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "bytes_received": 0,
  • "received_chunks": [
    ],
  • "session_id": "string",
  • "status": "string",
  • "task_id": 0,
  • "total_chunks": 0
}

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": [
    ]
}

List folder summaries

List immediate child folders of a repository-relative path, with recursive asset counts and covers, for the Folders collection view

query Parameters
repository_id
string

Optional repository UUID filter

path
string

Repository-relative parent folder path (empty for root)

Responses

Response samples

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

Get one folder summary

Get recursive asset counts, date range, and cover for one repository-relative folder path, for the Folder detail header

query Parameters
repository_id
required
string

Repository UUID

path
string

Repository-relative folder path (empty for root)

Responses

Response samples

Content type
application/json
{
  • "asset_count": 128,
  • "audio_count": 0,
  • "cover_asset_id": "550e8400-e29b-41d4-a716-446655440000",
  • "date_end": "string",
  • "date_start": "string",
  • "depth": 3,
  • "display_name": "05",
  • "folder_path": "inbox/2026/05",
  • "photo_count": 110,
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "repository_name": "Primary Repository",
  • "video_count": 18
}

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
reset_semantic
boolean

ResetSemantic wipes all semantic vectors and rebuilds from scratch. Use after switching the embedding model (drop+refill) so no two models' vectors are mixed. Honored only when the semantic task is included.

tasks
Array of strings

Responses

Request samples

Content type
application/json
{
  • "limit": 200,
  • "missing_only": true,
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "reset_semantic": false,
  • "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 repositories for scope selection

Return the shared repository registry for browse-scope/upload selectors and indexing filters. Paths are only included for admins.

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": {
    },
  • "video_total": 120
}

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_files": 213,
  • "total_media_items": 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

south
number

Viewport south latitude (-90 to 90)

north
number

Viewport north latitude (-90 to 90)

west
number

Viewport west longitude (-180 to 180)

east
number

Viewport east longitude (-180 to 180)

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
}

Precheck uploads against existing content fingerprints

Given client-computed BLAKE3 fingerprints, reports advisory candidates. Candidates must still be uploaded for server-side full-file verification.

Request Body schema: application/json
required

Candidate files

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

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"
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",
  • "top_results_limit": 200,
  • "viewer_timezone": "America/New_York"
}

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "result_items": [
    ],
  • "results_total_media_items": 150,
  • "results_total_visible": 120,
  • "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": "burst"
}

List tag summaries

List manual and AI/system tags with usage counts and covers, for the Tags collection view

query Parameters
repository_id
string

Optional repository UUID filter

source
string

Optional tag source filter (e.g. manual, zeroshot)

q
string

Search query (substring match on tag name)

limit
integer
Default: 50

Max results

offset
integer
Default: 0

Result offset

Responses

Response samples

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

List/search tags

List all tags or search by name for autocomplete suggestions

query Parameters
q
string

Search query (substring match)

limit
integer
Default: 20

Max results

Responses

Response samples

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

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

Get browser authentication capabilities

Report whether this request origin can use passkeys for the configured canonical origin.

Responses

Response samples

Content type
application/json
{
  • "current_origin": "http://192.168.1.20:6680",
  • "insecure_transport": true,
  • "passkey_available": false,
  • "passkey_unavailable_reason": "disabled"
}

Get refresh-session CSRF token

Return a CSRF token bound to the current HttpOnly refresh cookie

Responses

Response samples

Content type
application/json
{
  • "csrfToken": "string"
}

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,
  • "csrfToken": "string",
  • "expiresAt": "string",
  • "mfa_methods": [
    ],
  • "mfa_token": "string",
  • "password_change_token": "string",
  • "requires_mfa": true,
  • "requires_password_change": true,
  • "token": "string",
  • "user": {
    }
}

Probe login options

Identifier-first capability probe. Always returns password:true for valid usernames; passkey:true only when the active account has at least one passkey. Does not reveal TOTP enrollment. Unknown and inactive usernames match the password-only shape.

Request Body schema: application/json
required

Username to probe

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "passkey": false,
  • "password": true
}

Logout user

Revoke and clear the current HttpOnly refresh-cookie session

Responses

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,
  • "csrfToken": "string",
  • "expiresAt": "string",
  • "mfa_methods": [
    ],
  • "mfa_token": "string",
  • "password_change_token": "string",
  • "requires_mfa": true,
  • "requires_password_change": 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,
  • "csrfToken": "string",
  • "expiresAt": "string",
  • "mfa_methods": [
    ],
  • "mfa_token": "string",
  • "password_change_token": "string",
  • "requires_mfa": true,
  • "requires_password_change": true,
  • "token": "string",
  • "user": {
    }
}

Complete required password change

Replace a temporary reset password using the short-lived token returned by login.

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
{
  • "bootstrap_admin": true,
  • "csrfToken": "string",
  • "expiresAt": "string",
  • "mfa_methods": [
    ],
  • "mfa_token": "string",
  • "password_change_token": "string",
  • "requires_mfa": true,
  • "requires_password_change": true,
  • "token": "string",
  • "user": {
    }
}

Refresh access token

Rotate the HttpOnly refresh cookie and issue a new access token. Requires X-CSRF-Token bound to the current cookie session.

Responses

Response samples

Content type
application/json
{
  • "bootstrap_admin": true,
  • "csrfToken": "string",
  • "expiresAt": "string",
  • "mfa_methods": [
    ],
  • "mfa_token": "string",
  • "password_change_token": "string",
  • "requires_mfa": true,
  • "requires_password_change": 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,
  • "csrfToken": "string",
  • "expiresAt": "string",
  • "mfa_methods": [
    ],
  • "mfa_token": "string",
  • "password_change_token": "string",
  • "requires_mfa": true,
  • "requires_password_change": 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 Image Semantic Analysis and return catalog 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 the current user's cloud credentials without exposing secrets. Administrators receive all credentials.

Authorizations:
BearerAuth

Responses

Response samples

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

Create cloud credential

Authenticate with a cloud provider and save a user-owned, 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,
  • "owner_id": 123,
  • "provider": "icloud",
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "skipped_count": 40,
  • "started_at": "string",
  • "status": "running",
  • "total_seen": 120,
  • "updated_at": "string"
}

Cancel cloud import run

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,
  • "owner_id": 123,
  • "provider": "icloud",
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "skipped_count": 40,
  • "started_at": "string",
  • "status": "running",
  • "total_seen": 120,
  • "updated_at": "string"
}

Resume cloud import run

Authorizations:
BearerAuth
path Parameters
id
required
string

Import run UUID

Responses

Response samples

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

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": {
    },
  • "owner_id": 123,
  • "provider": "icloud",
  • "sources": [
    ]
}

Start repository cloud import

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

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Request Body schema: application/json

Cloud source selection

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

Bind a cloud source to a repository

Bind one user-owned credential plus remote scope to an existing repository and start an independent import run.

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Request Body schema: application/json
required

Cloud source

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

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
}

events

List Events

List owner-scoped Events, optionally projecting membership counts and covers to one repository.

query Parameters
repository_id
string

Optional repository UUID filter

include_hidden
boolean
Default: false

Include Events hidden from the default grid

limit
integer

Page size

cursor
string

Opaque cursor

Responses

Response samples

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

Get Event

path Parameters
id
required
string

Event UUID

query Parameters
repository_id
string

Optional repository Browse Scope

Responses

Response samples

Content type
application/json
{
  • "algorithm_version": "string",
  • "canonical_media_count": 0,
  • "cover_asset_id": "string",
  • "cover_media_item_id": "string",
  • "displayable_count": 0,
  • "end_at": 0,
  • "event_id": "550e8400-e29b-41d4-a716-446655440000",
  • "is_hidden": true,
  • "media_count": 0,
  • "pending_rebuild": true,
  • "projected_media_count": 0,
  • "redirected_from": "string",
  • "start_at": 0,
  • "timezone": "string",
  • "title_override": "string"
}

Update Event

path Parameters
id
required
string

Event UUID

Request Body schema: application/json
required

Event changes

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "event": {
    },
  • "pending_rebuild": true
}

Get Event assets

path Parameters
id
required
string

Event UUID

query Parameters
repository_id
string

Optional repository Browse Scope

limit
integer

Page size

Responses

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "next_cursor": "string",
  • "omitted_members": 0
}

Add Event members

path Parameters
id
required
string

Event UUID

Request Body schema: application/json
required

Assets to add

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "event": {
    },
  • "pending_rebuild": true
}

Remove Event member

path Parameters
id
required
string

Event UUID

mediaItemId
required
string

Media item UUID

Responses

Response samples

Content type
application/json
{
  • "event": {
    },
  • "pending_rebuild": true
}

Get Event relations

path Parameters
id
required
string

Event UUID

Responses

Response samples

Content type
application/json
{
  • "complete": true,
  • "relations": [
    ],
  • "source_version": "string"
}

Share Event

path Parameters
id
required
string

Event UUID

Request Body schema: application/json
required

Share options

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "allow_download": true,
  • "asset_count": 0,
  • "created_at": "string",
  • "description": "string",
  • "expires_at": "string",
  • "include_originals": true,
  • "last_viewed_at": "string",
  • "revoked_at": "string",
  • "share_id": "550e8400-e29b-41d4-a716-446655440000",
  • "source_kind": "asset_snapshot",
  • "source_ref": "string",
  • "status": "active",
  • "title": "string",
  • "token": "7yQhF3z9k2mN8pXeR5tVwL1sJ4bC6dA0",
  • "updated_at": "string",
  • "view_count": 0
}

Split Event

path Parameters
id
required
string

Event UUID

Request Body schema: application/json
required

Split request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "event": {
    },
  • "pending_rebuild": true
}

Merge Events

Request Body schema: application/json
required

Merge request

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "event": {
    },
  • "pending_rebuild": true
}

Rebuild Events

Request Body schema: application/json
required

Rebuild options

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "owner_id": 0,
  • "requested_revision": 0,
  • "run_id": "string"
}

Set Event rebuild state

Request Body schema: application/json
required

Rebuild state

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "algorithm_version": "string",
  • "initialized": true,
  • "last_error_code": "string",
  • "last_failure_run_id": "string",
  • "last_success_run_id": "string",
  • "paused": true,
  • "pending": true,
  • "pending_ranges": 0,
  • "published_revision": 0,
  • "queued_run_id": "string",
  • "revision": 0,
  • "running_run_id": "string",
  • "source_revision": 0
}

Get Event rebuild status

Responses

Response samples

Content type
application/json
{
  • "algorithm_version": "string",
  • "initialized": true,
  • "last_error_code": "string",
  • "last_failure_run_id": "string",
  • "last_success_run_id": "string",
  • "paused": true,
  • "pending": true,
  • "pending_ranges": 0,
  • "published_revision": 0,
  • "queued_run_id": "string",
  • "revision": 0,
  • "running_run_id": "string",
  • "source_revision": 0
}

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"
}

host-actions

List unfinished native host actions

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Request a native host storage action

Creates a persistent, expiring task. Filesystem paths and approval nonces never enter this HTTP request or response.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string

Stable request identifier

Request Body schema: application/json
required

Native host action

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "actor": "web:user:1",
  • "completed_at": "string",
  • "created_at": "string",
  • "error_code": "expired",
  • "error_message": "Native host approval expired",
  • "expected_version": 0,
  • "expires_at": "string",
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "kind": "open_repository",
  • "name": "External Archive",
  • "purpose": "Open an existing photo repository",
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "request_id": "web-host-action-4d4d",
  • "result": {
    },
  • "root_id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "pending",
  • "updated_at": "string"
}

Cancel native host action

Authorizations:
BearerAuth
path Parameters
id
required
string

Host action ID

Responses

Response samples

Content type
application/json
{
  • "actor": "web:user:1",
  • "completed_at": "string",
  • "created_at": "string",
  • "error_code": "expired",
  • "error_message": "Native host approval expired",
  • "expected_version": 0,
  • "expires_at": "string",
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "kind": "open_repository",
  • "name": "External Archive",
  • "purpose": "Open an existing photo repository",
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "request_id": "web-host-action-4d4d",
  • "result": {
    },
  • "root_id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "pending",
  • "updated_at": "string"
}

Get native host action

Authorizations:
BearerAuth
path Parameters
id
required
string

Host action ID

Responses

Response samples

Content type
application/json
{
  • "actor": "web:user:1",
  • "completed_at": "string",
  • "created_at": "string",
  • "error_code": "expired",
  • "error_message": "Native host approval expired",
  • "expected_version": 0,
  • "expires_at": "string",
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "kind": "open_repository",
  • "name": "External Archive",
  • "purpose": "Open an existing photo repository",
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "request_id": "web-host-action-4d4d",
  • "result": {
    },
  • "root_id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "pending",
  • "updated_at": "string"
}

Resolve native host action conflict

Authorizations:
BearerAuth
path Parameters
id
required
string

Host action ID

Request Body schema: application/json
required

Recovery decision

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "actor": "web:user:1",
  • "completed_at": "string",
  • "created_at": "string",
  • "error_code": "expired",
  • "error_message": "Native host approval expired",
  • "expected_version": 0,
  • "expires_at": "string",
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "kind": "open_repository",
  • "name": "External Archive",
  • "purpose": "Open an existing photo repository",
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "request_id": "web-host-action-4d4d",
  • "result": {
    },
  • "root_id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "pending",
  • "updated_at": "string"
}

Get native host capability

Authorizations:
BearerAuth

Responses

Response samples

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

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

include_hidden
boolean
Default: false

Include people hidden from the default grid

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",
  • "hidden_at": "string",
  • "is_confirmed": true,
  • "is_hidden": 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

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",
  • "hidden_at": "string",
  • "is_confirmed": true,
  • "is_hidden": 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_files": 213,
  • "total_media_items": 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

Set person cover

Set the representative cover face for a person. The face must belong to the person.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Person ID

Request Body schema: application/json
required

Cover payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

Get a Person's Events

path Parameters
id
required
integer

Person ID

Responses

Response samples

Content type
application/json
{
  • "complete": true,
  • "relations": [
    ],
  • "source_version": "string"
}

List person faces

List the individual face crops assigned to a person for correction workflows.

path Parameters
id
required
integer

Person ID

query Parameters
repository_id
string

Optional repository UUID filter

limit
integer
Default: 60

Maximum number of results (max 200)

offset
integer
Default: 0

Number of results to skip

Responses

Response samples

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

Get person face crop

Serve the face crop image for a single face belonging to a person.

path Parameters
id
required
integer

Person ID

faceId
required
integer

Face ID

query Parameters
repository_id
string

Optional repository UUID filter

Responses

Move face to another person

Reassign a single face from this person to another person as a manual correction.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Source person ID

faceId
required
integer

Face ID

Request Body schema: application/json
required

Move payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

Remove face from person

Detach a face from this person, leaving the original asset unchanged.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Person ID

faceId
required
integer

Face ID

Responses

Response samples

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

Set person hidden

Hide or unhide a person from the default people grid. Faces, assets and names are preserved.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Person ID

Request Body schema: application/json
required

Hidden payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

Merge people

Merge one or more source people into the target person. Assets remain in the Lumilio catalog and corrections become manual.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Target person ID

Request Body schema: application/json
required

Merge payload

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

Get Person relations

path Parameters
id
required
integer

Person ID

query Parameters
relation
required
string
Value: "co_occurs_with"

Relation type

Responses

Response samples

Content type
application/json
{
  • "complete": true,
  • "relations": [
    ],
  • "source_version": "string"
}

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"
}

public-shares

Get public share metadata

Get a public share's de-sensitized metadata (title, asset count, expiry, download policy). Records one view.

path Parameters
token
required
string

Share token

Responses

Response samples

Content type
application/json
{
  • "allow_download": true,
  • "asset_count": 0,
  • "created_at": "string",
  • "description": "string",
  • "expires_at": "string",
  • "include_originals": true,
  • "title": "string"
}

Get public share original file

Serve the original file for an asset that belongs to this share. Requires allow_download and include_originals to both be enabled.

path Parameters
token
required
string

Share token

assetId
required
string

Asset ID

Responses

Get public share asset thumbnail

Serve a thumbnail for an asset that belongs to this share.

path Parameters
token
required
string

Share token

assetId
required
string

Asset ID

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

Thumbnail size

Responses

Get public share asset web audio

Serve the web-optimized audio for an asset that belongs to this share.

path Parameters
token
required
string

Share token

assetId
required
string

Asset ID

Responses

Get public share asset web video

Serve the web-optimized video for an asset that belongs to this share.

path Parameters
token
required
string

Share token

assetId
required
string

Asset ID

Responses

List public share assets

Browse a public share's assets in date order. v1 is browse-only: no filter/search/sort.

path Parameters
token
required
string

Share token

Request Body schema: application/json
required

Pagination

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

Download public share

Serve the share's original files (optionally scoped to a subset via asset_ids) as a zip archive. Requires allow_download to be enabled.

path Parameters
token
required
string

Share token

Request Body schema: application/json

Optional asset ID subset

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

repositories

List repositories

Return all registered repositories.

Authorizations:
BearerAuth

Responses

Response samples

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

Create repository

Create a repository in an explicit direct-child storage folder below a registered Storage Location. Empty root_id selects the configured default. Existing .lumiliorepo targets are returned as structured recovery facts and are never opened implicitly.

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
{
  • "repository": {
    },
  • "warnings": [
    ]
}

Remove repository registration

Remove a non-primary repository and its catalog/index/task state after an exact repository-name confirmation. Original media, marker, and private files remain on disk.

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Request Body schema: application/json
required

Exact repository-name confirmation

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

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
{
  • "activity": "idle",
  • "default_owner_id": 0,
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "is_primary": false,
  • "local_settings": {
    },
  • "name": "Family Photos",
  • "path": "/data/storage/Family Photos",
  • "reachability": "active",
  • "role": "regular",
  • "root_id": "550e8400-e29b-41d4-a716-446655440000",
  • "storage_strategy": "date"
}

Preview repository removal

Return the catalog, album, queued-work, and private-state impact of removing a non-primary repository registration. Files on disk are always preserved.

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Responses

Response samples

Content type
application/json
{
  • "active_task_count": 0,
  • "album_count": 12,
  • "asset_count": 1240,
  • "catalog_media_bytes": 4294967296,
  • "cloud_import_count": 2,
  • "files_preserved": true,
  • "private_state_bytes": 1048576,
  • "private_state_found": true,
  • "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  • "repository_name": "Family Photos"
}

Rename repository

Change the display name without changing identity, path, storage strategy, duplicate handling, owner, role, or root.

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository UUID

Request Body schema: application/json
required

New display name

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "activity": "idle",
  • "default_owner_id": 0,
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "is_primary": false,
  • "local_settings": {
    },
  • "name": "Family Photos",
  • "path": "/data/storage/Family Photos",
  • "reachability": "active",
  • "role": "regular",
  • "root_id": "550e8400-e29b-41d4-a716-446655440000",
  • "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
{
  • "ambiguous_count": 0,
  • "authoritative": true,
  • "deferred_count": 1,
  • "deleted_count": 1,
  • "discovered_count": 10,
  • "error": "string",
  • "finished_at": "string",
  • "mode": "manual",
  • "moved_count": 1,
  • "partial_reason": "string",
  • "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

Merges RAW/JPEG and Live Photo components into logical media items, then detects burst presentation stacks

Authorizations:
BearerAuth
path Parameters
id
required
string

Repository ID

Responses

Response samples

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

List repository lifecycle audit events

Authorizations:
BearerAuth
query Parameters
limit
integer

Maximum events (1-200)

offset
integer

Pagination offset

Responses

Response samples

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

Get Storage Location and repository diagnostics

Authorizations:
BearerAuth

Responses

Response samples

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

Download a path-redacted storage support bundle

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "audit_events": [
    ],
  • "diagnostics": [
    ],
  • "generated_at": "string",
  • "paths_redacted": true
}

List repository candidates

Returns bounded direct-child facts for standalone and Docker workflows without accepting arbitrary filesystem paths.

Authorizations:
BearerAuth

Responses

Response samples

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

Open repository candidate

Opens a valid .lumiliorepo by portable directory name. Prior repository-private state is isolated before an authoritative initial scan.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string

Stable request identifier

Request Body schema: application/json
required

Repository candidate

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

Resolve repository candidate identity

Resolves a same-identity direct child using user-facing decisions; no arbitrary filesystem path is accepted.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string

Stable request identifier

Request Body schema: application/json
required

Repository candidate decision

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

List Storage Locations

Return registered repository roots with their current reachability. Filesystem paths are admin-only through this route.

Authorizations:
BearerAuth

Responses

Response samples

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

Remove Storage Location registration

Remove an empty, idle external Storage Location from Lumilio. The directory, .lumilioroot marker, and every disk file are preserved.

Authorizations:
BearerAuth
path Parameters
id
required
string

Storage Location UUID

Responses

Response samples

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

settings

Get database restore operation

Return the latest durable phase for an accepted restore operation, including completion or successful rollback after a runtime restart.

Authorizations:
BearerAuth
path Parameters
id
required
string

Restore operation ID

Responses

Response samples

Content type
application/json
{
  • "backup_name": "20260711T020000.000000Z-library.sqlite3",
  • "completed_at": "string",
  • "error_code": "string",
  • "id": "d62cbbf3-f564-458b-86ca-0f6d10fcd8d4",
  • "message": "string",
  • "requested_at": "string",
  • "restore_point": "string",
  • "status": "staged",
  • "updated_at": "string"
}

Get latest database restore operation

Return the latest durable restore receipt, if one exists.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "backup_name": "20260711T020000.000000Z-library.sqlite3",
  • "completed_at": "string",
  • "error_code": "string",
  • "id": "d62cbbf3-f564-458b-86ca-0f6d10fcd8d4",
  • "message": "string",
  • "requested_at": "string",
  • "restore_point": "string",
  • "status": "staged",
  • "updated_at": "string"
}

List database backups

List SQLite snapshots (routine backups and restore points), newest first.

Authorizations:
BearerAuth

Responses

Response samples

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

Create a database backup now

Enqueue an immediate SQLite snapshot; it appears in the list when the job finishes.

Authorizations:
BearerAuth

Responses

Response samples

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

Delete a database backup

Delete one SQLite snapshot and its manifest from the backups directory.

Authorizations:
BearerAuth
path Parameters
name
required
string

Backup file name

Responses

Response samples

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

Download a database backup

Download one standalone SQLite snapshot.

Authorizations:
BearerAuth
path Parameters
name
required
string

Backup file name

Responses

Restore a database backup

Validate and stage the named SQLite snapshot. The accepted operation continues across a runtime restart; poll the returned operation ID for completion or rollback.

Authorizations:
BearerAuth
path Parameters
name
required
string

Backup file name

Responses

Response samples

Content type
application/json
{
  • "backup_name": "20260711T020000.000000Z-library.sqlite3",
  • "completed_at": "string",
  • "error_code": "string",
  • "id": "d62cbbf3-f564-458b-86ca-0f6d10fcd8d4",
  • "message": "string",
  • "requested_at": "string",
  • "restore_point": "string",
  • "status": "staged",
  • "updated_at": "string"
}

Get runtime info

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

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "acme_certificate_expires_at": "string",
  • "acme_certificate_hostname": "photos.example.com",
  • "acme_certificate_status": "active",
  • "acme_last_managed_at": "string",
  • "environment": "production",
  • "geocoding_provider": "disabled",
  • "hardware_accel": "none",
  • "log_level": "info",
  • "lumen_discovery_enabled": true,
  • "passkey_enabled": true,
  • "repository_scan_enabled": true,
  • "repository_scan_interval_seconds": 300,
  • "server_listen": "0.0.0.0:6680",
  • "storage_root": "/data/storage",
  • "tls_mode": "off"
}

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
{
  • "backup": {
    },
  • "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
{
  • "backup": {
    },
  • "llm": {
    },
  • "ml": {
    },
  • "updated_at": "string",
  • "updated_by": 0
}

Validate an LLM settings draft

Validate the supplied provider/model draft without saving it or returning secret material.

Authorizations:
BearerAuth
Request Body schema: application/json
required

LLM settings draft

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

setup

Get system setup status

Report whether the first owner and primary repository have been created.

Responses

Response samples

Content type
application/json
{
  • "admin_initialized": true,
  • "initialized": true,
  • "next_registration_role": "string",
  • "primary_repository_initialized": true,
  • "repository_defaults": {
    },
  • "runtime_reason": "storage_recovery_required",
  • "runtime_state": "active"
}

List share links

List all share links owned by the current user, newest first.

Authorizations:
BearerAuth

Responses

Response samples

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

Create a share link

Resolve a source into an asset snapshot and create a revocable, time-limited public share link. The raw token is returned only in this response.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Share link creation data

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "allow_download": true,
  • "asset_count": 0,
  • "created_at": "string",
  • "description": "string",
  • "expires_at": "string",
  • "include_originals": true,
  • "last_viewed_at": "string",
  • "revoked_at": "string",
  • "share_id": "550e8400-e29b-41d4-a716-446655440000",
  • "source_kind": "asset_snapshot",
  • "source_ref": "string",
  • "status": "active",
  • "title": "string",
  • "token": "7yQhF3z9k2mN8pXeR5tVwL1sJ4bC6dA0",
  • "updated_at": "string",
  • "view_count": 0
}

Delete a share link

Permanently remove a share link record. Only expired or revoked links may be deleted.

Authorizations:
BearerAuth
path Parameters
id
required
string

Share ID

Responses

Response samples

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

Get a share link

Get one share link's metadata (never the token).

Authorizations:
BearerAuth
path Parameters
id
required
string

Share ID

Responses

Response samples

Content type
application/json
{
  • "allow_download": true,
  • "asset_count": 0,
  • "created_at": "string",
  • "description": "string",
  • "expires_at": "string",
  • "include_originals": true,
  • "last_viewed_at": "string",
  • "revoked_at": "string",
  • "share_id": "550e8400-e29b-41d4-a716-446655440000",
  • "source_kind": "asset_snapshot",
  • "source_ref": "string",
  • "status": "active",
  • "title": "string",
  • "updated_at": "string",
  • "view_count": 0
}

Update a share link

Patch a share link's title/description/download settings, and/or extend its expiry by extend_days.

Authorizations:
BearerAuth
path Parameters
id
required
string

Share ID

Request Body schema: application/json
required

Share link update

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "allow_download": true,
  • "asset_count": 0,
  • "created_at": "string",
  • "description": "string",
  • "expires_at": "string",
  • "include_originals": true,
  • "last_viewed_at": "string",
  • "revoked_at": "string",
  • "share_id": "550e8400-e29b-41d4-a716-446655440000",
  • "source_kind": "asset_snapshot",
  • "source_ref": "string",
  • "status": "active",
  • "title": "string",
  • "updated_at": "string",
  • "view_count": 0
}

Revoke a share link

Immediately disable public access for a share link.

Authorizations:
BearerAuth
path Parameters
id
required
string

Share ID

Responses

Response samples

Content type
application/json
{
  • "allow_download": true,
  • "asset_count": 0,
  • "created_at": "string",
  • "description": "string",
  • "expires_at": "string",
  • "include_originals": true,
  • "last_viewed_at": "string",
  • "revoked_at": "string",
  • "share_id": "550e8400-e29b-41d4-a716-446655440000",
  • "source_kind": "asset_snapshot",
  • "source_ref": "string",
  • "status": "active",
  • "title": "string",
  • "updated_at": "string",
  • "view_count": 0
}

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, require a password change on next login, invalidate existing sessions, and clear passkeys, TOTP, and recovery codes 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"
}