Social docs
Guides
Build with Social.
The end-to-end tutorial plus a shelf of focused single-feature guides. Most customers go through the tutorial once during integration, then come back here for the feature they're wiring next.
Looking for the full HTTP API? API reference. For the conceptual model in one page, Getting started.
Series
Tutorials
Focused
Single-feature guides
Webhooks
Durable outbound webhooks: signed deliveries (X-Pcft-Signature), a 16-event catalog, ~32h of backoff retries, delivery log, test pings, redelivery, and auto-disable recovery. At-least-once, strictly async.
Read more Notification preferences
Per-actor / per-kind opt-out. Mute follow notifications, keep mentions on. Producer checks the preference before inserting, so muted kinds never land in the inbox.
Read more Drafts
Save half a thought without shipping it. Author-only, hidden from feeds and lists. Promote via PATCH { status: 'published' } and the post_count counter is bumped at the transition.
Read more Suggested follows
Friend-of-a-friend recommendation with a top-by-followers cold-start fallback. 1-hour cache per (actor, limit). Excludes self, existing follows, mutes, blocks, and inbound blocks.
Read more Bookmarks
Personal save-for-later list per actor. Toggle on/off, list per actor. Bookmarks are private — no notifications, no counters, no public visibility.
Read more @-mentions
Parses @handle in post / comment bodies, indexes them, fires 'mention' notifications, and exposes a per-actor 'show me everywhere I'm tagged' feed.
Read more #-hashtags
Per-community tag directory, indexed at write time inside the same DB transaction as the post insert. Listing, detail with post count, posts-for-tag, prefix autocomplete.
Read more User search
Postgres FTS over a generated tsvector column on the actor table (display_name A + external_id B + bio C). Sub-100ms ranked search; block / mute filtering via requester_id.
Read more Post search
Postgres FTS over a generated tsvector column on the post table (title A + body B). Pick relevance ranking or recency ordering; status / expiry / block filters live at the SQL layer.
Read more Comment reactions
Same free-form `type` reactions as posts, this time on individual comments. Idempotent toggle, denormalised reaction_counts on the comment row, kind='reaction' notification with target_kind='comment'.
Read more Hashtag-followed feed
Per-actor follow list for hashtags. Posts using any followed tag get unioned into the actor's feed alongside posts from people they follow. Both chronological and ranked modes pick them up.
Read more Reposts
X-style retweet. Reposts ride on the existing post pipeline (kind='repost' + source_post_id) so feeds, reactions, comments all work without bespoke code. Idempotent toggle.
Read more Edit history
X-style edit window. Pre-edit snapshots in post_revision; edited_at + edit_count on the post row. Default 30-min window, configurable per-community. Drafts edit freely.
Read more Quote posts
X-style quote-tweet. kind='quote' + source_post_id + body via the existing post-create endpoint. The quote IS a post — its own engagement, edit history, mentions, hashtags. Source carries quote_count.
Read more Actor lists & list feeds
X-style lists. Curate a set of actors — private or public — and read a dedicated chronological or ranked feed of just those members. Block-aware membership, owner-managed.
Read more Muted terms
Per-actor keyword muting. Case-insensitive substring over post body + title, optional expiry, upsert on re-POST, idempotent DELETE. Filters the home + discover feeds; mind the short-page caveat.
Read more Community settings reference
Every supported community.settings key — ranking weights + half-life, max_comment_depth, auto_hide_flag_threshold, edit_window_minutes, max_group_conversation_size — with defaults, bounds, and the consuming feature.
Read more Sister docs
Cross-references
Social often pairs with other ProductCraft services:
- Auth — your customers' user accounts. Project them into Social as actors (see
02 · Profiles) so they show up with consistent identity across both services. - Mail — sending notification digest emails. Wire to Social's notification events (see
08 · Notifications) for the “you got a new follower” email. - Platform — PATs for CI/CD for the workspace credential pattern Social's customer-backend lane uses.