Create a post
POST /posts
Creates a post from one or more existing assets, with its title,
description, tags and cover. You must be able to read each asset,
both its record and its content; an asset you can’t read, or one
that doesn’t exist, is answered with 404. Without draft: true the
post is published at once, which needs the posts.publish or
system.admin capability.
Visibility defaults to org-only, and the cover to the first asset
in members. Members are listed by sort_order (0 when left out);
equal values have no fixed order, and an asset listed twice is
stored once with its last sort_order. Tags are trimmed and
de-duplicated, and blank ones are dropped. A team_id must name a
live team you belong to or where you hold posts.admin, unless you
hold system.admin (404 otherwise). A collection_id adds the post
to that collection without checking that you may edit it; an unknown
collection is 404.
Everything is written in one transaction, with the federation activity for a published post. Afterwards, the server tries to notify people mentioned in the title or description; this is best effort, and a notification that fails or is skipped doesn’t undo the post. Whether those people can read the post isn’t checked, so a mention in a draft or in a post they can’t read can still send them its title. If reading the new post back fails at that point, you get 500 although the post exists.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
The title. Defaults to empty. The 500-character limit shown isn’t checked.
The description. Defaults to empty. The server tries to notify users mentioned in it or in the title.
Who can read the post. org-only, the default, is any signed-in
user; public also reaches visitors when public mode is on;
followers is people who follow you; private is you and holders
of posts.admin or system.admin granted globally;
explicit-share is you and people it has been shared with.
The cover asset. Defaults to the first asset in members; any asset
you can read is allowed, member or not.
An optional separate thumbnail for the cover. It can be any asset you can read; it needn’t be a member.
Where the cover’s square crop is centred horizontally, as a fraction
of the picture’s width from 0 to 1. Null means centred. Send it with
cover_focal_y: one without the other, or a value outside 0-1, is
refused with 400.
The vertical half of the cover’s focal point, as a fraction of the
picture’s height. See cover_focal_x.
With true, the post is created as a draft that only you and
holders of posts.admin or system.admin granted globally whom its
visibility admits can see; publish it later with POST /posts/{id}/publish. Left out or false, the post is published at
once, which needs posts.publish or system.admin.
Whether the post accepts new comments. Defaults to true.
The assets in the post, at least one, each an existing asset you can read.
object
An existing asset you can read.
Position among the members; lower values come first. Defaults to 0, and equal values have no fixed order.
Tags for the post, trimmed and de-duplicated; blank ones are dropped.
A collection to add the post to, pinned. Whether you may edit the collection isn’t checked; an unknown collection is 404.
The team the post belongs to. It must be a live team you belong to
or where you hold posts.admin, unless you hold system.admin;
otherwise 404. A team doesn’t widen who can read the post.
Responses
Section titled “ Responses ”The new post, in the form GET /posts/{id} returns.
A post: one or more assets shown together with a title, a
description and tags. members lists the assets in order and
cover_asset_id names the cover picture.
object
The author’s name and picture, for showing with the post.
author_user_ref is always present, but this object is left out
when the author has chosen to hide their profile from people who
aren’t signed in and you aren’t signed in, and when the author’s
account no longer exists.
object
The handle. Also the profile link target
(/users/by-username/{username}).
The name to show, never empty: the profile’s display name, then the
account’s full name, then the username, and as a last resort user
followed by the account number. For readers who aren’t signed in,
the account’s full name is skipped; the display name and username
are still used.
The avatar URL stored on the user’s profile, if there is one; left out when none is stored.
The asset shown as the post’s cover. A post created without one uses its first member.
An optional cover picture that doesn’t have to be one of the post’s
members. When it is set, collection covers show it in place of
cover_asset_id.
Where to centre the cover picture when it is cropped, across its
width: a fraction from 0 (left edge) to 1 (right edge). Absent when
no point has been chosen. It is always set, or left out, together
with cover_focal_y.
The same point down the picture’s height, from 0 (top edge) to 1
(bottom edge). See cover_focal_x.
true while the post hasn’t been published, false once it has.
Only its author and people with posts.admin or system.admin can
read a draft. Those people still go through the post’s visibility
as they would once it is published, so a followers-only or
explicit-share draft also needs a follow or a share, unless they
wrote it.
Whether the post accepts new comments and replies. When it’s
false, adding a comment or a reply returns 409 with the error
comments_disabled; comments already on the post aren’t removed.
New posts accept comments unless they are created with false, and
the setting can be changed when the post is updated.
The id of the post’s workflow state. A request can’t set it: it is
set when the post is created and changed by publishing or
unpublishing. Use draft to tell whether the post is published.
Whether generative AI was used, worked out by the server from the
post’s members and its two cover pictures (cover_asset_id and
cover_thumbnail_asset_id), leaving out assets in the trash. The
post is generated if any of them is generated, otherwise
assisted if any is assisted, and none only when every one of
them is none.
In every other case the field is absent: when one of them has no
statement and none says generated or assisted, or when there is
nothing to count. Absent means not stated, which isn’t the same as
none. A request can’t set it.
Whether you have liked this post. Always false when you aren’t
signed in.
Up to two of the newest comments on the post, newest first, for showing with it. Only top-level comments are included: replies and deleted comments are left out. Absent when there are none. The post’s comment list has the full thread.
One comment as it is shown with a post: who wrote it, its text and when. Replies, likes and the other comment details aren’t included; the post’s comment list has them.
object
The comment’s text as written, in full.
The commenter’s name and picture. Left out when the commenter has
chosen to hide their profile from people who aren’t signed in and
you aren’t signed in, when their account no longer exists, and for a
comment received from a paired instance, which has
remote_display_name instead.
object
The handle. Also the profile link target
(/users/by-username/{username}).
The name to show, never empty: the profile’s display name, then the
account’s full name, then the username, and as a last resort user
followed by the account number. For readers who aren’t signed in,
the account’s full name is skipped; the display name and username
are still used.
The avatar URL stored on the user’s profile, if there is one; left out when none is stored.
For a comment received from a paired instance: the name this instance has stored for the person who wrote it. Absent for comments written on this instance, and when no name has been received.
One asset in a post: its place in the order (sort_order) and the
asset itself.
If you aren’t allowed to see the asset, the entry stays in the list
as a placeholder, so you can tell something is there: restricted
is true, asset is left out, and only asset_id, sort_order
and, when there is one, owner_display_name are given.
object
true when you aren’t allowed to see this asset; asset is then
left out.
Given only when restricted is true: the name of the asset’s
owner, so the placeholder can say whose work it is. Absent when
there is no name to show.
The asset. Left out when restricted is true.
object
true when this is a placeholder for an asset you can’t open.
Always present, so check it before reading anything else.
On a placeholder only: the owner’s display name. Absent when there’s no name that can be shown, for example to an anonymous visitor when the owner hides their profile from them.
Anonymous visitors see only active assets. draft and archived don’t hide an asset from other signed-in accounts.
true when the work is rated mature. The rating is about who has
chosen to see mature work; it’s separate from the sensitivity tier,
which decides who is allowed to see it.
A viewer qualifies for mature work when the instance allows it and
they’ve opted in; signed-in owners and system.admin are let
through either way. For anyone else, the browse list leaves mature
assets out and their files are refused, but GET /assets/{id} still
returns the record, so use this flag to label what you show. GET /assets reports false on every readable item, and placeholders
leave it out.
The maker’s statement about generative AI in this work: none,
assisted or generated. Absent means nobody has said, which isn’t
the same as none; show it as “not stated” or show nothing. It’s a
label people can filter by, never a reason to hide the work. GET /assets leaves it out even when it’s set.
The SHA-256 of the linked file, as used by GET /storage/objects/{hash}. Absent when no file is linked.
The file’s size in bytes, when recorded. Assets created with POST /assets don’t record it.
The asset’s tags, as plain strings. tag_details has the same tags
with where each one came from.
The same tags with their source and, for AI tags, confidence and
model. Only GET /assets/{id} includes it, and only when the asset
has tags.
One tag and where it came from.
object
The tag.
manual for tags people added, ai for AI tagging, import for
imported tags. AI tagging replaces only earlier AI tags; replacing
the tag list with PATCH /assets/{id} removes all three kinds.
For AI tags, the provider’s confidence from 0 to 1. Absent for other tags.
For AI tags, the provider that suggested it, such as openai or ollama.
For AI tags, the model that suggested it.
Free-form JSON stored with the asset. Clients can keep their own keys here, and background processing adds its own sections. Updating it replaces the whole object.
object
The asset’s workflow state, if it has one.
The team the asset is assigned to. It’s set when the asset is created and can’t be changed. Absent when there is none, and on placeholders.
Where the asset’s preview processing stands, as recorded. pending
means the preview job hasn’t finished or never started: an asset
with no linked file, or whose job couldn’t be queued, stays
pending, and its variants can return 404. ready means the
preview job finished or none was needed; other background jobs, such
as transcription, may still be running. failed means the preview
job stopped with an error. While a job runs, the value can also be
processing, which isn’t in the list below. Anonymous visitors see
only ready assets.
Like the preview flags, this is a stored marker: it doesn’t check that the file or its renditions are actually in storage.
true when a col thumbnail is recorded for the file and you may
see the asset’s pictures. When it’s false, don’t request one.
This and the other preview hints (ladder_available,
scrub_available, thumbhash) come from the server’s records, not
from storage, so a request can still fail if a stored copy is
missing. “May see the pictures” follows the sensitivity tier; on
GET /assets/{id} it doesn’t take the mature rating into account,
so a viewer who doesn’t qualify for mature work can see true and
still have the request refused.
true when every size in the instance’s preview ladder (see GET /previews) is recorded and you may see the asset’s pictures, on the
same basis as preview_available. Check it before requesting the
larger sizes; preview_available covers only the col thumbnail.
true when a sprites.vtt hover-scrub file is recorded and you may
see the asset’s pictures, on the same basis as preview_available.
Whether an anonymous visitor would be shown this asset: it’s live,
active, public and processed. The answer is the same for
everyone, so it says nothing about what you can see. It doesn’t take
the mature rating or the instance’s anonymous-browsing setting into
account. Useful when choosing a cover for something public.
A small encoded blur of the image (a base64 thumbhash) to show while
it loads. Absent when there isn’t one or you may not see the asset’s
pictures, on the same basis as preview_available.
The width in pixels of the image the previews are made from, when it
has been recorded. For files without pixels, such as 3D models,
fonts or audio, it’s the size of the image their preview is drawn
from. Photos are measured after their EXIF rotation. pixel_width
and pixel_height always come together or not at all.
The height to go with pixel_width.
When the asset last changed, including changes made by background processing. Send it as if_unchanged_since when you update.
When the asset was deleted. Only soft-deleted assets in GET /assets?include_deleted=true results have it.
The reason given when it was deleted, if any. Appears with deleted_at.
Subtitle and caption tracks for the asset. Only GET /assets/{id}
includes them, and only when there are some.
One subtitle or caption track. An asset has at most one per language; uploading another for the same language replaces it.
object
The track’s language tag, such as en or fr-CA. und means the
language couldn’t be worked out from the file name.
A display name, such as English (US) or Forced. Empty when none
was given.
The SHA-256 of the stored WebVTT file.
The format the track was uploaded in. It’s stored as WebVTT whatever the source format.
How reliable the conversion to WebVTT is, from 0 to 1. Every format accepted today converts from text and gives 1; image-based subtitles, such as DVD IDX files, aren’t accepted yet.
Field values to show on a card, already formatted and in the order the operator set. Absent when there are none and on placeholders. Only fields without a read restriction can appear.
One field value to show on a card.
object
The field’s code.
The field’s name, for a caption.
The value as one line of text. Never empty: a field with no value is left out instead.
The federated instance this asset came from. Absent for local assets.
object
The owner’s name and avatar, for showing on a card. Absent when the owner can’t be shown, for example to an anonymous visitor when the owner hides their profile from them, and on placeholders.
object
The handle. Also the profile link target
(/users/by-username/{username}).
The name to show, never empty: the profile’s display name, then the
account’s full name, then the username, and as a last resort user
followed by the account number. For readers who aren’t signed in,
the account’s full name is skipped; the display name and username
are still used.
The avatar URL stored on the user’s profile, if there is one; left out when none is stored.
The federated instance this post came from. Absent for local posts, and when this instance no longer has a record of the one it came from.
object
The team the post belongs to, if any. The team doesn’t change who
can read the post: its visibility and any sharing decide that.
When the post was moved to the trash. Only posts listed from the trash have it; it is absent everywhere else.
The reason given when the post was moved to the trash, if there was one. Like deleted_at, only posts listed from the trash have it.
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"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed