Guides

Collections.

One primitive, two shapes. A bookmark collection is a private save folder (“Recipes”, “Read later”). A highlight collection is a profile-public reel that bypasses story expiry (“Travel 2026”). Both are ordered, owner-authored, and additive over the flat bookmark and highlight surfaces you already have.

Create a collection

kind defaults to bookmark (private). Pass highlight + visibility: "public" for a profile reel. A cover is optional — either an uploaded asset you own (cover_asset_id) or an external cover_url.

bash

curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "Content-Type: application/json" -H "Idempotency-Key: <uuid>" \
  -d '{"owner_actor_id":"<actor>","name":"Travel 2026","kind":"highlight","visibility":"public"}' \
  "https://social.productcraft.co/v1/communities/<c>/collections"

Add, reorder, remove posts

Items are posts, in curator order. Adding is idempotent per (collection, post). Only the owner can mutate a collection.

bash

# Add a post
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "Content-Type: application/json" \
  -d '{"caller_actor_id":"<actor>","post_id":"<post>","position":0}' \
  "https://social.productcraft.co/v1/communities/<c>/collections/<col>/items"

# Reorder it
curl -X PATCH -H "Authorization: Bearer pcft_live_..." \
  -H "Content-Type: application/json" \
  -d '{"caller_actor_id":"<actor>","position":3}' \
  "https://social.productcraft.co/v1/communities/<c>/collections/<col>/items/<post>"

# Remove it (body carries the caller)
curl -X DELETE -H "Authorization: Bearer pcft_live_..." \
  -H "Content-Type: application/json" -d '{"caller_actor_id":"<actor>"}' \
  "https://social.productcraft.co/v1/communities/<c>/collections/<col>/items/<post>"

Read semantics differ by kind

bookmark — private to the owner; item listing drops expired posts. (Unlike the flat bookmark list, which never filters — collection item listings always drop unpublished posts too.)
highlight — profile-public when visibility: "public"; item listing bypasses story expiry, so a 24h story stays in the reel indefinitely (the collection form of is_pinned).

List a profile's public collections, or a viewer's own (including private) with actor_id:

bash

# A profile's public highlight reels
curl -H "Authorization: Bearer pcft_live_..." \
  "https://social.productcraft.co/v1/communities/<c>/collections?owner_actor_id=<actor>&kind=highlight"

# The posts inside one, in curator order
curl -H "Authorization: Bearer pcft_live_..." \
  "https://social.productcraft.co/v1/communities/<c>/collections/<col>/items"

Bookmark straight into collections

The flat bookmark endpoint takes an optional collection_ids — the post is saved to the flat list and filed into each of the caller's collections in one call. Ids the caller doesn't own are skipped. The flat bookmark contract is unchanged.

bash

curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "Content-Type: application/json" \
  -d '{"actor_id":"<actor>","collection_ids":["<col>"]}' \
  "https://social.productcraft.co/v1/communities/<c>/posts/<post>/bookmark"