Skip to content

List posts

GET
/posts

Returns a page of posts, newest first, for the browse feed, profiles, team pages and the drafts list. Signed-in users see what the post read rule allows them; with public mode on, visitors who aren’t signed in can call this too and see public posts only, and with it off they get 401.

Without visibility, a signed-in feed covers every tier except private; asking for your own author_ref, or using liked_by, drops that default so private posts you may read are included. Every filter only narrows the page: the read rule applies to every row whatever you send. Drafts appear only with draft=true. Mature posts appear only where the mature settings allow them.

Pages use a cursor: limit is clamped to 1-200 and defaults to 50, and when more rows follow, next_cursor is set for you to send back unchanged with the same dir. A page can hold fewer posts than limit, even none, while next_cursor is still set. Unless your feed settings show them, members you can’t see are removed from each post and a post left with no members is dropped, unless it is yours; a post deleted while the page is built is skipped. A malformed cursor is answered with 500.

author_ref
integer format: int64

Only posts by this user ref. Asking for your own ref also includes your private posts.

liked_by
integer format: int64

Only posts this user has liked. The read rule still applies, so you get only liked posts you could already read.

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

Only posts at this visibility tier. Without it, a signed-in feed covers every tier except private, and a visitor who isn’t signed in gets public posts.

q
string
<= 200 characters

Text to search for in the post’s searchable text, after trimming. The search endpoint has the full query language. The 200-character limit shown isn’t checked.

tag
Array<string>

Only posts carrying this tag. Repeat it to require several: ?tag=a&tag=b returns posts carrying every one. Matching is exact and case-sensitive. An empty value is ignored, but a value made of spaces is matched as sent.

team_id
string format: uuid

Only posts belonging to this team. It narrows the page and grants nothing: team membership doesn’t let you read more. An unknown team gives an empty page, but a deleted team’s posts still match, within the read rule.

kind
string
<= 200 characters

Only posts with at least one member asset of the given kinds, comma-separated, for example image,video. Kinds follow the card badges: image, video, pdf, audio, sequence, font, sprite, 3d, ebook, doc, audiobook, archive and placeholder. Members you can’t read don’t count. Names are case-insensitive and unknown ones are ignored; a list with no known name selects nothing, and an empty value is no filter.

ai
string
Allowed values: pure not_pure

not_pure leaves out posts that are purely AI-generated; posts that mix AI and human work, or have an undeclared contributor, stay. pure returns only purely AI-generated posts. It is a filter, not a restriction: leaving it out hides nothing. Any other value is refused with 400.

mature
string
Allowed values: not_mature

not_mature leaves out posts flagged mature, your own included. It only narrows what the mature settings already allow; no value asks for mature posts. Any other value is refused with 400.

feed
string
Allowed values: latest following

following returns only posts by people you follow, from teams you follow or carrying a tag you follow, still within the read rule; it is empty if you follow no people, teams or tags. latest, the default, adds no filter, and any other value is treated as latest.

dir
string
default: desc
Allowed values: asc desc

Sort direction over posting time and id: desc, the default, is newest first and asc oldest first. A cursor belongs to the direction that produced it, so start again without cursor after changing dir. Any other value is treated as desc.

limit
integer
default: 50 >= 1 <= 200

How many posts to return, from 1 to 200; values outside that range are clamped. Defaults to 50.

cursor
string

The next_cursor from the previous page, sent back unchanged with the same dir. A malformed value is answered with 500.

include_deleted
boolean

With true, soft-deleted posts are included in a reduced form. Only system.admin holders can use it; for anyone else it is ignored.

draft
boolean

With true, the page holds drafts only, and only drafts you may read: your own, and other people’s if you hold posts.admin or system.admin granted globally and the draft’s visibility would let you read it once published. Without it, every listing returns published posts only and leaves out your own drafts too.

A page of posts and, when more rows follow, the cursor for the next page.

object
items
required

The posts on this page.

Array<object>

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
id
required
string format: uuid
author_user_ref
required
integer format: int64
author

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
ref
required
integer format: int64
username
required

The handle. Also the profile link target (/users/by-username/{username}).

string
display_name
required

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.

string
avatar_url

The avatar URL stored on the user’s profile, if there is one; left out when none is stored.

string
nullable
title
required
string
description
required
string
visibility
required
string
Allowed values: public private org-only followers explicit-share
cover_asset_id

The asset shown as the post’s cover. A post created without one uses its first member.

string format: uuid
nullable
cover_thumbnail_asset_id

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.

string format: uuid
nullable
cover_focal_x

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.

number format: double
nullable
cover_focal_y

The same point down the picture’s height, from 0 (top edge) to 1 (bottom edge). See cover_focal_x.

number format: double
nullable
draft
required

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.

boolean
comments_enabled
required

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.

boolean
state_id

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.

string format: uuid
nullable
ai_provenance

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.

