Skip to content
Artist Alley

List admin-curated featured items (GitHub

GET
/admin/featured

Returns the featured curation list in display order (position ascending, then created_at). Each entry resolves its subject’s display title, plus thumbnail hints for asset subjects. Requires system.admin.

Authorizations

Section titled “Authorizations ”

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Featured items in order.

object
items
required
Array<object>

GitHub #341 — one admin-curated featured entry pointing at an asset or collection, with an explicit ordering position and the resolved subject title. Both subject kinds carry thumbnail hints so a tile can render a cover: assets from themselves, collections via ADR 0027’s hero-card fallback (#559).

object
id
required

The featured_items row id (used for remove/reorder).

string format: uuid
subject_kind
required
string
Allowed values: asset collection
subject_id
required
string format: uuid
position
required

0-based display order.

integer
title
required

Resolved subject title (asset title or collection name). Empty when the subject was deleted out from under the row.

string
cover_asset_id

The asset whose col variant renders this tile (#559).

For an asset subject this is the subject itself. For a COLLECTION it is the hero-card fallback of ADR 0027 — the most-recent post’s cover asset — which is why the id is needed separately: subject_id is the collection, and the variant endpoint is keyed by asset.

Null when nothing is servable to this caller, in which case the tile is title-only. Subject to the same gating as asset_file_hash, so it never names an asset the caller cannot see.

string format: uuid
nullable
asset_file_hash

Thumbnail hint for the tile’s cover asset; null when there is nothing servable for this caller. Populated for collection subjects too since #559.

string
nullable
asset_has_image

Whether a raster thumbnail exists for the cover asset.

Unreliable for asset subjects — the underlying has_image column has no writer, so it is false across the board; clients key on preview_available instead. Retained because removing a response field is a breaking change.

boolean
preview_available
required

True iff a servable col variant exists for the tile’s cover asset AND the caller passes the content plane (ADR 0064). The rail renders a thumbnail only when true, else a title-only tile with no byte request (#471). Computed from live variant existence, so unlike asset_has_image it is trustworthy. Populated for collection subjects too since #559.

boolean
created_at
required
string format: date-time

401

Section titled “401 ”

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

403

Section titled “403 ”

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed