Create a new collection
POST /collections
Creates a manual-membership collection owned by the caller.
Query-membership and hybrid modes ship in 1.11.B; for now
only membership=manual is accepted.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
Only manual is accepted in 1.11.A; passing query or
hybrid returns 400 until 1.11.B ships.
Initial values for collection-scoped custom
fields. The handler validates that every required=true
collection field is present; missing required fields
return 422 with required_collection_field_missing.
object
Responses
Section titled “ Responses ”Collection created
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.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication 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"}The create body does not satisfy the collection-scoped field definitions. Both gates run BEFORE any write, so a refusal never leaves a half-created collection behind, and both are enforced on CREATE only — subsequent UPDATEs do not re-validate.
required_collection_field_missing— a field withrequired = trueis absent from the body.collection_field_pattern_mismatch— a supplied value does not match its field’sregexp_filter. Seeding an initial value is the one human write aread_onlycollection field allows, and the pattern still applies to it.
object
Unexpected server error
object
Human-readable error summary
Example
the request could not be completed