Partial update of a post
PATCH /posts/{id}
Optimistic concurrency: pass the post’s last-
known updated_at as if_unchanged_since; 409 if the
row has been edited since.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Request Body required
Section titled “Request Body required ”Partial update; only present fields are touched.
object
Optimistic-concurrency guard. When set, the
server returns 409 EditConflict if the post’s
updated_at has advanced past this value. Omit to
opt out of the check (legacy behaviour).
Responses
Section titled “ Responses ”Updated
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.
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 completedEdited by someone else after if_unchanged_since.
Returned with HTTP 409 when an optimistic-concurrency check
fails. Carries the row’s current updated_at so the
client can decide whether to reload + retry or surface a
diff UI.
object
Human-readable summary (e.g. “asset was edited by someone else”).
The current updated_at on the row (server-authoritative).