Social API reference

Social API · Search

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

Search post content (title + body) by full-text.

Postgres FTS over a generated tsvector column on the post table (title A + body B, simple locale). `order='relevance'` (default) ranks by ts_rank; `order='recent'` keeps the FTS filter but orders by created_at desc. Filters out drafts / removed / hidden / expired posts. Pass `actor_id` to drop posts authored by anyone the requester has muted / blocked, or who has blocked the requester. Without `actor_id`, only posts with `visibility='public'` surface.

Path parameters

community_id*string

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

Query parameters

q*string

Search text.

limitinteger

Maximum number of items to return (1-50, default 20).

orderenum (2)

`relevance` (best match first) or `recent` (newest first).

actor_idstring · uuid

Viewer social actor UUID.

cursorstring

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

Response · 200 Ranked post hits, cursor-paginated by (rank, id) for relevance or (created_at, id) for recent.

data*array

Up to `limit` (default 20, max 50) hits. Not paginated in v1.

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/posts
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "post": {
        "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
        "community_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
        "actor_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "kind": "text",
        "title": "Shipping Phase 8",
        "body": "Stories are live!",
        "url": "https://cdn.example.com/img.png",
        "attributes": {},
        "visibility": "public",
        "status": "published",
        "reaction_counts": {
          "like": 12,
          "fire": 3
        },
        "comment_count": 4,
        "source_post_id": null,
        "repost_count": 0,
        "quote_count": 0,
        "edited_at": null,
        "edit_count": 0,
        "view_count": 0,
        "expires_at": null,
        "pinned": false,
        "settings": {},
        "scheduled_for": null,
        "assets": [
          {
            "asset_id": null,
            "alt_text": null
          }
        ],
        "created_at": "2026-05-01T12:00:00.000Z",
        "updated_at": "2026-05-01T12:00:00.000Z"
      },
      "rank": 0.6079
    }
  ],
  "pagination": {}
}