Search posts

Two modes (combinable)

• Filter mode — pass a structured query AST (and/or sort) and the endpoint returns posts matching the filter, ordered by sort (default createdAt:desc). Same shape as /v2/conversations/search, /v2/companies/search, /v2/contacts/search.
• Search mode — pass a top-level search string and the endpoint runs a hybrid full-text + vector search (BM25 + embeddings, semanticRatio 0.5) over post title and content, returning matches ranked by relevance. Optional: combine with query to constrain the search to a board / status / time window, and/or sort to override relevance ranking with chronological order.

{
  "search": "mobile dark mode",
  "query": {
    "operator": "AND",
    "value": [
      { "field": "boardId", "operator": "IN", "value": ["507f1f77bcf86cd799439011"] }
    ]
  },
  "limit": 20
}

search is server-managed: no operators, no field selection, no special syntax — same plain-text contract as /v2/conversations/search. The string must be 1–500 characters; up to ~1024 BM25-tokenizer characters are forwarded to Turbopuffer (longer queries are truncated at a word boundary).

Structured query AST

Each clause has the shape { field, operator, value }. You can pass a single clause or wrap up to 15 in a top-level AND group:

{
  "query": {
    "operator": "AND",
    "value": [
      { "field": "boardId", "operator": "IN", "value": ["507f1f77bcf86cd799439011"] },
      { "field": "upvotes", "operator": ">", "value": 10 }
    ]
  },
  "sort": "upvotes:desc",
  "limit": 20
}

To list every post a contact has upvoted (the inverse of feedback.posts.voters.list(postId)):

{
  "query": { "field": "voterId", "operator": "=", "value": "507f1f77bcf86cd799439011" },
  "sort": "upvotes:desc",
  "limit": 100
}

Top-level OR groups and nested groups are not supported in this version.

Supported fields and operators

Field names are camelCase, matching the rest of the v2 public API. Snake_case names that this endpoint originally shipped with (board_id, status_id, tag_id, author_id, voter_id, assignee_id, company_id, created_at, updated_at, comment_count, monthly_spend, opportunity_amount, in_review, is_pinned) are still accepted for back-compat but are deprecated — please migrate to camelCase in new code.

Use the top-level search field for full-text search across title and content (see "Search mode" above). The clause-level operators ~, !~, ^, $ are reserved for future use and currently return 400.

A filter-mode query (no search) consisting only of != or NIN clauses on unbounded fields is rejected with query_too_broad to prevent full-org scans. Combine the negation with at least one positive clause (=, IN, >, <) instead. Boolean fields (inReview, isPinned) are bounded so a standalone negation on them is allowed. Search mode (with search set) relaxes this — the FTS query itself acts as the positive constraint.

Sort

Allowed values:

• createdAt:desc (default), createdAt:asc
• updatedAt:desc, updatedAt:asc
• upvotes:desc, upvotes:asc
• eta:desc, eta:asc
• monthlySpend:desc, monthlySpend:asc (sum of upvoters' monthly spend)
• opportunityAmount:desc, opportunityAmount:asc (linked HubSpot/Salesforce value)
• commentCount:desc, commentCount:asc

Snake_case sort axes (created_at:desc, monthly_spend:asc, etc.) are accepted for back-compat — the cursor encodes the canonical camelCase identity, so a caller can switch naming conventions mid-pagination without restarting.

When search is set, results are ranked by relevance unless sort is also set, in which case the matching posts are returned in the requested order. The chosen sort axis (or relevance) is encoded in the cursor; switching sort (or toggling search on/off) mid-pagination returns 400 invalid_cursor. Restart pagination without a cursor when changing the sort or search shape.

Pagination

Cursor-based, limit between 1 and 100 (default 10). In filter mode, totalCount is approximate and capped at 5000; totalCountCapped is true when the real count may be higher. In search mode, totalCount reflects the matching survivor set after the AST filter and is capped at 200 (the Turbopuffer top-K).

Server-side guards

These exclusions are always applied and CANNOT be disabled via the AST:

• Spam posts (isSpam: true) are excluded.
• Merged posts (those rolled into another post) are excluded — the canonical row is what's returned.
• Support-board (ticket) categories are excluded — tickets have their own /v2/tickets surface.

Response

Returns a standard list envelope with post rows identical to GET /v2/posts/{id}.

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.