---
title: "Set a stack's cover"
method: PATCH
path: "/api/stacks/{stack_id}"
tags: ["stacks"]
---

# Set a stack's cover

`PATCH /api/stacks/{stack_id}`

Pins one of the stack's own live members as its cover (`primary_asset_id`). Setting a cover marks the stack as user-owned (`origin = user`), which freezes it — membership included — against burst re-detection, so neither the chosen cover nor the frame grouping is ever silently reverted by a later detection pass.

`primary_asset_id` cannot be null: there is no manual clear-cover operation. A pin clears automatically when the pinned frame is removed from the stack or permanently deleted.

## Path parameters

- `stack_id` string, required — Stack ID (with `asset_stack_` prefix) of the stack to pin a cover on.

## Request body

- StackUpdate
  - `primary_asset_id` string, required — Asset ID (with `asset_` prefix) to pin as the stack's cover. Must be a live, current member of this stack — get member IDs from `list_assets` with `stack_id`.

## Response `200`

Successful Response

- StackResponse — Represents a group of assets displayed as a single tile.
  - `id` string, required — Unique stack identifier with 'asset_stack_' prefix
  - `primary_asset_id` string, 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_count` integer, 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_at` string, date-time, required — When this stack was created
  - `updated_at` string, date-time, required — When this stack was last updated

## Other responses

- `401` — Missing, invalid, or expired credentials.
- `403` — The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept.
- `404` — Not found
- `422` — Validation Error
- `429` — Rate limit exceeded. Retry after the interval in the `Retry-After` header.

---

[API](https://skmtc.net/gumnut-ai/apis/gumnut-api.md) · [All operations](https://skmtc.net/gumnut-ai/apis/gumnut-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gumnut-ai/gumnut-api/versions/e71db45f5d4a/schema)