List posts (paginated feed)
GET /posts
The browse-page feed. Public posts visible to authenticated callers; the author’s own posts of any visibility are also returned. Anonymous access to this feed is not yet implemented.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Plain-text search over the post’s TSVECTOR. A future search DSL will replace this with a full query language.
Pre-baked feed selector. When set, applies a viewer-anchored filter on top of the other query params.
following— restrict to authors the caller follows (browse-page “Following” tab). Returns an empty page for callers who don’t follow anyone yet.latest(default) — no extra filter; same shape as omitting the param.
Admin-only. When true, soft-deleted posts appear
alongside live rows. Non-admin callers ignored.
Responses
Section titled “ Responses ”A page of posts
object
Feed entity. Wraps 1+ assets with descriptive metadata. The
members array is the ordered list of assets in the post;
cover_asset_id is the one shown in feed/grid cards.
object
Pointer to one of members[].asset_id — the chosen cover.
Defaults to members[0].asset_id when not set explicitly.
Optional standalone thumbnail asset, NOT a member of the
post. Used when the uploader wants a different image as
the feed thumbnail than any of the post’s assets (e.g. a
cropped detail or an entirely separate cover image). When
set, the feed card prefers this asset’s variants over
cover_asset_id.
Optional workflow state. Must reference a row in
workflow_state whose domain = 'post'. NULL = no
workflow tracking on this post.
An asset attached to a post, with its sort_order in the carousel and the asset payload joined-in to avoid an N+1.
object
object
Sha256 of the linked storage object
Flat tag value list — backwards-compatible projection
that pre-1.14.B consumers depend on. New consumers
prefer tag_details below which carries per-tag source
- confidence + provenance.
Per-tag source/confidence/provenance.
Same set of tags as tags, ordered the same way; this
field is the typed projection the frontend
AssetTagBadge renders.
One tag with full source/confidence/provenance metadata. Backs the per-source UI badge.
object
The tag value itself (e.g. “kittens”).
Where the tag came from. manual = operator typed it
in the UI; ai = generated by an AI tag job;
import = bulk CSV / EXIF / upstream system. AI runs
never overwrite manual or import rows.
Provider-supplied confidence in [0, 1] when source=‘ai’; null for manual and import tags. UI filter threshold lives in ai.tag.confidence_threshold (default 0.5).
Provider slug (openai / claude / ollama) for source=‘ai’.
Model identifier (gpt-4o / claude-3-5-sonnet) for source=‘ai’.
Free-form JSONB metadata blob (EXIF, custom fields, etc.).
object
Optional workflow state (domain = ‘asset’).
Post-upload processing pipeline state. pending means
background jobs (variant generation, EXIF extraction,
etc.) are still in flight — the original file at /file
is always available, but /variants/{key} URLs may
404 until processing completes. ready is the steady
state. failed surfaces in the UI as a retry affordance.
True iff a servable col thumbnail variant exists for this
asset AND the caller passes the content plane
(visibility.CanReadContent, ADR 0064). The client renders the
thumbnail only when this is true and otherwise shows a
placeholder WITHOUT requesting bytes — so a content-gated or
preview-less asset never fires a /variants/col (or /file)
request that would 404 and spam the console (#471). A
restricted asset the caller may not read reads identically to
“no preview” (false), so this never confirms restricted
(0064-safe).
Base64-encoded thumbhash (~30 bytes decoded) for instant blurred placeholder rendering on feed cards. Computed synchronously at upload for image assets. NULL for non-image resources.
Soft-delete timestamp. Non-null only on rows surfaced by
the admin include_deleted=true listing (the trash view);
null on live rows.
Optional reason captured at soft-delete time.
WebVTT subtitle / caption tracks attached to this asset. Empty array when none, or when the asset’s renderable kind doesn’t support subtitles (image, 3D, document, etc.). Tracks ride along with the asset; they do NOT appear in asset-count queries and do NOT federate as standalone activities.
One WebVTT subtitle track attached to an asset. NOT a first-class asset; rides along with its parent in the Asset.subtitle_tracks array. Tracks are uniquely identified by (asset_id, lang) — re-uploading the same lang replaces the existing row rather than creating a duplicate.
object
RFC 5646 / BCP 47 language tag (e.g. “en”, “en-US”, “ja”, “fr-CA”). The sentinel value “und” is reserved for sidecar files that matched by basename but had no inferrable language segment.
Optional human-readable label (“English (US)”, “Forced”, “Director’s commentary”). Empty string when not provided; never null.
CAS hash of the stored WebVTT file.
The format the track was uploaded in. The conversion worker stores WebVTT regardless; tracking the source lets operators re-convert if a converter bug surfaces.
1.0 for text-based sources (deterministic conversion). <1.0 for OCR’d bitmap sources like IDX (DVD subtitles). UI MAY surface a warning banner below 0.8.
Optional team scope (ADR 0010 Layer 5). When set, team-
scoped capability checks apply: callers who hold
posts.read scoped to this team or any ancestor team
can see the post regardless of visibility. NULL = no
team scope; only visibility / role / ACL gates apply.
Soft-delete timestamp. Non-null only on rows surfaced by
the admin include_deleted=true listing (the trash view);
null on live rows.
Optional reason captured at soft-delete time.
Authentication 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"}Unexpected server error
object
Human-readable error summary
Example
the request could not be completed