Skip to content

Update a collection

PATCH
/collections/{id}

Changes a collection’s details, its cover choices and their framing. Fields you leave out, or send as null, keep their stored values; use the clear_ flags to remove one.

The owner may change it, and so may holders of collections.admin or system.admin granted globally. A sharing grant doesn’t count, whatever its permission. A collection that doesn’t exist or is deleted answers 404, and anyone else gets 403.

if_unchanged_since is compared with the collection’s updated_at, to the microsecond, before the change; if they differ you get 409 and nothing is written. The comparison and the write aren’t one step, so two edits sent at the same moment with the same value can both succeed. Where their effects overlap, the write that commits last decides what is stored, whatever order the requests arrived or finished in; for example, a new cover sent without framing clears a crop another request has just set. Every update that succeeds, even one that changes nothing, sets a new updated_at and records an update activity in the same transaction.

The response doesn’t include covers. Required collection fields aren’t checked again.

id
required
string format: uuid

The collection’s id.

Send only what you’re changing. null means leave it alone, so removing a value takes its clear_ flag, and sending a value with its own clear flag gets 400.

object
name

A new name. Spaces at either end are removed, and it can’t end up empty (400).

string
>= 1 characters <= 200 characters
description

A new description. An empty string clears it.

string
visibility

Who may read the collection; see visibility in the response. A value outside the list is refused with 500.

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

Only manual is accepted; query and hybrid get 400.

string
Allowed values: manual query hybrid
expires_at

A new expiry date. Nothing acts on it at present. null leaves it alone; use clear_expires_at to remove it.

string format: date-time
nullable
clear_expires_at

true removes the expiry date. Sending it with expires_at gets 400.

boolean
purpose

A new free-form label. An empty string stores an empty label; it can’t be set back to null.

string
nullable
cover_asset_id

The collection’s chosen cover. It can be any asset you’re allowed to see, not only one in the collection: you’re its owner, it’s public, it’s a team asset of a team you belong to, or you hold content.read.all or system.admin. Mature assets also follow the mature settings, except for their owner and system.admin. Anything else, including an id that doesn’t exist or a deleted asset, gets the same 400. The asset needn’t have its renditions yet.

Choosing a different cover clears cover_focal_x, cover_focal_y and cover_zoom unless you send new values for them in the same request. Sending the cover that’s already set leaves its framing as it is, unless you also send new framing.

string format: uuid
clear_cover

true removes the chosen cover, so the cover is made from the collection’s posts again. It also clears the cover’s focal point and zoom unless you send new ones. Sending it with cover_asset_id gets 400.

boolean
featured_cover_asset_id

The cover for the featured rail, on the same terms as cover_asset_id: the same assets qualify and the same 400 applies. Choosing a different one clears featured_cover_focal_x, featured_cover_focal_y and featured_cover_zoom unless you send new values; the collection card’s framing isn’t touched.

string format: uuid
clear_featured_cover

true removes the featured-rail cover, so the rail falls back to cover_asset_id and then to a cover made from the posts. It also clears the featured focal point and zoom unless you send new ones. Sending it with featured_cover_asset_id gets 400.

boolean
featured_cover_focal_x

Where to centre the featured rail’s crop across the picture, from 0 at the left edge to 1 at the right. Send it with featured_cover_focal_y; one without the other, or a value outside 0-1, gets 400.

number format: double
<= 1
featured_cover_focal_y

Where to centre the featured rail’s crop down the picture, from 0 at the top to 1 at the bottom. Send it with featured_cover_focal_x.

number format: double
<= 1
clear_featured_cover_focal

true puts the featured rail’s crop back to centred. Sending it with either focal value gets 400.

boolean
cover_focal_x

Where to centre the collection card’s 4:3 crop across the picture, from 0 at the left edge to 1 at the right. Send it with cover_focal_y; one without the other, or a value outside 0-1, gets 400.

number format: double
<= 1
cover_focal_y

Where to centre the collection card’s crop down the picture, from 0 at the top to 1 at the bottom. Send it with cover_focal_x.

number format: double
<= 1
clear_cover_focal

true puts the collection card’s crop back to centred. Sending it with either focal value gets 400.

boolean
featured_cover_zoom

How far to tighten the featured rail’s crop, from 1 (the whole fit) to 4; at 2 it shows a quarter of the area. It’s independent of the focal point. A value outside 1-4 gets 400.

number format: double
>= 1 <= 4
clear_featured_cover_zoom

true removes the featured rail’s zoom. Sending it with featured_cover_zoom gets 400.

boolean
cover_zoom

How far to tighten the collection card’s crop, from 1 to 4. A value outside that range gets 400.

number format: double
>= 1 <= 4
clear_cover_zoom

true removes the collection card’s zoom. Sending it with cover_zoom gets 400.

boolean
if_unchanged_since

The updated_at you last read. If the collection’s updated_at is different, to the microsecond, you get 409 and nothing changes. Leave it out to skip the check.

string format: date-time

The collection as updated. 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
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

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

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

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

if_unchanged_since doesn’t match the collection’s updated_at. Nothing was changed.

Returned with 409 when the item changed after the version you sent.

object
error
required

A short explanation.

string
updated_at
required

The item’s current updated_at.

string format: date-time