Skip to content

List collections

GET
/collections

Returns a page of the collections you’re allowed to see, newest first. Deleted collections are left out unless a holder of system.admin asks for them with include_deleted=true.

Signed-in users see collections that are public, their own, and those shared with them through a grant that hasn’t expired; holders of system.admin see no more than that here. With public mode on, visitors who aren’t signed in can call this too and see public collections only; with it off they get 401.

Every filter only narrows that set. owner_ref, visibility, featured and q combine; when you’re signed in, the mine, featured, public and shared tabs replace the first three, and all or any other tab leaves them as sent. Pages use a cursor: limit is clamped to 1-200 and defaults to 50, and next_cursor is set when more collections follow. A malformed cursor is answered with 500. There’s no total count, and collections created after your first request don’t appear on later pages.

Each collection comes with covers worked out for you.

owner_ref
integer format: int64

Only collections owned by this user ref.

visibility
string
Allowed values: public private org-only followers explicit-share

Only collections with this visibility. It narrows what you may see and never widens it. A value that isn’t in the list matches nothing.

featured
boolean

true keeps only collections featured to you, and false only those that aren’t. A featured placement counts when its audience includes you: public placements for everyone and org placements for signed-in users; team placements don’t count. Featuring never makes a collection visible to you.

tab
string
Allowed values: mine featured public shared all

A preset for the collections page. It applies only when you’re signed in, and each of the first four presets replaces owner_ref, visibility and featured:

  • mine: your own collections.
  • featured: collections featured to you, as with featured=true.
  • public: public collections.
  • shared: collections shared with you through a grant that hasn’t expired, other than your own.
  • all, or any other value: no preset.

q, limit, cursor and include_deleted still apply.

q
string
<= 200 characters

Only collections whose name contains this text, ignoring case and spaces at either end. % and _ act as wildcards for any run of characters and any single character.

limit
integer
default: 50 >= 1 <= 200

How many collections to return, from 1 to 200; values outside that range are clamped. Defaults to 50.

cursor
string

The next_cursor from the previous page, sent back unchanged. A value that can’t be read is answered with 500.

include_deleted
boolean

With system.admin, true adds deleted collections to the list, each with deleted_at and deleted_reason, but only those the list would otherwise show you. For anyone else it’s ignored.

One page of collections, newest first.

object
items
required

The collections on this page.

Array<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
id
required
string format: uuid
owner_user_ref
required
integer format: int64
name
required
string
description
required
string
visibility
required

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.

string
Allowed values: public private org-only followers explicit-share
membership
required

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.

string
Allowed values: manual query hybrid
expires_at

An expiry date set on the collection, or null. Nothing acts on it at present: the collection stays readable and listed after that time.

string format: date-time
nullable
purpose

An optional free-form label for what the collection is for, such as for_review. It doesn’t change how the collection behaves.

string
nullable
origin_server_id

The server the collection came from, or null for a collection created here.

string format: uuid
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
deleted_at

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.

string format: date-time
nullable
deleted_reason

Why the collection was deleted, when a reason was given. It appears only with deleted_at.

string
nullable
cover_asset_id

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.

string format: uuid
nullable
featured_cover_asset_id

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.

string format: uuid
nullable
featured_cover_focal_x

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.

number format: double
nullable
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.

number format: double
nullable
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.

number format: double
nullable
cover_focal_y

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.

number format: double
nullable
featured_cover_zoom

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.

number format: double
nullable
cover_zoom

How far the collection card’s crop is tightened, from 1 to 4. See featured_cover_zoom.

number format: double
nullable
covers

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.

Array<object>

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
asset_id
required

The asset to show. A col rendition is recorded for it, fetched from /assets/{asset_id}/variants/col.

string format: uuid
preview_available
required

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.

boolean
next_cursor

Send this back as cursor to get the next page. It’s left out on the last page.

string
nullable

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"
}

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed