REST: Members and Profiles

This page documents the largest REST surface in BuddyNext: the self-service /me/* routes, the per-user /users/{id}/* routes, profile-field and profile-group administration, member types, profile-slug checks, and the member directory. The /me/* and /users/{id}/* groups together account for roughly 63 routes under buddynext/v1. This page covers everything except the social-graph relationship routes (follow, connect, block, mute) that happen to live on the same /me/* and /users/{id}/* paths - those are documented on the REST: Social Graph page. Read the REST Contract page first; everything here assumes its namespace, nonce auth, envelope, and pagination rules.

Overview / Contract

All routes register under buddynext/v1. Authentication, the success/error envelope, and cursor pagination follow the REST Contract page without exception:

Permission callbacks fall into a few classes used throughout this surface:

Note: Public-read routes (__return_true) do not return everything to everyone. The Profile, Directory, and Member-Type services apply per-viewer privacy gates (profile visibility, directory opt-out, blocked/restricted relationships) before a row is serialized.

/me/* - the self-service surface

Every route below operates on get_current_user_id() and requires a logged-in caller. The user ID is never in the path.

Profile, avatar, and cover

Drafts, bookmarks, and shares

Blocked, muted, and restricted lists

These are read-only list views of the caller's own social-graph state. The write actions that populate them (POST /users/{id}/block, /mute, /restrict) are on the Social Graph page.

Onboarding and presence

/me/interests writes through the profile store, not user meta. The picks land in the system interests profile field (a category_multiselect, one bn_profile_values row per pick) - POST /me/interests is a thin alias over the canonical profile-save path, so a pick made here is the same value PUT /me/profile would write.

Social login providers

Notification and space-notification preferences

Note: /me/notification-prefs, /me/notification-channels, and /me/space-notification-prefs are documented here as the read endpoints. Preference writes for these surfaces are submitted through the profile/account save flow (PUT /me/profile for the email/digest toggles) and the notification-channel handlers; see the Notifications schema page for the underlying bn_notification_prefs storage.

Account: 2FA, password, email, and sessions

Two-factor lives under /account/2fa/*; password, email, and session controls live under /auth/*. Both groups require a logged-in caller.

Note: /auth/2fa and /auth/2fa/email-code (under the auth namespace, permission __return_true, gated by users_can_register) are part of the login challenge flow, not account management. They are documented on the REST: Auth page.

Appeals and self-service privacy

/users/{id}/* - routes that target a specific user

{id} matches [\d]+. Reads here are public (privacy-gated per row); writes are administrative.

Profile view and admin media

Companion-gated member routes

Registered by JetonomyBridge and present only when the Jetonomy companion is active. Note the /members/ prefix (not /users/) - this route mirrors the SSR profile Discussions tab so the native app renders the same panel.

The space-scoped Jetonomy bridge routes (POST /spaces/{id}/forum, GET /spaces/{id}/discussion-search) are documented on the REST: Spaces page.

Moderation actions targeting a user

These are administrative moderation routes. The member-facing counterpart is POST /me/appeals above.

Every route below except warn uses the require_admin permission callback - site admin (manage_options), not the community moderator role. The one exception is POST /users/{id}/warn, which is authenticated at the route and authorized inside the handler, so a space owner or moderator may warn a member within a space they moderate. See REST: Moderation and Trust for the full authorization model.

Note: The relationship and trust actions that also live on /users/{id}/* - block, mute, restrict, connect (+ accept/decline), follow, followers, following, connection/status, mutual-connections, account-type - are member-driven social-graph routes, not moderation. They are documented in full on the REST: Social Graph page.

Profile fields and groups (CRUD + reorder)

Profile groups contain fields. Lists are public; all writes require require_admin. Reorder uses a direction enum (up/down) rather than absolute positions, so concurrent reorders stay consistent.

Groups

Fields

Member types (CRUD + assignment)

Type definitions are public to read and admin to write. Assignment to a user is admin for any user, or self-assignable types via can_set_user_type.

Profile-slug check and member directory

GET /members accepts these query parameters:

Note: relation=following and relation=connections are applied inside the directory query (a JOIN on bn_follows / connections), so the total count and cursor reflect the filtered set. Do not post-filter directory rows on the client.

Examples

Update my profile

PUT /me/profile accepts a flat JSON object of field_key => value. Core fields (display_name), profile fields (headline, bio, location, website, social_*), privacy gates, and notification toggles can all be sent in one call. Unknown keys are ignored. URL fields are accepted without a protocol (https is prefixed). A clean save returns 200; field-level validation failures return 422 with an errors map the client can render inline.

curl -X PUT 'https://example.com/wp-json/buddynext/v1/me/profile' \
  -H 'X-WP-Nonce: <nonce>' \
  -H 'Content-Type: application/json' \
  --data '{
    "display_name": "Ada Lovelace",
    "headline": "Mathematician and writer",
    "bio": "Working on the Analytical Engine.",
    "location": "London",
    "website": "ada-lovelace.example",
    "social_github": "https://github.com/ada",
    "bn_privacy_profile_visibility": "followers",
    "bn_pref_email_digest": true
  }'

Success response (200):

{
  "saved": true,
  "errors": [],
  "profile": {
    "user_id": 12,
    "completion": 80,
    "groups": [],
    "fields": {
      "headline": "Mathematician and writer",
      "bio": "Working on the Analytical Engine.",
      "location": "London",
      "website": "https://ada-lovelace.example"
    }
  }
}

Validation-failure response (422):

{
  "saved": false,
  "errors": {
    "website": "Enter a valid URL (https://example.com).",
    "display_name": "Display name is required."
  }
}

Create a profile field

POST /profile-fields requires require_admin. group_id, field_key, and label are required; type, is_required, and sort_order default as shown. The create returns 201 with the new field ID.

curl -X POST 'https://example.com/wp-json/buddynext/v1/profile-fields' \
  -H 'X-WP-Nonce: <nonce>' \
  -H 'Content-Type: application/json' \
  --data '{
    "group_id": 1,
    "field_key": "favorite_language",
    "label": "Favorite programming language",
    "type": "text",
    "is_required": false,
    "sort_order": 5
  }'

Success response (201):

{ "id": 42 }

Notes / gotchas

• Social-graph routes live on these same paths. /me/blocked, /me/muted, /me/restricted, /me/connections, /me/connection-requests, /me/follow-requests*, and the /users/{id}/ actions for block, mute, restrict, connect, follow, followers, following, connection/status, mutual-connections, and account-type are detailed on the REST: Social Graph page. They are grouped there because they share the social-graph services and hooks, even though their paths sit under /me/* and /users/{id}/*.
• Public reads are privacy-gated, not open. A __return_true permission callback means the route is reachable without login; it does not mean every row is returned. Profile visibility, directory opt-out, and blocked/restricted relationships are enforced row-by-row in the service layer.
• Reorder is relative. Field and group reorder take a direction enum (up/down), not an absolute index, so two admins reordering at once cannot corrupt the order.
• Profile writes are split by storage. PUT /me/profile routes core fields to wp_update_user, privacy and notification keys to user meta (through PrivacyService for the gate keys, so buddynext_privacy_preference_changed fires), and everything else to profile-value rows - all in one request.
• Free vs Pro. Every route on this page is Free (buddynext/v1). Pro adds advanced field renderers and membership-driven profile surfaces under buddynext-pro/v1; it reads Free profile data through the Profile service rather than re-registering these routes.