List the collections your post is in
GET /posts/{id}/collections
Lists the collections your post has been added to. Those you can read come back with their details, each saying whether you can take the post out of it; the rest are only counted.
You need to be signed in, and only the post’s author and holders of
posts.admin or system.admin granted globally can ask. Anyone
else gets 404, as for a post that doesn’t exist or is deleted. Being
able to read the post, having it shared with you, or holding
posts.admin only for a team isn’t enough.
A collection is included when it isn’t deleted and holds the post through a membership that hasn’t expired; a membership stops counting once its expiry time is reached. Drafts can be in collections too, so the answer doesn’t depend on whether the post is published. Being in a collection doesn’t let that collection’s readers read the post: the post’s own rules still decide.
items holds the collections you may read: public ones, your own,
ones shared with you through a grant that hasn’t expired, or all of
them if you hold system.admin. Holding collections.admin doesn’t
widen this. The newest come first, up to 200, with no way to page
further. Each comes back as stored, without covers; its cover
settings are the curator’s choices, not a sign that you can see
those pictures.
can_remove says whether you may take the post out of that
collection. That is for the collection’s owner or a holder of
collections.admin or system.admin granted globally, not for the
post’s author as such. It reflects your rights when the list was
read, and the removal route checks again.
withheld_count is how many other collections holding the post you
may not read; you get no names or ids for them. It is counted on its
own, so a list cut at 200 doesn’t change it. The list and the two
counts behind it aren’t read as one snapshot, so a membership added
or removed meanwhile can make the count briefly wrong in either
direction.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The post’s id.
Responses
Section titled “ Responses ”The collections you can read that hold the post, and a count of the others.
The collections holding a post, split by what you may read: readable
ones in items, the others only as a number in withheld_count.
object
The collections holding the post that you may read, newest first and at most 200, each with whether you may take the post out of it.
One collection holding the post, and whether you may take the post out of it.
object
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.
Whether you may remove the post from this collection: true for the
collection’s owner and for holders of collections.admin or
system.admin granted globally. Being the post’s author adds
nothing: an author sees false on a collection they don’t own
unless they hold one of those capabilities. It reflects your rights
when the list was read; the removal route checks again.
How many other collections holding the post you may not read. Deleted collections aren’t counted.
It is counted separately from items, not as a total minus the
number of items, so when more than 200 readable collections hold the
post, items stops at 200 and this can still be 0. Because the
counts and the list are read one after another, a change in between
can leave it briefly too high or too low.
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"}Resource not found
object
Human-readable error summary
Example
the request could not be completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed