REST API Endpoints for Friend Lists

BuddyPress Auto Friends exposes a REST API for managing friend list members. The API is used internally by the Friend Lists JavaScript, but you can also call it from external applications or custom code.

Base URL: /wp-json/bautof/v1/

Since: 1.8.1

Authentication

All endpoints require the user to be logged in and to own the list they are accessing. Pass the WordPress REST nonce in the X-WP-Nonce header:

X-WP-Nonce: <nonce from wp_create_nonce('wp_rest')>

If the user is not logged in, the API returns a 401 response. If the list does not belong to the current user, the API returns a 404 response.

Endpoints

GET /lists/{slug}/members

Retrieve all members of a specific friend list.

URL parameters:

Parameter	Type	Description
slug	string	The list slug (alphanumeric, hyphens, underscores)

Response:

{
  "success": true,
  "count": 2,
  "members": [
    {
      "id": 42,
      "display_name": "Jane Smith",
      "avatar_url": "https://example.com/avatar/42",
      "profile_url": "https://example.com/members/jane-smith/"
    },
    {
      "id": 17,
      "display_name": "John Doe",
      "avatar_url": "https://example.com/avatar/17",
      "profile_url": "https://example.com/members/john-doe/"
    }
  ]
}

---

POST /lists/{slug}/members

Add a member to a friend list.

URL parameters:

Parameter	Type	Description
slug	string	The list slug

Request body:

{
  "user_id": 42
}

Field	Type	Required	Description
user_id	integer	Yes	WordPress user ID to add to the list

The user must be an existing BuddyPress friend of the authenticated user. Attempting to add a non-friend returns a 403 response.

Response:

{
  "success": true,
  "count": 3,
  "user_id": 42,
  "display_name": "Jane Smith",
  "avatar_url": "https://example.com/avatar/42",
  "profile_url": "https://example.com/members/jane-smith/"
}

Error responses:

Code	Status	Meaning
rest_invalid_user	400	The user_id does not correspond to a valid user
rest_not_friend	403	The user is not a BuddyPress friend of the authenticated user
rest_forbidden	404	The list does not exist or does not belong to the current user

---

DELETE /lists/{slug}/members/{user_id}

Remove a member from a friend list.

URL parameters:

Parameter	Type	Description
slug	string	The list slug
user_id	integer	WordPress user ID to remove

Response:

{
  "success": true,
  "count": 2,
  "user_id": 42
}

---

GET /lists/{slug}/suggestions

Get suggested users to add to a friend list, with optional search filtering.

URL parameters:

Parameter	Type	Description
slug	string	The list slug

Query parameters:

Parameter	Type	Default	Description
search	string	""	Filter suggestions by display name or username

The suggestion pool is always limited to the authenticated user’s existing BuddyPress friends. Only friends can be added to lists, so strangers never appear in suggestions.

Response:

{
  "success": true,
  "count": 5,
  "members": [
    {
      "id": 15,
      "display_name": "Alice Brown",
      "avatar_url": "https://example.com/avatar/15",
      "profile_url": "https://example.com/members/alice-brown/"
    }
  ]
}

Code examples

Fetch list members with JavaScript

wp.apiFetch( {
    path: '/bautof/v1/lists/my-list/members',
    method: 'GET',
} ).then( ( response ) => {
    console.log( response.members );
} );

Add a member with JavaScript

wp.apiFetch( {
    path: '/bautof/v1/lists/my-list/members',
    method: 'POST',
    data: { user_id: 42 },
} ).then( ( response ) => {
    console.log( 'Member added. Total count:', response.count );
} );

Remove a member with JavaScript

wp.apiFetch( {
    path: '/bautof/v1/lists/my-list/members/42',
    method: 'DELETE',
} ).then( ( response ) => {
    console.log( 'Member removed. Total count:', response.count );
} );

Fallback to Admin AJAX

The plugin JavaScript uses wp.apiFetch as the primary path and falls back to WordPress Admin AJAX (admin-ajax.php) if any REST request fails with a 403, 404, or network error. Sites with REST API access restricted by security plugins continue to work without any configuration change.