> ## Documentation Index
> Fetch the complete documentation index at: https://bluebubbles.anmho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Server API reference — BlueBubbles SDK

> Inspect server metadata, read logs, manage alerts, restart services, view media statistics, and install updates for your BlueBubbles Server.

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**

```typescript theme={null}
client.server.getServerMetadata(): CancelablePromise<any>
```

**Example**

```typescript theme={null}
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**

```typescript theme={null}
client.server.getServerLogs(): CancelablePromise<any>
```

**Example**

```typescript theme={null}
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**

```typescript theme={null}
client.server.getServerAlerts(): CancelablePromise<any>
```

**Example**

```typescript theme={null}
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**

```typescript theme={null}
client.server.markAlertsAsRead({
  requestBody,
}: {
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
```

**Request body parameters**

<ParamField body="ids" type="number[]" required>
  An array of alert IDs to mark as read. Retrieve alert IDs using
  `getServerAlerts()` first.
</ParamField>

**Example**

```typescript theme={null}
// 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**

```typescript theme={null}
client.server.restartServer(): CancelablePromise<any>
```

**Example**

```typescript theme={null}
await client.server.restartServer();
```

<Warning>
  `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.
</Warning>

***

### `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**

```typescript theme={null}
client.server.restartServices(): CancelablePromise<any>
```

**Example**

```typescript theme={null}
// Restart services without a full app restart
await client.server.restartServices();
```

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

***

## Statistics

### `getMediaTotals()`

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

**Signature**

```typescript theme={null}
client.server.getMediaTotals(): CancelablePromise<any>
```

**Example**

```typescript theme={null}
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**

```typescript theme={null}
client.server.getMediaTotalsPerChat(): CancelablePromise<any>
```

**Example**

```typescript theme={null}
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**

```typescript theme={null}
client.server.getImessageEntityTotals(): CancelablePromise<any>
```

**Example**

```typescript theme={null}
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**

```typescript theme={null}
client.server.checkForServerUpdate(): CancelablePromise<any>
```

**Example**

```typescript theme={null}
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**

```typescript theme={null}
client.server.installServerUpdate({
  requestBody,
}: {
  requestBody?: any;
}): CancelablePromise<any>
```

**Example**

```typescript theme={null}
// 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 } });
```

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