Social API reference

Social API · Search

get/v1/communities/{community_id}/search/actorsAuth

Search actors by display name, external_id (username), and bio.

Postgres FTS over a generated tsvector column (display_name A + external_id B + bio C, `simple` locale). Returns up to `limit` (default 20, max 50) hits ordered by `ts_rank`. Pass `actor_id` to filter out actors the requester has muted or blocked, and actors who have blocked the requester. Trigram fuzzy matching is intentionally out of scope — that's a follow-up.

Path parameters

community_id*string

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

Query parameters

q*string

Free-text query (1..120 chars).

limitinteger

Max hits to return.

actor_idstring · uuid

Viewer social actor UUID — filters out blocked / muted actors.

cursorstring

Opaque pagination cursor from a prior response. Valid only for the same `q` (task 022).

Response · 200 Ranked actor hits, cursor-paginated by (rank, id).

data*array

Up to `limit` (default 20, max 50) ranked hits. Not paginated in v1; results are bounded by `limit`.

pagination*object

Always `null` — this lane returns a single bounded, ranked page (no cursor in v1). Present for envelope consistency.

Example

Request

GET https://social.productcraft.co/v1/communities/{community_id}/search/actors
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"
      },
      "rank": 0.6079
    }
  ],
  "pagination": {}
}