Create a collection
POST /collections
Creates a collection owned by you. You need to be signed in; no capability is needed.
name has spaces at either end removed and must not be empty (400).
visibility defaults to private, and a value outside its list is
refused with 500. membership must be manual or left out (400
otherwise). The 200-character limit on name isn’t checked. A
request body that isn’t valid JSON, or that gives a field a value of
the wrong type, is refused with 400 before anything else.
Each active collection field configured as required needs an entry
in field_values, and text values must match their fields’ input
patterns; otherwise you get 422 and nothing is created. If those
checks pass, a field id that doesn’t exist, or that belongs to a
field for something other than collections, makes the request fail
with 500, and nothing is created either.
The collection, its field values and a create activity are saved
together. The response doesn’t include covers. You can choose a
cover later with PATCH /collections/{id}.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
The collection’s name. Spaces at either end are removed, and it can’t be empty.
A longer description; empty if you leave it out.
Who may read the collection; see visibility in the response. Defaults to private.
Only manual is accepted; query and hybrid get 400.
An expiry date to record. Nothing acts on it at present.
An optional free-form label for what the collection is for, such as for_review. It doesn’t change how the collection behaves.
Starting values for collection fields, one entry per field. Put the value in the member that matches the field’s type; the other members are ignored. A required field counts as supplied when it has an entry, even one with no value. If a field appears more than once, the last entry is stored, but every entry’s text is checked against the field’s pattern. Read-only fields can be given a starting value here.
object
The collection field to set.
For text, longtext, rich_text, select and tree fields; for select and tree it’s the term’s slug. Rich text is cleaned before it’s stored.
For number and boolean fields, with 1 for yes and 0 for no. It’s read as a single-precision number, so long numbers lose digits.
For date and datetime fields.
For multi_select fields: the terms’ slugs.
For reference fields: the referenced asset’s id.
Responses
Section titled “ Responses ”The new collection. covers isn’t included.
A named collection of posts, owned by one user. Who can read it is
set by visibility, how posts get into it by membership, and
whether it carries an expiry date by expires_at.
object
Who may read the collection. A public collection can be read by
any signed-in user, and by visitors who aren’t signed in when the
instance is in public mode. Any other collection can be read by its
owner, by users it has been shared with through a grant that hasn’t
expired, and by holders of system.admin. As installed, org-only,
followers and explicit-share add no readers beyond those, so
they behave like private.
How posts get into the collection. Only manual is in use: posts
are added and removed one at a time. query and hybrid are
reserved, and saving a search as a collection stores a fixed set of
its results.
An expiry date set on the collection, or null. Nothing acts on it at present: the collection stays readable and listed after that time.
An optional free-form label for what the collection is for, such as
for_review. It doesn’t change how the collection behaves.
The server the collection came from, or null for a collection
created here.
When the collection was deleted. It appears only in the listing of
deleted collections that holders of system.admin can ask for with
include_deleted=true; elsewhere it is absent.
Why the collection was deleted, when a reason was given. It appears only with deleted_at.
The cover picture the curator chose, or null when the cover is
made from the collection’s posts. It can be any asset the curator
was allowed to see when choosing it, not only one in the collection.
This is the setting, not what to show: covers says what to paint,
and readers who may not see the chosen picture get the posts’
pictures instead.
The cover to use for this collection on the featured rail, or null
for no separate choice. The rail tries this cover, then
cover_asset_id, then a cover made from the collection’s posts,
skipping any the reader may not see. Like cover_asset_id, it can
be any asset the curator was allowed to see, and it is the setting
rather than what to show.
Where the featured rail’s crop is centred across the picture, from 0
at the left edge to 1 at the right, measured on the original
picture. null means centred. It is set or cleared together with
featured_cover_focal_y.
Where the featured rail’s crop is centred down the picture, from 0
at the top to 1 at the bottom. See featured_cover_focal_x.
Where the collection card’s 4:3 crop is centred across the picture,
from 0 at the left edge to 1 at the right, measured on the original
picture. null means centred. It is set or cleared together with
cover_focal_y, and cleared when the cover picture changes without
new framing. Apply it to a full-picture rendition such as preview,
not to col, which is already a square centre crop.
Where the collection card’s crop is centred down the picture, from 0
at the top to 1 at the bottom. See cover_focal_x.
How far the featured rail’s crop is tightened, from 1 to 4: at 1 the
crop just fits, and at 2 it shows a quarter of that area. null
means no zoom, which looks the same as 1.
How far the collection card’s crop is tightened, from 1 to 4. See
featured_cover_zoom.
What to paint for the collection’s tile: the chosen cover if you may
see it and a col rendition is recorded for it, otherwise up to
four pictures from the collection’s posts that you may see and that
have a recorded col rendition, in the order the posts were added.
Each picture appears at most once.
It is absent where a route doesn’t compose covers, as in the list of collections holding a post; an empty array means there is nothing to show.
One picture in a collection’s cover. It is included only if you may
see it and a col rendition is recorded for it; that record isn’t a
check that the file can be fetched.
object
The asset to show. A col rendition is recorded for it, fetched
from /assets/{asset_id}/variants/col.
Whether a preview rendition is also recorded for the asset: the
full picture to crop from when the collection has a focal point or
zoom. When it is false, use col with a centred crop.
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 collection fields’ rules weren’t met, and nothing was created.
reason says which rule:
required_collection_field_missing: an active required collection field has no entry infield_values.collection_field_pattern_mismatch: a text value doesn’t match its field’s input pattern.
Only the first problem is reported: active required fields are checked first, in their display order, then values in the order you sent them. Updating the collection later doesn’t check the required fields again.
object
What’s wrong, in words.
Which rule was broken.
The field’s code.
The field’s label.
Unexpected server error
object
Human-readable error summary
Example
the request could not be completed