Skip to content
calternal docs

Set the key Photo in a burst

PUT
/api/v1/photos/stacks/{group_id}/key-photo
curl --request PUT \
  --url https://example.com/api/v1/photos/stacks/example/key-photo \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "item_id": "example" }'

Requires a signed-in User. It chooses which Photo represents the burst in the timeline. It returns 400 when the Photo is not in the burst, 404 when the burst is missing or 409 when its metadata cannot be updated. Route: /api/v1/photos/stacks/{group_id}/key-photo. Inputs: group_id. Do not automatically replay this operation after an uncertain result.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
group_id
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
item_id
required
string
Examplegenerated
{
  "item_id": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

The accepted key choice plus the previous override and CAS tokens for Undo.

object
previous_item_id

Prior explicit choice, or None when capture order supplied the key.

string | null
sidecars
required

Current Sidecar hashes, captured after the forward update.

Array<object>

A Sidecar revision expected by a key-photo Undo; None means it was absent.

object
hash

BLAKE3 hash of the Sidecar bytes, or None when no Sidecar existed.

string | null
item_id
required

Stable Files item identity for the photo.

string
Examplegenerated
{
  "previous_item_id": "example",
  "sidecars": [
    {
      "hash": "example",
      "item_id": "example"
    }
  ]
}

400

Section titled “400”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

404

Section titled “404”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

409

Section titled “409”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}