List collections (filterable, paginated)
GET /collections
Returns collections ordered by created_at DESC, id DESC so
the newest entries are first. Filters and cursor pagination
match the assets list contract — pass back next_cursor
opaquely as cursor to retrieve the following page.
Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Filter to collections owned by this user_ref.
Narrow to one tier WITHIN what this caller may read — the
same display-filter semantics GET /posts?visibility= has.
It never widens the read rule.
public joined the list with #1195. The tab-driven Public
view has filtered on that tier server-side since #1104
(hubPublicTier), so a client could reach the tier by tab
and not by name; the enum was the only thing saying it did
not exist.
Filters on whether the collection has a placement in
featured_items THIS CALLER CAN SEE (ADR 0065) — public
placements for everyone, plus org placements once signed
in. Not “ORG-scoped”: #1104 split the scope, and the filter
follows the caller rather than pinning one value.
Featuring is a placement, not a property of the collection, so this asks “is it featured to me”, not “is its featured flag set” — the flag no longer exists.
IT NEVER WIDENS ACCESS. The placement filter is ANDed onto the ordinary collection read predicate, so a collection the caller may not read is absent whether it is featured or not.
Pre-canned filter for the collections hub:
mine— collections owned by the caller (any visibility)featured— featured to this caller AND readable by them. NO TIER PIN (#1121): this tab means “featured collections I may see”, so it is the placement filter ANDed onto the ordinary read predicate and nothing else. It used to also pinvisibility=public, which made it disagree with the rail (GET /featured) — an admin could feature anorg-onlycollection, see it on the rail, and never see it here. Removing the pin cannot widen access: featuring is a placement, not a grant, and the read predicate it is ANDed onto is unchanged.public— visibility=public (every install-public collection). This tab KEEPS its tier pin, because there the tier is the tab’s contract rather than an extra conjunct on top of one.shared— collections the caller has ACL access to but doesn’t ownall— every collection the caller is allowed to see (default)tabis mutually-exclusive withowner_ref/visibility/featured— when set it overrides those.
Free-text filter on name (case-insensitive substring).
Admin-only. When true, soft-deleted collections appear
alongside live rows. Non-admin callers ignored.
Responses
Section titled “ Responses ”A page of collections
object
A user-owned collection of assets, per ADR 0009. UUID-keyed,
federation-prepared (origin_server_id), with three
orthogonal axes: visibility, membership, and lifecycle.
object
The collection’s read tier.
public means anonymous visitors may read it when the
instance has public mode on. It has been in the column’s
CHECK constraint since migration 00008 and in the read rule
(visibility.Predicate over EntityCollection admits
visibility = 'public') ever since; only this schema, and
therefore every client, kept saying otherwise — the same
defect #1176 fixed for posts. A collection could be made
public by no route the API offered (#1195).
manual only for 1.11.A. query and hybrid ship in
1.11.B once the search DSL (ADR 0010) lands.
TTL. Null = permanent.
Free-form admin-set hint (“for_review”, “for_proofing”, …).
Replaces RS’s single-purpose archived flag.
Federation home server. Null = local. Populated when collections sync in from a peer in a later phase.
Soft-delete timestamp. Non-null only on rows surfaced by
the admin include_deleted=true listing (the trash view);
null on live rows.
Optional reason captured at soft-delete time.
The curator’s CHOSEN cover picture (#1027), or null to compose the derived mosaic from members instead.
ANY asset the curator could picture when they set it — not necessarily a member of this collection. That is what makes it survive the member being removed, which is the failure a member-only pointer has. “Upload a dedicated banner” is still available: upload it as an ordinary asset, then pick it. One extra step, no separate upload machinery, and one representation for a cover instead of two.
THIS IS THE CURATOR’S SETTING, NOT THE RENDER ANSWER. Read
covers to know what to paint; read this to populate the
edit form’s picker. They disagree on purpose whenever the
reader may not picture the chosen asset — see covers.
It does NOT federate. A local asset id names something that exists only on this server, which is ADR 0083’s exclusion criterion; a peer composes its own mosaic from the members it holds.
The curator’s cover for the FEATURED RAIL specifically (#1207), or null for “no separate choice”.
The rail’s card is locked to 890:500 while a collection card is 4:3, so the picture that reads well on one is often not the one that reads well on the other. This is the second pointer that lets them differ.
NULL IS A FALLBACK, NOT A BLANK. The rail’s preference order
is this cover, then cover_asset_id, then the derived
hero-card cover of ADR 0027 — and each rung is re-checked
against the reader’s own picture plane, so a chosen cover
the reader may not picture falls through to the next rung
rather than leaving a blank tile or leaking the withheld
picture.
Like cover_asset_id: any asset the curator may picture,
not necessarily a member; the curator’s SETTING rather than
the render answer; and not federated.
Where the featured rail’s 890:500 crop is centred horizontally, as a FRACTION of the picture’s width — 0 is the left edge, 1 the right (#1207).
A fraction rather than a pixel offset because the rail
renders whichever preview rung the ladder serves at whatever
width the viewport gives it. A fraction is correct at every
rung and every width; a pixel offset measured against the
original is correct at none of them. It maps straight onto
CSS object-position.
Null means centre — the CSS default and what every collection had before this existed. Null and an explicit 0.5 are stored differently on purpose: the editor’s reset is a clear, so “never positioned” stays distinguishable from “positioned dead centre”.
Always null or set TOGETHER with featured_cover_focal_y; a
focal point is a point, and the database constrains the pair.
The vertical half of the featured crop’s focal point — 0 is
the top edge, 1 the bottom (#1207). See
featured_cover_focal_x for why it is a fraction, why null
means centre, and why the two travel together.
Where the COLLECTION cover’s 4:3 crop is centred horizontally, as a fraction of the picture’s width (#1207).
THE DESTINATION SHAPE IS 4:3, NOT A SQUARE (#1334).
CollectionCard paints a chosen cover inside an
aspect-[4/3] tile on the hub, on a profile and in search,
and that tile is the only collection surface that crops this
picture. The square is the tempting wrong answer because the
col rendition IS one (fit: cover at 320px, a 320x320
centre-crop, what every small collection thumbnail is made
of), but col is a SOURCE and not a destination: a client
that positioned against it would show a region the card
never displays. A crop locks to the dimensions of the thing
that renders it.
A separate pair from featured_cover_focal_x because the
featured card is 890:500: the point that centres a face in a
wide band is not the point that centres it in a 4:3 tile, so
one fraction cannot be right for both destinations.
⚠️ IT IS CHOSEN AGAINST THE ORIGINAL PICTURE. A consumer
honours it by rendering a contain rung with
object-position; applying it to col crops a crop, since
col’s square was already taken at the centre before this
value could act.
Null means centre. Swapping or removing the cover picture without supplying new framing clears it (#1333), because a fraction chosen against one photograph means nothing on the next.
The vertical half of the collection cover’s focal point
(#1207). See cover_focal_x.
How far the featured rail’s 890:500 crop is tightened, as a multiplier on the fitting rectangle (#1212).
The crop window is the FIT window divided by this, so 1 is
the fit itself and 2 shows a quarter of the area. It exists
because the fit window always has one axis equal to the
whole picture — object-fit: cover keeps one axis whole —
so at the fit exactly one axis can travel, and a subject
sitting in the left half of a portrait cover can never be
brought to the middle. Below the fit BOTH axes gain travel,
which is what makes featured_cover_focal_x mean anything
for such a picture.
Null means fit: what every collection rendered before this existed, so a client that ignores it renders exactly what it rendered before. Null and an explicit 1 paint the same picture and are stored differently on purpose — the editor’s reset is a clear, so “never zoomed” stays distinguishable from “zoomed and came back”.
Bounded 1..4. Below 1 the window would be larger than the
picture. The upper bound comes from the preview ladder’s
real rungs: a cover carrying a crop is painted from a
CONTAIN rung, the rung it is guaranteed to have is preview
(1024) and the tallest one is hires (4096), so 4x is the
last step the ladder can still answer with real pixels.
How far the collection card’s 4:3 crop is tightened (#1212).
Separate from featured_cover_zoom for the reason the focal
pairs are separate: the tightening that frames a subject in
a wide band is not the one that frames it in a 4:3 tile. See
featured_cover_zoom for the semantics and the 1..4 bound.
What to PAINT for this collection’s tile — the curator’s chosen cover if there is a renderable one (#1027), else up to four members whose picture this caller may render, the derived mosaic (#1026).
A COVER THIS READER MAY NOT PICTURE FALLS BACK TO THE MOSAIC; it never yields a blank tile, and it never leaks the withheld picture either. The choice is the curator’s, but whether it renders is still decided per reader, so two readers of the same collection can correctly get different answers here. A client cannot tell an overridden cover from a one-member mosaic, and does not need to.
POSTS ARE THE ONLY SOURCE (#1236). Each contributing
member is a collection_posts row, supplying
cover_thumbnail_asset_id ?? cover_asset_id — the same
preference a feed card uses. #882 made a post-only
collection an ordinary thing to own (“save someone else’s
post”), and until #1026 such a collection had no cover
source at all and rendered as an empty folder.
collection_resources rows used to contribute their asset
directly, and stopped when #1161 removed bare-asset
membership as a publication path: a tile summarises what a
collection CONTAINS, and after #1185 took the asset section
off the page those assets were inside nothing a reader
could open. A COLLECTION WITH NO POSTS THEREFORE HAS NO
COVERS — the field is absent, and the client paints its
empty state.
ORDER is the curator’s, added_at ascending: the
arrangement is the curation.
EACH ASSET APPEARS AT MOST ONCE, at its earliest position.
Two posts in one collection can share a cover, and the same
picture twice summarises nothing. Clients may therefore key
a list on asset_id.
WITHHELD MEMBERS ARE SKIPPED, NOT SLOTTED. Only members
passing the caller’s picture plane (ADR 0064) and having a
col rendition appear, so a restricted member never
occupies a slot a renderable one behind it could fill. A
blank quarter of a mosaic says nothing and costs a picture.
ABSENT means “not composed on this surface”, never “no members” — an empty array is the honest “nothing to show”.
One tile of a collection’s composed mosaic cover (#1026). An
entry exists only if this caller may render the asset, so
clients paint every entry unconditionally — there is no
preview_available to branch on and no placeholder rung.
object
Fetch the picture from
/assets/{asset_id}/variants/col. Guaranteed to have that
rendition — an asset without one is not a cover candidate.
A CONTAIN rung (preview) exists for this asset (#1207) — a
different question from the col guarantee above, and the
one a focal point depends on.
⚠️ A COVER WITH A FOCAL POINT MUST BE PAINTED FROM A CONTAIN
RUNG. col is fit: cover at 320px, a 320x320 CENTRE-CROP,
so the picture’s edges are gone before object-position
could act on them: applying collections.cover_focal_* to
col crops a crop and lands somewhere the curator did not
choose. The focal fractions are stored against the ORIGINAL,
so the source has to be one that still is the original
shape.
When this is false there is no such rung and the client
falls back to col with a centred crop — which is exactly
what every collection card did before focal points existed,
so the fallback is the old behaviour rather than a
degradation.
Populated for every entry, mosaic tiles included, even though only the single-cover case consumes it: a field that is present on some rows and absent on others is a field every reader has to branch on twice.
Opaque token for the next page; omitted on the final page.
Pass back unchanged as the cursor query parameter.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Unexpected server error
object
Human-readable error summary
Example
the request could not be completed