string
nullable
Allowed values: none assisted generated
posted_at
required
string format: date-time
like_count
required
integer format: int64
liked

Whether you have liked this post. Always false when you aren’t signed in.

boolean
comment_count
required
integer format: int64
comments_preview

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.

Array<object>

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
id
required
string format: uuid
body
required

The comment’s text as written, in full.

string
created_at
required
string format: date-time
author

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
ref
required
integer format: int64
username
required

The handle. Also the profile link target (/users/by-username/{username}).

string
display_name
required

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.

string
avatar_url

The avatar URL stored on the user’s profile, if there is one; left out when none is stored.

string
nullable
remote_display_name

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.

string
nullable
tags
required
Array<string>
members
required
Array<object>

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
asset_id
required
string format: uuid
sort_order
required
integer
restricted
required

true when you aren’t allowed to see this asset; asset is then left out.

boolean
owner_display_name

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.

string
asset

The asset. Left out when restricted is true.

object
id
required
string format: uuid
restricted
required

true when this is a placeholder for an asset you can’t open. Always present, so check it before reading anything else.

boolean
owner_display_name

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.

string
title
string
description
string
asset_type
integer format: int64
owner_user_ref
integer format: int64
nullable
status

Anonymous visitors see only active assets. draft and archived don’t hide an asset from other signed-in accounts.

string
Allowed values: draft active archived
mature

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.

boolean
ai_provenance

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.

string
nullable
Allowed values: none assisted generated
file_hash

The SHA-256 of the linked file, as used by GET /storage/objects/{hash}. Absent when no file is linked.

string
nullable
file_extension
string
nullable
file_size_bytes

The file’s size in bytes, when recorded. Assets created with POST /assets don’t record it.

integer format: int64
nullable
tags

The asset’s tags, as plain strings. tag_details has the same tags with where each one came from.

Array<string>
tag_details

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.

Array<object>

One tag and where it came from.

object
value
required

The tag.

string
source
required

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.

string
Allowed values: manual ai import
confidence

For AI tags, the provider’s confidence from 0 to 1. Absent for other tags.

number format: double
nullable
created_by_provider

For AI tags, the provider that suggested it, such as openai or ollama.

string
nullable
created_by_model

For AI tags, the model that suggested it.

string
nullable
metadata

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
key
additional properties
any
state_id

The asset’s workflow state, if it has one.

string format: uuid
nullable
team_id

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.

string format: uuid
nullable
processing_status

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.

string
Allowed values: pending ready failed
preview_available

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.

boolean
ladder_available

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.

boolean
scrub_available

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.

boolean
anonymously_visible

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.

boolean
thumbhash

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.

string
nullable
pixel_width

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.

integer format: int32
nullable
pixel_height

The height to go with pixel_width.

integer format: int32
nullable
created_at
string format: date-time
updated_at

When the asset last changed, including changes made by background processing. Send it as if_unchanged_since when you update.

string format: date-time
deleted_at

When the asset was deleted. Only soft-deleted assets in GET /assets?include_deleted=true results have it.

string format: date-time
nullable
deleted_reason

The reason given when it was deleted, if any. Appears with deleted_at.

string
nullable
subtitle_tracks

Subtitle and caption tracks for the asset. Only GET /assets/{id} includes them, and only when there are some.

Array<object>

One subtitle or caption track. An asset has at most one per language; uploading another for the same language replaces it.

object
lang
required

The track’s language tag, such as en or fr-CA. und means the language couldn’t be worked out from the file name.

string
label

A display name, such as English (US) or Forced. Empty when none was given.

string
file_hash
required

The SHA-256 of the stored WebVTT file.

string
source_format
required

The format the track was uploaded in. It’s stored as WebVTT whatever the source format.

string
Allowed values: vtt srt ssa ass sub idx
confidence
required

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.

number format: float
<= 1
created_at
string format: date-time
card_fields

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.

Array<object>

One field value to show on a card.

object
code
required

The field’s code.

string
label
required

The field’s name, for a caption.

string
value
required

The value as one line of text. Never empty: a field with no value is left out instead.

string
origin

The federated instance this asset came from. Absent for local assets.

object
peer_id
required
string format: uuid
display_name
required
string
instance_url
string
owner

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
ref
required
integer format: int64
username
required

The handle. Also the profile link target (/users/by-username/{username}).

string
display_name
required

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.

string
avatar_url

The avatar URL stored on the user’s profile, if there is one; left out when none is stored.

string
nullable
origin_server_id
string format: uuid
nullable
origin

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
peer_id
required
string format: uuid
display_name
required
string
instance_url
string
team_id

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.

string format: uuid
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
deleted_at

When the post was moved to the trash. Only posts listed from the trash have it; it is absent everywhere else.

string format: date-time
nullable
deleted_reason

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.

string
nullable
next_cursor

Send this back as cursor to get the next page. Left out when no further rows were found.

string
nullable

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

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed