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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The collection’s id.
Request Body required
Section titled “Request Body required ”The post to add and its settings in this collection.
object
The post to add. It has to be one you can read.
Position in the collection; lower values come first. Defaults to 0.
Whether the post is listed. With false it stays in the collection but isn’t shown. Defaults to true.
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.
Responses
Section titled “ Responses ”The post is in the collection with the settings you sent.
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"}Resource not found
object
Human-readable error summary
Example
the request could not be completed