Social API reference

Social API · Suggestions

get/v1/communities/{community_id}/actors/{actor_id}/suggested-followsAuth

Suggested follows for an actor.

Friend-of-a-friend signal first (people the requester's followees also follow), with a cold-start fallback to top actors in the community by follower count when FoF underfills the limit. Excludes self, existing follows / mutes / blocks, and actors who have blocked the requester. Cached 1h per (actor, limit).

Path parameters

community_id*string

Social community UUID. Must belong to the PAK's workspace.

actor_id*string

Social actor UUID for whom to compute suggestions.

Query parameters

limitinteger

Items to return; capped at 50.

Response · 200 Ordered candidates.

data*array

Ordered candidates. FoF candidates are returned first (highest count first); cold-start fallbacks fill any remaining slots up to the requested limit.

pagination*object

Always `null` — suggestions are a single bounded, scored page (no cursor in v1). Present for envelope consistency (task 008 / G13).

Example

Request

GET https://social.productcraft.co/v1/communities/{community_id}/actors/{actor_id}/suggested-follows
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "actor": {
        "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "community_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
        "external_id": "user_abc123",
        "display_name": "Ada Lovelace",
        "avatar_url": "https://cdn.example.com/avatars/ada.png",
        "metadata": {
          "tier": "pro"
        },
        "status": "active",
        "is_private": false,
        "created_at": "2026-05-01T12:00:00.000Z",
        "updated_at": "2026-05-01T12:00:00.000Z"
      },
      "score": 4,
      "reason": "followed_by_friends"
    }
  ],
  "pagination": {}
}