Social docs
Getting started

Add Social to your product.

From zero to a working community in five steps. You'll mint an API key, create a community, project an end-user as an actor, and post your first piece of content.

1

Enable Social on your workspace

Open the Social area in the console. If your workspace doesn't have Social enabled yet, you'll be prompted to turn it on (workspace owners only). This is what gates every customer-backend call — without the service enabled, every Social endpoint returns 403 SERVICE_NOT_ENABLED.

2

Create a community (standalone or Auth-backed)

From the console, click New community. Pick a display name and a slug — that's enough for a standalone community. Standalone communities are independent: you manage actor external_ids however you like (your own user table, opaque IDs, etc.).

If you already authenticate end-users via Auth, tick Connect to a Auth app in the modal and pick one of your apps. Social will verify the app belongs to the same workspace (cross-tenant gate, enforced server-side), and actors will then map 1:1 to Auth end-users via their account UUID. Either way, the community ends up in the same place — the integration is purely about how you source actor identity.

bash
# Standalone — no Auth app needed
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "content-type: application/json" \
  -d '{
    "slug": "my-community",
    "display_name": "My Community"
  }' \
  https://social.productcraft.co/v1/workspaces/<workspaceId>/communities

# Auth-backed — social verifies the app is in your workspace
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "content-type: application/json" \
  -d '{
    "app_id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "my-community",
    "display_name": "My Community"
  }' \
  https://social.productcraft.co/v1/workspaces/<workspaceId>/communities

3

Mint a Platform API Key

All Social customer-backend calls authenticate with a workspace Platform API Key. Open Workspace settings → API keys, create one, and lock its policy to the communities you intend to use. Keys are pcft_live_* prefixed.

4

Project an end-user as an actor

Before any post, follow, or comment can be created, the actor has to exist. Upsert is idempotent on (community, external_id); the second call with the same id returns created: false. The response carries the social actor.id (a UUID) — keep it on your side, every downstream call below keys off it.

bash
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "content-type: application/json" \
  -d '{
    "external_id": "user_42",
    "display_name": "Alice",
    "avatar_url": "https://cdn.example.com/avatars/alice.png"
  }' \
  https://social.productcraft.co/v1/communities/<communityId>/actors

# response: { "actor": { "id": "770a8600-...", ... }, "created": true }

5

Create your first post

With the actor in place, you can post on their behalf. Pass the social actor.id from step 4 as actor_id. Posts ride a single primitive — set kind to text, link, image, or story. Stories add an expires_at for the 24h-disappearing UX:

bash
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "content-type: application/json" \
  -d '{
    "actor_id": "770a8600-0000-0000-0000-000000000001",
    "kind": "story",
    "body": "shipping today",
    "attributes": { "media_url": "https://cdn.example.com/stories/1.jpg" },
    "expires_at": "2026-05-02T12:00:00Z",
    "visibility": "close_friends"
  }' \
  https://social.productcraft.co/v1/communities/<communityId>/posts

Next

Where to go from here

  • API reference — every endpoint with request and response schemas.
  • Feeds — GET /actors/:actorId/feed serves a ranked, algorithmic timeline by default. Pass order=chronological for time-ordered. Tune ranking weights per-community via community.settings.ranking.
  • Notifications — GET /actors/:actorId/notifications returns the per-actor inbox; producers fire automatically when someone follows, reacts, comments, or votes.
  • Stories — GET /actors/:actorId/story-tray gives the Instagram-style author tray. View tracking, polls, highlights, close-friends visibility, and private replies are all in the API reference.
  • Moderation — flags fire from POST /communities/:c/flags; the moderation queue and audit log live in the console.
Open the API referenceBack to the console