Server API reference — BlueBubbles SDK

The server service exposes administrative operations for the BlueBubbles Server running on your macOS machine. You can read server metadata and logs, acknowledge alerts, trigger restarts at varying levels of severity, pull media and entity statistics, and manage server updates — all through the SDK. Access the service through client.server.

Metadata and logs

`getServerMetadata()`

Returns metadata about the BlueBubbles Server and the underlying operating system — including the server version, macOS version, and other environment details. Signature

client.server.getServerMetadata(): CancelablePromise<any>

Example

const info = await client.server.getServerMetadata();
console.log(info.data.server_version);
console.log(info.data.os_version);

`getServerLogs()`

Fetches recent log output from the BlueBubbles Server. Signature

client.server.getServerLogs(): CancelablePromise<any>

Example

const logs = await client.server.getServerLogs();
console.log(logs.data);

Alerts

`getServerAlerts()`

Returns all alerts generated by the BlueBubbles Server. Alerts include connectivity warnings, configuration issues, and other notable server events. Signature

client.server.getServerAlerts(): CancelablePromise<any>

Example

const alerts = await client.server.getServerAlerts();

for (const alert of alerts.data) {
  console.log(`[${alert.type}] ${alert.message}`);
}

`markAlertsAsRead()`

Marks one or more alerts as read on the server. You must pass the IDs of the alerts you want to mark — a catch-all endpoint is intentionally not provided to avoid race conditions. Signature

client.server.markAlertsAsRead({
  requestBody,
}: {
  requestBody?: Record<string, any>;
}): CancelablePromise<any>

Request body parameters

number[]

required

An array of alert IDs to mark as read. Retrieve alert IDs using getServerAlerts() first.

Example

// Fetch unread alerts and mark them all as read
const alerts = await client.server.getServerAlerts();
const ids = alerts.data.map((a: any) => a.id);

await client.server.markAlertsAsRead({
  requestBody: { ids },
});

Restart

`restartServer()`

Performs a full restart of the BlueBubbles Server application. The server closes itself completely and reopens. Signature

client.server.restartServer(): CancelablePromise<any>

Example

await client.server.restartServer();

restartServer() closes and reopens the BlueBubbles Server app entirely. Your SDK connection will drop during the restart. The Mac itself is not restarted. Build in reconnection logic if you call this programmatically.

`restartServices()`

Performs a soft restart of the individual services running inside BlueBubbles Server — including the HTTP service, the FCM service, and the Private API service. The server application itself stays running. Signature

client.server.restartServices(): CancelablePromise<any>

Example

// Restart services without a full app restart
await client.server.restartServices();

Prefer restartServices() over restartServer() when you only need to re-initialize a specific service (e.g., after rotating FCM credentials).

Statistics

`getMediaTotals()`

Returns aggregate totals for different media types (images, videos, etc.) across all chats. Signature

client.server.getMediaTotals(): CancelablePromise<any>

Example

const totals = await client.server.getMediaTotals();
console.log(totals.data);
// { images: 1402, videos: 87, ... }

`getMediaTotalsPerChat()`

Returns media totals broken down by individual chat. Useful for identifying which conversations contain the most media. Signature

client.server.getMediaTotalsPerChat(): CancelablePromise<any>

Example

const perChat = await client.server.getMediaTotalsPerChat();

for (const entry of perChat.data) {
  console.log(entry.chatGuid, entry.images, entry.videos);
}

`getImessageEntityTotals()`

Returns row counts for the core iMessage database entities: handles, messages, and chats. Signature

client.server.getImessageEntityTotals(): CancelablePromise<any>

Example

const totals = await client.server.getImessageEntityTotals();
console.log(totals.data);
// { handles: 412, messages: 98301, chats: 57 }

Updates

`checkForServerUpdate()`

Checks whether a new version of the BlueBubbles Server app is available. Returns update metadata if an update exists. Signature

client.server.checkForServerUpdate(): CancelablePromise<any>

Example

const update = await client.server.checkForServerUpdate();

if (update.data?.available) {
  console.log(`Update available: ${update.data.version}`);
}

`installServerUpdate()`

Installs an available update. By default the call returns immediately without waiting for the installation to complete. Pass wait=true as a URL parameter (via requestBody) to block until the update finishes. Signature

client.server.installServerUpdate({
  requestBody,
}: {
  requestBody?: any;
}): CancelablePromise<any>

Example

// Start install and return immediately
await client.server.installServerUpdate({ requestBody: null });

// Wait for the update to complete before resolving
await client.server.installServerUpdate({ requestBody: { wait: true } });

Always call checkForServerUpdate() before installServerUpdate() to confirm an update is actually available. Installing when no update exists will return an error.

Messaging

Contacts & Handles

Server

Server API reference — BlueBubbles SDK

Metadata and logs

`getServerMetadata()`

`getServerLogs()`

Alerts

`getServerAlerts()`

`markAlertsAsRead()`

Restart

`restartServer()`

`restartServices()`

Statistics

`getMediaTotals()`

`getMediaTotalsPerChat()`

`getImessageEntityTotals()`

Updates

`checkForServerUpdate()`

`installServerUpdate()`

​Metadata and logs

​getServerMetadata()

​getServerLogs()

​Alerts

​getServerAlerts()

​markAlertsAsRead()

​Restart

​restartServer()

​restartServices()

​Statistics

​getMediaTotals()

​getMediaTotalsPerChat()

​getImessageEntityTotals()

​Updates

​checkForServerUpdate()

​installServerUpdate()

Metadata and logs

`getServerMetadata()`

`getServerLogs()`

Alerts

`getServerAlerts()`

`markAlertsAsRead()`

Restart

`restartServer()`

`restartServices()`

Statistics

`getMediaTotals()`

`getMediaTotalsPerChat()`

`getImessageEntityTotals()`

Updates

`checkForServerUpdate()`

`installServerUpdate()`