API docs by Redocly

Lumilio-Photos Manager API (1.0)

Download OpenAPI specification:

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

Photo management system API with asset upload, processing, and organization features

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

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Create a new album

Create a new album for the authenticated user

Authorizations:
BearerAuth
Request Body schema: application/json
required

Album creation data

album_name
required
string
cover_asset_id
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "album_name": "string",
  • "cover_asset_id": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Delete album

Delete an album by its ID

Authorizations:
BearerAuth
path Parameters
id
required
integer

Album ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "error": "error details",
  • "message": "success"
}

Get album by ID

Retrieve a specific album by its ID

Authorizations:
BearerAuth
path Parameters
id
required
integer

Album ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

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

album_name
string
cover_asset_id
string
description
string

Responses

Request samples

Content type
application/json
{
  • "album_name": "string",
  • "cover_asset_id": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Get assets in album

Retrieve all assets in a specific album

Authorizations:
BearerAuth
path Parameters
id
required
integer

Album ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "error": "error details",
  • "message": "success"
}

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)

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "error": "error details",
  • "message": "success"
}

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

position
integer

Responses

Request samples

Content type
application/json
{
  • "position": 0
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "error": "error details",
  • "message": "success"
}

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 for the asset

position
required
integer

Responses

Request samples

Content type
application/json
{
  • "position": 0
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "error": "error details",
  • "message": "success"
}

Get albums containing asset

Retrieve all albums that contain a specific asset

Authorizations:
BearerAuth
path Parameters
id
required
string

Asset ID (UUID format)

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "error": "error details",
  • "message": "success"
}

assets

List assets

Retrieve a paginated list of assets. Filter by type, owner, or search query. Use 'vector=true|false' to control semantic vector search when 'q' is provided (feature must be enabled). At least one filter parameter is required.

query Parameters
type
string
Enum: "PHOTO" "VIDEO" "AUDIO" "DOCUMENT"
Example: type="PHOTO"

Asset type filter

owner_id
integer
Example: owner_id=123

Filter by owner ID

q
string
Example: q="red bird on a branch"

Search query (semantic vector search when enabled) and filename match

vector
boolean
Default: false

When q is set: true to use semantic vector search, false to use filename search

limit
integer
Default: 20
Example: limit=20

Maximum number of results (max 100)

offset
integer
Default: 0

Number of results to skip for pagination

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Upload a single asset

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

header Parameters
X-Content-Hash
string

MLService-calculated BLAKE3 hash of the file

Request Body schema: multipart/form-data
required
file
required
string <binary>

Asset file to upload

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

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)

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Get asset by ID

Retrieve detailed information about a specific asset. Optionally include thumbnails, tags, and albums.

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

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

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

Updated metadata

specific_metadata
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

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

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

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

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

Batch upload assets

Batch upload multiple assets using a multipart/form-data request. Each file part's field name must be its BLAKE3 content hash. All files are staged and queued for processing.

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Filter assets

Filter assets using comprehensive filtering options including RAW, rating, liked status, filename patterns, date ranges, camera make, and lens

Request Body schema: application/json
required

Filter criteria

object (handler.AssetFilter)
limit
integer [ 1 .. 100 ]
offset
integer >= 0

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 20,
  • "offset": 0
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Get filter options

Get available camera makes and lenses for filter dropdowns

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Search assets

Search assets using either filename matching or semantic vector search. Can be combined with comprehensive filters.

Request Body schema: application/json
required

Search criteria

object (handler.AssetFilter)
limit
integer [ 1 .. 100 ]
offset
integer >= 0
query
required
string
search_type
required
string
Enum: "filename" "semantic"

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 20,
  • "offset": 0,
  • "query": "red bird on branch",
  • "search_type": "filename"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Get supported asset types

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

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

auth

Login user

Authenticate user with username and password

Request Body schema: application/json
required

Login credentials

password
required
string
username
required
string

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Logout user

Revoke the user's refresh token

Request Body schema: application/json
required

Refresh token to revoke

refreshToken
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "error": "error details",
  • "message": "success"
}

Get current user

Get information about the currently authenticated user

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Refresh access token

Generate a new access token using a valid refresh token

Request Body schema: application/json
required

Refresh token

refreshToken
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}

Register a new user

Create a new user account with username, email, and password

Request Body schema: application/json
required

Registration data

email
required
string
password
required
string >= 6 characters
username
required
string [ 3 .. 50 ] characters

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    },
  • "error": "error details",
  • "message": "success"
}