Skip to content

Add an asset to a post

POST
/posts/{id}/assets

Adds an existing asset to a post’s members, or changes its position if it’s already one.

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 post: you’re its author, you hold posts.admin or system.admin, or you hold posts.admin for the post’s team. A post that doesn’t exist or is deleted answers 404, and anyone else gets 403. You also need to be allowed to read the asset’s content, not just see it listed: 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. The asset doesn’t have to be yours. An asset you can’t read answers 404, as one that doesn’t exist or is deleted does.

Adding an asset that’s already a member replaces its sort_order, which goes back to 0 if you leave it out, and keeps the time it was first added. Members are listed by sort_order, then by the time recorded when each was added; members with the same value and the same recorded time, such as those added together when the post was created, have no fixed order. Negative numbers are accepted, and several members can share one. A number too large to read is refused with 400; one that is read but falls outside the 32-bit range wraps around instead of being refused. There’s no limit on members, and drafts can be changed too.

The post’s updated_at doesn’t change, and nothing is recorded as an activity. The server works out the post’s mature rating, AI label and search text again, and each server’s cached copy of the post is dropped on a best-effort basis.

id
required
string format: uuid

The post’s id.

object
asset_id
required

An existing asset you can read.

string format: uuid
sort_order

Position among the members; lower values come first. Defaults to 0, and equal values have no fixed order.

integer
0

The asset is a member of the post.

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