Social API.
Communities, posts, ranked feeds, stories, polls, moderation — every endpoint generated from the live OpenAPI spec.
Social is keyed on community_id for the customer-backend lane. Each end-user of your product is projected as an actor viaPOST /v1/communities/{community_id}/actors. All subsequent posts, edges, comments, votes, and views reference the actor by their actor.id — the UUID Social returned at upsert time. Your customer-supplied external_id is only the upsert key and the input to the GET .../actors/by-external/{external_id} lookup; every other parameter named actor_id takes the UUID.
The customer-backend lane authenticates with your workspace API key (pcft_live_*) as a bearer token. The admin lane under /v1/workspaces/{workspace_id}/... accepts a API key bearer, a PlatformUser bearer (console JWT), or the platform session cookie — the same pcft_live_* key you use below also works there, provided its policy grants the workspace-scoped permissions each route names.
Base URL
https://api.social.productcraft.coAuth
Authorization: Bearer …Spec version
OpenAPI spec
https://api.social.productcraft.co/docs-jsonActors
Members of a community (actors): create or upsert them from your own user ids, read, update, and delete them.
- post
/v1/communities/{community_id}/actors/batchBulk actor upsert (max 200 per call) — the import lane. - post
/v1/communities/{community_id}/actors/by-external/batchBatch-resolve external_ids to actors (max 200 per call). - get
/v1/communities/{community_id}/actorsList actors in a community. - post
/v1/communities/{community_id}/actorsUpsert an actor by external_id. - get
/v1/communities/{community_id}/actors/by-external/{external_id}Look up an actor by the customer-supplied external_id. - get
/v1/communities/{community_id}/actors/{actor_id}Get an actor by its UUID. - patch
/v1/communities/{community_id}/actors/{actor_id}Update actor profile fields. - delete
/v1/communities/{community_id}/actors/{actor_id}Delete an actor.
Assets
Image and video uploads: request an upload URL, finalize, read and delete assets you attach to posts.
- post
/v1/communities/{community_id}/assetsUpload media. - post
/v1/communities/{community_id}/assets/{asset_id}/completeFinalize a presigned-PUT video upload. - get
/v1/communities/{community_id}/assets/{asset_id}Fetch one asset with freshly-minted presigned rendition URLs. - delete
/v1/communities/{community_id}/assets/{asset_id}Delete an asset — removes every stored rendition object, then the row. - get
/v1/communities/{community_id}/actors/{actor_id}/assetsList an actor's uploaded assets — the "your uploads" surface + GDPR export walk.
Bookmarks
Posts a member saved for later.
Collections
Named, ordered collections of posts a member curates.
- get
/v1/communities/{community_id}/collectionsList collections. - post
/v1/communities/{community_id}/collectionsCreate a collection. - get
/v1/communities/{community_id}/collections/{collection_id}Fetch one collection. - patch
/v1/communities/{community_id}/collections/{collection_id}Update a collection (owner only) — rename, cover, visibility, reorder position. - delete
/v1/communities/{community_id}/collections/{collection_id}Delete a collection (owner only). - get
/v1/communities/{community_id}/collections/{collection_id}/itemsList a collection's posts in curator order. - post
/v1/communities/{community_id}/collections/{collection_id}/itemsAdd a post to a collection (owner only). - patch
/v1/communities/{community_id}/collections/{collection_id}/items/{post_id}Reorder a post within a collection (owner only). - delete
/v1/communities/{community_id}/collections/{collection_id}/items/{post_id}Remove a post from a collection (owner only).
Comments
Comments and threaded replies on posts: create, read, edit, delete, and the moderation queue for comments awaiting approval.
- get
/v1/communities/{community_id}/posts/{post_id}/commentsList comments on a post. - post
/v1/communities/{community_id}/posts/{post_id}/commentsAdd a comment on a post. - get
/v1/communities/{community_id}/posts/{post_id}/comments/{comment_id}Get a single comment by id. - patch
/v1/communities/{community_id}/posts/{post_id}/comments/{comment_id}Update a comment's body, status, or visibility. - delete
/v1/communities/{community_id}/posts/{post_id}/comments/{comment_id}Soft-delete a comment. - post
/v1/communities/{community_id}/posts/{post_id}/comments/{comment_id}/approveApprove a pending_approval comment (restricted-actor pre-moderation). - post
/v1/communities/{community_id}/posts/{post_id}/comments/{comment_id}/pinPin a top-level comment (post-author only). - delete
/v1/communities/{community_id}/posts/{post_id}/comments/{comment_id}/pinUnpin a comment (post-author only).
Connections
Integrations that connect a community to another ProductCraft product.
- post
/v1/communities/{community_id}/connectionsRequest a connection (mutual follow). - post
/v1/communities/{community_id}/connections/{dst_actor_id}/{src_actor_id}/acceptAccept `src_actor_id`'s connection request as `dst_actor_id`: approves the follow request AND creates the reverse… - delete
/v1/communities/{community_id}/connections/{actor_id}/{other_actor_id}Sever a connection COMPLETELY: deletes the follow edges in both directions and withdraws any pending requests either…
Conversations
Direct messages: one-to-one and group conversations, their members and messages.
- get
/v1/communities/{community_id}/conversations/unread-countGlobal unread message count for the caller across every conversation in this community. - get
/v1/communities/{community_id}/conversationsList the caller's conversations in this community, most-recent-activity first. - post
/v1/communities/{community_id}/conversationsOpen a conversation. - post
/v1/communities/{community_id}/conversations/{conversation_id}/membersAdd a member to a group conversation. - patch
/v1/communities/{community_id}/conversations/{conversation_id}/members/{member_actor_id}Update a participant (task 025). - delete
/v1/communities/{community_id}/conversations/{conversation_id}/members/{member_actor_id}Remove a participant. - get
/v1/communities/{community_id}/conversations/{conversation_id}Get a single conversation by id. - patch
/v1/communities/{community_id}/conversations/{conversation_id}Conversation-level update (task 025). - delete
/v1/communities/{community_id}/conversations/{conversation_id}Leave the conversation. - get
/v1/communities/{community_id}/conversations/{conversation_id}/messagesList messages in the conversation. - post
/v1/communities/{community_id}/conversations/{conversation_id}/messagesSend a message in the conversation. - get
/v1/communities/{community_id}/conversations/{conversation_id}/messages/{message_id}Fetch a single message (task 024) — resolves a reply target without paging the whole thread. - patch
/v1/communities/{community_id}/conversations/{conversation_id}/messages/{message_id}Edit a message body. - delete
/v1/communities/{community_id}/conversations/{conversation_id}/messages/{message_id}Soft-delete a message. - post
/v1/communities/{community_id}/conversations/{conversation_id}/readMark messages as read up to a given timestamp (default: now()).
Counters
Cached counts (followers, posts, reactions) for a member or a post.
- get
/v1/communities/{community_id}/countersBatch counters (max 100 actors per call) — render a member list with follower badges from ONE call instead of one per… - get
/v1/communities/{community_id}/actors/{actor_id}/countersDenormalised counters for one actor (followers, following, posts, comments, blocks).
Dm-Reactions
Reactions on direct messages.
- get
/v1/communities/{community_id}/conversations/{conversation_id}/messages/{message_id}/reactionsList the reactions on a direct message. - post
/v1/communities/{community_id}/conversations/{conversation_id}/messages/{message_id}/reactionsAdd a reaction to a direct message. - delete
/v1/communities/{community_id}/conversations/{conversation_id}/messages/{message_id}/reactions/{actor_id}/{type}Remove the (actor, type) reaction.
Drafts
A member's draft and scheduled posts.
- get
/v1/communities/{community_id}/actors/{actor_id}/draftsList the actor's drafts (status='draft'). - get
/v1/communities/{community_id}/actors/{actor_id}/scheduled-postsList the actor's scheduled posts (status='scheduled'), ordered soonest-to-publish first. - get
/v1/communities/{community_id}/actors/{actor_id}/archivedList the actor's archived posts (status='archived'), newest-first.
Edges
The social graph: follow, mute, block and restrict between members, follow requests for private members, and the lists that read them.
- post
/v1/communities/{community_id}/follows/batchBulk follow creation (max 200 per call) — the graph-import lane. - post
/v1/communities/{community_id}/followsFollow another actor. - post
/v1/communities/{community_id}/follow-requests/{dst_actor_id}/{src_actor_id}/approveApprove a pending follow request (task 014). - delete
/v1/communities/{community_id}/follow-requests/{dst_actor_id}/{src_actor_id}Decline a pending follow request (task 014). - get
/v1/communities/{community_id}/actors/{actor_id}/follow-requestsList incoming follow requests for a (private) actor, newest-first (task 014). - delete
/v1/communities/{community_id}/follows/{src_actor_id}/{dst_actor_id}Unfollow. - get
/v1/communities/{community_id}/actors/{actor_id}/followingList the actors this actor follows. - get
/v1/communities/{community_id}/actors/{actor_id}/followersList the actors who follow this actor. - post
/v1/communities/{community_id}/mutesMute another actor. - delete
/v1/communities/{community_id}/mutes/{src_actor_id}/{dst_actor_id}Unmute. - get
/v1/communities/{community_id}/actors/{actor_id}/mutesList actors this actor has muted. - post
/v1/communities/{community_id}/hidesHide a post from the actor's feeds ("not interested"). - delete
/v1/communities/{community_id}/hides/{src_actor_id}/{post_id}Un-hide a post. - get
/v1/communities/{community_id}/actors/{actor_id}/hidesList the posts an actor has hidden, newest-first. - post
/v1/communities/{community_id}/dismissed-suggestionsDismiss an actor from your follow suggestions ("don't suggest"). - delete
/v1/communities/{community_id}/dismissed-suggestions/{src_actor_id}/{dst_actor_id}Un-dismiss a suggestion. - get
/v1/communities/{community_id}/actors/{actor_id}/dismissed-suggestionsList actors this actor has dismissed from suggestions. - post
/v1/communities/{community_id}/blocksBlock another actor. - delete
/v1/communities/{community_id}/blocks/{src_actor_id}/{dst_actor_id}Unblock. - get
/v1/communities/{community_id}/actors/{actor_id}/blocksList actors this actor has blocked. - post
/v1/communities/{community_id}/restrictsRestrict another actor (Instagram-style). - delete
/v1/communities/{community_id}/restricts/{src_actor_id}/{dst_actor_id}Unrestrict. - get
/v1/communities/{community_id}/actors/{actor_id}/restrictsList actors this actor has restricted. - get
/v1/communities/{community_id}/actors/{src_actor_id}/relationshipsBatched pairwise relationship lookup: does this actor follow / mute / block / restrict each of up to 100 others (and…
Feed
Feeds: a member's home timeline, a member's own posts, and the community-wide feeds.
- get
/v1/communities/{community_id}/actors/{actor_id}/feedFeed for an actor: their own posts + posts from actors they follow, with blocks excluded. - get
/v1/communities/{community_id}/discover-feedDiscover / explore feed (task 019). - get
/v1/communities/{community_id}/lists/{list_id}/feedList-scoped feed (task 018).
Flags
Reports: members flag posts, comments or other members for moderation.
Hashtag-Follows
Hashtags a member follows.
- get
/v1/communities/{community_id}/actors/{actor_id}/hashtag-followsList the hashtags an actor follows. - post
/v1/communities/{community_id}/actors/{actor_id}/hashtag-followsFollow a hashtag on behalf of an actor. - delete
/v1/communities/{community_id}/actors/{actor_id}/hashtag-follows/{tag}Unfollow a hashtag.
Hashtag-Posts
Posts carrying a hashtag.
Insights
Per-post and per-member engagement insights.
- get
/v1/communities/{community_id}/posts/{post_id}/insightsAggregate insights for a post: total views, unique reach, engagement counts, and a daily views/reach series over… - get
/v1/communities/{community_id}/actors/{actor_id}/insightsAn actor's follower time series: live follower_count plus a nightly-snapshot daily series over ?from/?to (default…
Lists
Member lists: named lists of members a member curates, and their members.
- get
/v1/communities/{community_id}/listsList discoverable lists in this community. - post
/v1/communities/{community_id}/listsCreate a new list. - get
/v1/communities/{community_id}/lists/{list_id}Get one list by id. - patch
/v1/communities/{community_id}/lists/{list_id}Update list name / description / visibility. - delete
/v1/communities/{community_id}/lists/{list_id}Delete a list. - get
/v1/communities/{community_id}/lists/{list_id}/membersList members of a list. - post
/v1/communities/{community_id}/lists/{list_id}/membersAdd a member to a list. - delete
/v1/communities/{community_id}/lists/{list_id}/members/{member_actor_id}Remove a member from a list.
Mentions
Posts and comments that mention a member.
Muted-Terms
Words and phrases a member mutes from their feeds, messages and mentions.
- get
/v1/communities/{community_id}/actors/{actor_id}/muted-termsList the actor's currently-active muted terms, newest-first. - post
/v1/communities/{community_id}/actors/{actor_id}/muted-termsAdd (or refresh) a muted term for the actor. - delete
/v1/communities/{community_id}/actors/{actor_id}/muted-terms/{term}Remove a muted term.
Notification-Preferences
Which notifications a member receives.
Notifications
A member's in-app notifications: list, mark read, unread count.
- get
/v1/communities/{community_id}/actors/{actor_id}/notificationsList notifications for an actor (newest first). - get
/v1/communities/{community_id}/actors/{actor_id}/notifications/unread-countCount unread notifications for an actor. - patch
/v1/communities/{community_id}/actors/{actor_id}/notifications/{notification_id}Mark a single notification as read or unread. - post
/v1/communities/{community_id}/actors/{actor_id}/notifications/read-allMark every unread notification for the actor as read.
Post-Reactions
Reactions (like and the other reaction types) on posts.
Posts
Posts: create, read, edit, delete, schedule, pin, quote, and read their reactions and reposts.
- get
/v1/communities/{community_id}/postsList posts. - post
/v1/communities/{community_id}/postsCreate a post on behalf of an actor. - get
/v1/communities/{community_id}/posts/{post_id}Get a post by id. - patch
/v1/communities/{community_id}/posts/{post_id}Update post fields. - delete
/v1/communities/{community_id}/posts/{post_id}Soft-delete a post. - get
/v1/communities/{community_id}/posts/{post_id}/revisionsList a post's edit history. - get
/v1/communities/{community_id}/posts/{post_id}/quotesList the quote posts of a source post (X-style "show quotes" link). - post
/v1/communities/{community_id}/posts/impressionsBatch-increment impression (`view_count`) counters on a list of posts.
Reposts
Reposts of a post.
Search
Search posts, members and hashtags in a community.
Stories
Stories: short-lived posts that expire after 24 hours, and who viewed them.
- get
/v1/communities/{community_id}/actors/{actor_id}/story-trayStory tray for an actor — one entry per author with at least one unexpired or pinned story. - get
/v1/communities/{community_id}/actors/{owner_actor_id}/highlightsList the actor's pinned posts (highlights). - post
/v1/communities/{community_id}/posts/{post_id}/viewsRecord a view of a post (idempotent). - get
/v1/communities/{community_id}/posts/{post_id}/viewersList viewers of a post (author-only). - post
/v1/communities/{community_id}/close-friendsAdd a member to an actor's close-friends list. - delete
/v1/communities/{community_id}/close-friends/{owner_actor_id}/{member_actor_id}Remove a member from an actor's close-friends list. - get
/v1/communities/{community_id}/actors/{actor_id}/close-friendsList the close-friends members of an actor. - post
/v1/communities/{community_id}/posts/{post_id}/votesCast or change a vote on a poll. - get
/v1/communities/{community_id}/posts/{post_id}/poll-resultsAggregate poll results for a post. - get
/v1/communities/{community_id}/posts/{post_id}/votes/{actor_id}Read an actor's vote on a poll. - delete
/v1/communities/{community_id}/posts/{post_id}/votes/{actor_id}Retract an actor's vote on a poll. - get
/v1/communities/{community_id}/posts/{post_id}/votersList voters of a poll (author-only).
Suggestions
Suggested members to follow.
Viewer-State
The calling member's relationship to posts and members (liked, bookmarked, following) in one call.
Webhooks
Webhook endpoints that receive post, comment, follow, moderation, message and media events, their delivery log and replays, at the workspace or for one community. The legacy per-community webhook routes are deprecated.
- get
/v1/communities/{community_id}/webhooks/event-typesList the events an endpoint can subscribe to. - get
/v1/communities/{community_id}/webhooks/endpointsList webhook endpoints, oldest first. - post
/v1/communities/{community_id}/webhooks/endpointsAdd a webhook endpoint. - get
/v1/communities/{community_id}/webhooks/endpoints/{endpoint_id}Get one webhook endpoint (without its secret). - patch
/v1/communities/{community_id}/webhooks/endpoints/{endpoint_id}Change a webhook endpoint: URL, description, events, on/off. - delete
/v1/communities/{community_id}/webhooks/endpoints/{endpoint_id}Delete a webhook endpoint. - post
/v1/communities/{community_id}/webhooks/endpoints/{endpoint_id}/rotate-secretRotate the signing secret. - post
/v1/communities/{community_id}/webhooks/endpoints/{endpoint_id}/testSend a test event to this endpoint now and return the result. - get
/v1/communities/{community_id}/webhooks/eventsList webhook events, newest first (kept for 30 days). - get
/v1/communities/{community_id}/webhooks/events/{event_id}Get one webhook event with every delivery attempt. - post
/v1/communities/{community_id}/webhooks/events/{event_id}/replaySend a logged event again, to its endpoints or to one endpoint. - get
/v1/communities/{community_id}/webhooksList the community's webhooks — disabled rows included, so an auto-disabled subscriber stays discoverable. - post
/v1/communities/{community_id}/webhooksCreate a community webhook. - get
/v1/communities/{community_id}/webhooks/{webhook_id}Read a single webhook by id. - patch
/v1/communities/{community_id}/webhooks/{webhook_id}Update webhook url, subscribed event types, or disabled state. - delete
/v1/communities/{community_id}/webhooks/{webhook_id}Delete the webhook. - post
/v1/communities/{community_id}/webhooks/{webhook_id}/testSend a test delivery now: the example of the first event type the webhook subscribes to, signed exactly like a real… - post
/v1/communities/{community_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliverSend a past delivery's event again, now, with its original body (same event id, so subscriber-side event-id dedupe… - post
/v1/communities/{community_id}/webhooks/{webhook_id}/rotate-secretRotate the signing secret; the old one stops at once. - get
/v1/communities/{community_id}/webhooks/{webhook_id}/deliveriesList delivery attempts (newest first). - get
/v1/webhook-event-typesList the webhook event-type names.
Workspace lane
Admin API
Community CRUD, settings, the moderation queue and audit log, conversation moderation and analytics: the workspace-scoped endpoints the console is built on. Admin API reference →
Comment-Reactions
Reactions (like and the other reaction types) on comments.
/v1/communities/{community_id}/posts/{post_id}/comments/{comment_id}/reactionsList reactions on a comment, newest-first./v1/communities/{community_id}/posts/{post_id}/comments/{comment_id}/reactionsReact to a comment./v1/communities/{community_id}/posts/{post_id}/comments/{comment_id}/reactions/{src_actor_id}/{type}Unreact.