REST: Search, Hashtags, and Misc Singletons

Reference for the cross-cutting buddynext/v1 routes that do not belong to a single content domain: unified search (unified, member directory, and as-you-type suggest), the hashtag routes (trending, autocomplete, detail, feed, follow/unfollow, related, contributors, and the current user's followed tags), and a set of standalone singleton routes (shell nav, kudos, achievements, member types, link preview, CSV invite import, companion install, and admin slug-check). For developers calling or extending these surfaces.

Overview / Contract

All routes are under the buddynext/v1 namespace and follow the shared envelope, authentication, and pagination rules on the REST Contract page - read that first.

• Auth. Public routes use __return_true. Auth routes require a logged-in user. Hashtag routes additionally require the Hashtags feature to be enabled; write routes also require login. The admin singletons require capabilities (manage_options or install_plugins).
• Feature gate. Every hashtag route runs through a feature gate. When Hashtags are turned off for the community, read routes return 403 with code hashtags_disabled; write routes return 401 when the caller is logged out, then the same 403 when the feature is off.
• Pagination. Search accepts page and per_page (default 20). Hashtag feeds paginate over post results.

Search

Served by SearchController. /search is the unified search across content types; /search/members is a directory-style member search with cursor pagination; /search/suggest powers the as-you-type typeahead overlay.

The type parameter on /search narrows results to one object type (for example members, spaces, or posts); omit it to return grouped results keyed by type. The Pro-only member filters are registered on /search so app and REST clients can pass them and so the schema documents them - Free forwards them through the buddynext_search_query_args filter seam, and they are simply ignored when Pro is not active.

Hashtags

Served by HashtagController. The {slug} path segment matches [^/]+ (any non-slash characters). All routes are gated by the Hashtags feature toggle.

The read routes use the require_hashtags_enabled gate (feature toggle only). The follow/unfollow routes and /me/hashtags use require_hashtags_enabled_auth, which additionally requires a logged-in user.

Shell nav, gamification, and member types

Standalone routes that back the app shell and the gamification/member-type surfaces.

Misc singletons

Standalone routes that do not belong to a domain controller.

Capability detail:

• /link-preview requires authentication (require_auth); it is used by the post composer before submit.
• /invites/import-csv requires manage_options (and a logged-in user).
• /companions/install requires install_plugins.
• /admin/slug-check requires manage_options.

Examples

Unified search

curl "https://example.com/wp-json/buddynext/v1/search?q=design&type=members&per_page=10&page=1"

The /search handler returns the matched object type, the result rows, and the total count:

{
  "type": "members",
  "total": 2,
  "results": [
    {
      "id": 17,
      "name": "Ada Lovelace",
      "initials": "AL",
      "bio": "Building the analytical engine.",
      "profile_url": "https://example.com/members/ada/",
      "is_self": false,
      "is_following": true
    },
    {
      "id": 31,
      "name": "Grace Hopper",
      "initials": "GH",
      "bio": "Compilers and nanoseconds.",
      "profile_url": "https://example.com/members/grace/",
      "is_self": false,
      "is_following": false
    }
  ]
}

Space results carry id, name, initials, description, member_count, space_url, and is_member. The is_following / is_member flags are populated only when a logged-in viewer makes the request.

Follow a hashtag

curl -X POST https://example.com/wp-json/buddynext/v1/hashtags/photography/follow \
  -H "X-WP-Nonce: <nonce>" \
  --cookie "<auth cookies>"

{ "following": true, "follower_count": 42 }

Notes and gotchas

• Hashtag routes 403 when the feature is off, not 404. Check the Hashtags toggle before assuming a route is missing; the error code is hashtags_disabled.
• Pro search filters are documented but inert in Free. tier_slug, member_label, joined_after, and active_within_days on /search are accepted and ignored unless buddynext-pro is active and merges them through the buddynext_search_query_args seam.
• /link-preview lives on the Feed controller, not a dedicated search/preview controller; it requires authentication because it is part of the post composer.
• The admin singletons are owner tooling. /invites/import-csv, /companions/install, and /admin/slug-check are administrator-only and are not part of the member-facing surface.