v64

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-016280256.4 KB

stacks

Manually stack assets

Groups two or more existing assets into a new user-owned stack (origin = user) for collapsed display. A user-owned stack is never re-segmented by burst re-detection.

An asset already in another stack is repointed into the new one, folding that stack in whole if it was its pinned cover; a stack left with fewer than 2 members dissolves. The photos themselves are untouched.

If a concurrent stack change invalidates the request mid-flight, it returns 409 and nothing is created; retry the request unchanged.

post/api/stacks

Request body

asset_idsstring[] required

Asset IDs (with asset_ prefix) to group into the new stack — at least 2 distinct ids, all in the target library.

primary_asset_idstring nullable

Asset ID (with asset_ prefix) to pin as the stack's cover; must be one of asset_ids. Omit to leave the cover unpinned — there is no automatic pick, and clients choose their own display cover for an unpinned stack.

library_idstring nullable

Library to create the stack in. Optional if the user has a single library; required when they have multiple.

Response

Successful Response

idstring required

Unique stack identifier with 'asset_stack_' prefix

primary_asset_idstring nullable

ID of the asset the user pinned as the stack's cover, or null if none is pinned. Null for an auto-detected burst unless a user has since pinned a cover — there is no server-selected default, so a client showing a stack with no pinned cover picks its own. A pinned cover that has been trashed keeps its ID here; it is cleared only once the asset is permanently deleted.

asset_countinteger required

Number of live assets in this stack. Excludes trashed members, so it can drop below the number of frames originally grouped.

origin'auto_burst' | 'user' required

How a stack came to exist.

auto_burst marks a stack the burst detector created from the time + EXIF-camera signal; user marks a stack a user created or edited (manual create, set-cover, add/remove, unstack). The distinction is what keeps re-detection from stomping a user's correction — the detection pass skips user stacks.

created_atstring date-time required

When this stack was created

updated_atstring date-time required

When this stack was last updated