Skip to content

Add a post to a collection

POST
/collections/{id}/posts

Adds an existing post to a collection, or changes its settings there if it’s already in it. The collection holds a reference: the post isn’t copied and keeps its author, visibility and lifecycle.

A body that isn’t valid JSON, or that gives a field the wrong type, gets 400 before anything else is checked. Then you need to be signed in and allowed to edit the collection: you own it, or you hold collections.admin or system.admin granted globally. A sharing grant doesn’t count, whatever its level. A collection that doesn’t exist, is deleted or that you can’t edit answers 404.

You also need to be able to read the post: it’s yours, its visibility lets you in, or it’s shared with you. Holders of posts.admin or system.admin granted globally can also read private posts, and other people’s drafts that they could read once published. A post you can’t read answers 404, as one that doesn’t exist or is deleted does. Drafts you can read can be added, but they aren’t listed until they’re published. Mature settings aren’t checked here, so you can add a mature post that the list won’t show you.

sort_order defaults to 0, pinned to true and expires_at to no end. Adding a post that’s already in the collection replaces all three with what you send, so anything you leave out goes back to its default; the time it was first added stays. A post with pinned set to false, or whose expires_at has passed, stays in the collection but isn’t listed, and a time already passed is accepted. Negative values are accepted for sort_order, and a whole number the server can read but that doesn’t fit in 32 bits wraps around instead of being refused; one too large to read at all gets 400. There’s no limit on how many posts a collection holds.

Adding a published post records an activity in the same transaction, naming you, the post and the collection with its name, whatever the collection’s visibility. Each successful request records one, also when nothing changed. Adding a draft records none, and publishing it later doesn’t record the addition either. Nobody is notified, and the post and the collection’s own details don’t change.

The checks and the write aren’t one step. If the collection or the post is moved to the trash in between, the membership is still saved; if either has been removed for good, the request fails with 500. When two requests add the same post at once, the settings saved last stand.

id
required
string format: uuid

The collection’s id.

The post to add and its settings in this collection.

object
post_id
required

The post to add. It has to be one you can read.

string format: uuid
sort_order

Position in the collection; lower values come first. Defaults to 0.

integer
0
pinned

Whether the post is listed. With false it stays in the collection but isn’t shown. Defaults to true.

boolean
default: true
expires_at

When the post stops being listed. Leave it out or send null for no end. After that time it stays in the collection but isn’t shown.

string format: date-time
nullable

The post is in the collection with the settings you sent.

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

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed