Search

API Reference

Client

Search

get/v1/search

Returns matching chats, participant name matches in groups, and the first page of messages in one call. Paginate messages via search-messages. Paginate chats via search-chats. Uses the same sorting as the chat search in the app.

Query ParametersExpand Collapse

query: string

User-typed search text. Literal word matching (NOT semantic).

minLength1

ReturnsExpand Collapse

results: object { chats, in_groups, messages }

chats: array of Chat { id, accountID, network, 10 more }

Top chat results.

id: string

Unique identifier of the chat (room/thread ID, same as id) across Beeper.

accountID: string

Beeper account ID this chat belongs to.

network: string

Display-only human-readable network name (e.g., 'WhatsApp', 'Messenger').

participants: object { hasMore, items, total }

Chat participants information.

hasMore: boolean

True if there are more participants than included in items.

items: array of User { id, cannotMessage, email, 5 more }

Participants returned for this chat (limited by the request; may be a subset).

id: string

Stable Beeper user ID. Use as the primary key when referencing a person.

cannotMessage: optional boolean

True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.

email: optional string

Email address if known. Not guaranteed verified.

fullName: optional string

Display name as shown in clients (e.g., 'Alice Example'). May include emojis.

imgURL: optional string

Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed.

isSelf: optional boolean

True if this user represents the authenticated account's own identity.

phoneNumber: optional string

User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown.

username: optional string

Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique.

total: number

Total number of participants in the chat.

title: string

Display title of the chat as computed by the client/server.

type: "single" or "group"

Chat type: 'single' for direct messages, 'group' for group chats.

Accepts one of the following:

"single"

"group"

unreadCount: number

Number of unread messages.

isArchived: optional boolean

True if chat is archived.

isMuted: optional boolean

True if chat notifications are muted.

isPinned: optional boolean

True if chat is pinned.

lastActivity: optional string

Timestamp of last activity. Chats with more recent activity are often more important.

formatdate-time

lastReadMessageSortKey: optional number or string

Last read message sortKey (hsOrder). Used to compute 'isUnread'.

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

localChatID: optional string

Local chat ID specific to this Beeper Desktop installation.

in_groups: array of Chat { id, accountID, network, 10 more }

Top group results by participant matches.

id: string

Unique identifier of the chat (room/thread ID, same as id) across Beeper.

accountID: string

Beeper account ID this chat belongs to.

network: string

Display-only human-readable network name (e.g., 'WhatsApp', 'Messenger').

participants: object { hasMore, items, total }

Chat participants information.

hasMore: boolean

True if there are more participants than included in items.

items: array of User { id, cannotMessage, email, 5 more }

Participants returned for this chat (limited by the request; may be a subset).

id: string

Stable Beeper user ID. Use as the primary key when referencing a person.

cannotMessage: optional boolean

True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.

email: optional string

Email address if known. Not guaranteed verified.

fullName: optional string

Display name as shown in clients (e.g., 'Alice Example'). May include emojis.

imgURL: optional string

Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed.

isSelf: optional boolean

True if this user represents the authenticated account's own identity.

phoneNumber: optional string

User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown.

username: optional string

Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique.

total: number

Total number of participants in the chat.

title: string

Display title of the chat as computed by the client/server.

type: "single" or "group"

Chat type: 'single' for direct messages, 'group' for group chats.

Accepts one of the following:

"single"

"group"

unreadCount: number

Number of unread messages.

isArchived: optional boolean

True if chat is archived.

isMuted: optional boolean

True if chat notifications are muted.

isPinned: optional boolean

True if chat is pinned.

lastActivity: optional string

Timestamp of last activity. Chats with more recent activity are often more important.

formatdate-time

lastReadMessageSortKey: optional number or string

Last read message sortKey (hsOrder). Used to compute 'isUnread'.

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

localChatID: optional string

Local chat ID specific to this Beeper Desktop installation.

messages: object { chats, hasMore, items, 2 more }

chats: map[Chat { id, accountID, network, 10 more } ]

Map of chatID -> chat details for chats referenced in items.

id: string

Unique identifier of the chat (room/thread ID, same as id) across Beeper.

accountID: string

Beeper account ID this chat belongs to.

network: string

Display-only human-readable network name (e.g., 'WhatsApp', 'Messenger').

participants: object { hasMore, items, total }

Chat participants information.

hasMore: boolean

True if there are more participants than included in items.

items: array of User { id, cannotMessage, email, 5 more }

Participants returned for this chat (limited by the request; may be a subset).

id: string

Stable Beeper user ID. Use as the primary key when referencing a person.

cannotMessage: optional boolean

True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.

email: optional string

Email address if known. Not guaranteed verified.

fullName: optional string

Display name as shown in clients (e.g., 'Alice Example'). May include emojis.

imgURL: optional string

Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed.

isSelf: optional boolean

True if this user represents the authenticated account's own identity.

phoneNumber: optional string

User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown.

username: optional string

Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique.

total: number

Total number of participants in the chat.

title: string

Display title of the chat as computed by the client/server.

type: "single" or "group"

Chat type: 'single' for direct messages, 'group' for group chats.

Accepts one of the following:

"single"

"group"

unreadCount: number

Number of unread messages.

isArchived: optional boolean

True if chat is archived.

isMuted: optional boolean

True if chat notifications are muted.

isPinned: optional boolean

True if chat is pinned.

lastActivity: optional string

Timestamp of last activity. Chats with more recent activity are often more important.

formatdate-time

lastReadMessageSortKey: optional number or string

Last read message sortKey (hsOrder). Used to compute 'isUnread'.

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

localChatID: optional string

Local chat ID specific to this Beeper Desktop installation.

hasMore: boolean

True if additional results can be fetched using the provided cursors.

items: array of Message { id, accountID, chatID, 9 more }

Messages matching the query and filters.

id: string

Message ID.

accountID: string

Beeper account ID the message belongs to.

chatID: string

Unique identifier of the chat.

senderID: string

Sender user ID.

sortKey: string

A unique key used to sort messages

timestamp: string

Message timestamp.

formatdate-time

attachments: optional array of Attachment { type, duration, fileName, 8 more }

Attachments included with this message, if any.

type: "unknown" or "img" or "video" or "audio"

Attachment type.

Accepts one of the following:

"unknown"

"img"

"video"

"audio"

duration: optional number

Duration in seconds (audio/video).

fileName: optional string

Original filename if available.

fileSize: optional number

File size in bytes if known.

isGif: optional boolean

True if the attachment is a GIF.

isSticker: optional boolean

True if the attachment is a sticker.

isVoiceNote: optional boolean

True if the attachment is a voice note.

mimeType: optional string

MIME type if known (e.g., 'image/png').

posterImg: optional string

Preview image URL for video attachments (poster frame). May be temporary or local-only to this device; download promptly if durable access is needed.

size: optional object { height, width }

Pixel dimensions of the attachment: width/height in px.

height: optional number

width: optional number

srcURL: optional string

Public URL or local file path to fetch the asset. May be temporary or local-only to this device; download promptly if durable access is needed.

isSender: optional boolean

True if the authenticated user sent the message.

isUnread: optional boolean

True if the message is unread for the authenticated user. May be omitted.

reactions: optional array of Reaction { id, participantID, reactionKey, 2 more }

Reactions to the message, if any.

id: string

Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise.

participantID: string

User ID of the participant who reacted.

reactionKey: string

The reaction key: an emoji (😄), a network-specific key, or a shortcode like "smiling-face".

emoji: optional boolean

True if the reactionKey is an emoji.

imgURL: optional string

URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed.

senderName: optional string

Resolved sender display name (impersonator/full name/username/participant name).

text: optional string

Plain-text body if present. May include a JSON fallback with text entities for rich messages.

newestCursor: string

Cursor for fetching newer results (use with direction='after'). Opaque string; do not inspect.

oldestCursor: string

Cursor for fetching older results (use with direction='before'). Opaque string; do not inspect.

Search

http

• http
• typescript
• python
• go

curl http://localhost:23373/v1/search \
    -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN" \
    -d '{}'

200 example

{
  "results": {
    "chats": [
      {
        "id": "!instagram_mattwondra:local-instagram.localhost",
        "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU",
        "network": "Instagram",
        "participants": {
          "hasMore": false,
          "items": [
            {
              "id": "@mattwondra:local-instagram.localhost",
              "cannotMessage": false,
              "email": "email",
              "fullName": "Matt Wondra",
              "imgURL": "imgURL",
              "isSelf": false,
              "phoneNumber": "phoneNumber",
              "username": "mattwondra"
            },
            {
              "id": "@batuhan:local-instagram.localhost",
              "cannotMessage": false,
              "email": "email",
              "fullName": "Batuhan İçöz",
              "imgURL": "imgURL",
              "isSelf": true,
              "phoneNumber": "phoneNumber",
              "username": "batuhan"
            }
          ],
          "total": 2
        },
        "title": "Matt Wondra",
        "type": "single",
        "unreadCount": 0,
        "isArchived": false,
        "isMuted": false,
        "isPinned": false,
        "lastActivity": "2025-08-31T19:41:41.000Z",
        "lastReadMessageSortKey": 449706228480,
        "localChatID": "1229391"
      }
    ],
    "in_groups": [
      {
        "id": "!instagram_mattwondra:local-instagram.localhost",
        "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU",
        "network": "Instagram",
        "participants": {
          "hasMore": false,
          "items": [
            {
              "id": "@mattwondra:local-instagram.localhost",
              "cannotMessage": false,
              "email": "email",
              "fullName": "Matt Wondra",
              "imgURL": "imgURL",
              "isSelf": false,
              "phoneNumber": "phoneNumber",
              "username": "mattwondra"
            },
            {
              "id": "@batuhan:local-instagram.localhost",
              "cannotMessage": false,
              "email": "email",
              "fullName": "Batuhan İçöz",
              "imgURL": "imgURL",
              "isSelf": true,
              "phoneNumber": "phoneNumber",
              "username": "batuhan"
            }
          ],
          "total": 2
        },
        "title": "Matt Wondra",
        "type": "single",
        "unreadCount": 0,
        "isArchived": false,
        "isMuted": false,
        "isPinned": false,
        "lastActivity": "2025-08-31T19:41:41.000Z",
        "lastReadMessageSortKey": 449706228480,
        "localChatID": "1229391"
      }
    ],
    "messages": {
      "chats": {
        "!signal_adamvy:local-signal.localhost": {
          "id": "!signal_adamvy:local-signal.localhost",
          "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
          "network": "Signal",
          "participants": {
            "hasMore": false,
            "items": [
              {
                "id": "@adamvy:local-signal.localhost",
                "cannotMessage": false,
                "email": "email",
                "fullName": "Adam Van Ymeren",
                "imgURL": "imgURL",
                "isSelf": false,
                "phoneNumber": "phoneNumber",
                "username": "username"
              },
              {
                "id": "@batuhan:local-signal.localhost",
                "cannotMessage": false,
                "email": "email",
                "fullName": "Batuhan İçöz",
                "imgURL": "imgURL",
                "isSelf": true,
                "phoneNumber": "phoneNumber",
                "username": "username"
              }
            ],
            "total": 2
          },
          "title": "Adam Van Ymeren",
          "type": "single",
          "unreadCount": 0,
          "isArchived": false,
          "isMuted": false,
          "isPinned": true,
          "lastActivity": "2025-08-31T17:38:20.393Z",
          "lastReadMessageSortKey": 449706228480,
          "localChatID": "1229720"
        },
        "!telegram_nick:local-telegram.localhost": {
          "id": "!telegram_nick:local-telegram.localhost",
          "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
          "network": "Telegram",
          "participants": {
            "hasMore": false,
            "items": [
              {
                "id": "@nick:local-telegram.localhost",
                "cannotMessage": false,
                "email": "email",
                "fullName": "Nick Mills-Barrett",
                "imgURL": "imgURL",
                "isSelf": false,
                "phoneNumber": "phoneNumber",
                "username": "nick"
              },
              {
                "id": "@batuhan:local-telegram.localhost",
                "cannotMessage": false,
                "email": "email",
                "fullName": "Batuhan İçöz",
                "imgURL": "imgURL",
                "isSelf": true,
                "phoneNumber": "phoneNumber",
                "username": "batuhan"
              }
            ],
            "total": 2
          },
          "title": "Nick Mills-Barrett",
          "type": "single",
          "unreadCount": 2,
          "isArchived": false,
          "isMuted": true,
          "isPinned": false,
          "lastActivity": "2025-08-31T16:45:10.123Z",
          "lastReadMessageSortKey": 449706228480,
          "localChatID": "1229721"
        }
      },
      "hasMore": true,
      "items": [
        {
          "id": "1343993",
          "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
          "chatID": "!signal_adamvy:local-signal.localhost",
          "senderID": "@adamvy:local-signal.localhost",
          "sortKey": "sortKey",
          "timestamp": "2025-08-28T11:04:29.621Z",
          "attachments": [
            {
              "type": "unknown",
              "duration": 0,
              "fileName": "fileName",
              "fileSize": 0,
              "isGif": true,
              "isSticker": true,
              "isVoiceNote": true,
              "mimeType": "mimeType",
              "posterImg": "posterImg",
              "size": {
                "height": 0,
                "width": 0
              },
              "srcURL": "srcURL"
            }
          ],
          "isSender": false,
          "isUnread": false,
          "reactions": [
            {
              "id": "id",
              "participantID": "participantID",
              "reactionKey": "reactionKey",
              "emoji": true,
              "imgURL": "imgURL"
            }
          ],
          "senderName": "Adam Van Ymeren",
          "text": "Hey, can we reschedule our meeting to 3pm?"
        },
        {
          "id": "1343994",
          "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
          "chatID": "!telegram_nick:local-telegram.localhost",
          "senderID": "@nick:local-telegram.localhost",
          "sortKey": "sortKey",
          "timestamp": "2025-08-28T14:22:15.432Z",
          "attachments": [
            {
              "type": "unknown",
              "duration": 0,
              "fileName": "fileName",
              "fileSize": 0,
              "isGif": true,
              "isSticker": true,
              "isVoiceNote": true,
              "mimeType": "mimeType",
              "posterImg": "posterImg",
              "size": {
                "height": 0,
                "width": 0
              },
              "srcURL": "srcURL"
            }
          ],
          "isSender": false,
          "isUnread": true,
          "reactions": [
            {
              "id": "id",
              "participantID": "participantID",
              "reactionKey": "reactionKey",
              "emoji": true,
              "imgURL": "imgURL"
            }
          ],
          "senderName": "Nick Mills-Barrett",
          "text": "The deployment is complete, everything looks good"
        }
      ],
      "newestCursor": null,
      "oldestCursor": "1756379069621"
    }
  }
}

Returns Examples

200 example

{
  "results": {
    "chats": [
      {
        "id": "!instagram_mattwondra:local-instagram.localhost",
        "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU",
        "network": "Instagram",
        "participants": {
          "hasMore": false,
          "items": [
            {
              "id": "@mattwondra:local-instagram.localhost",
              "cannotMessage": false,
              "email": "email",
              "fullName": "Matt Wondra",
              "imgURL": "imgURL",
              "isSelf": false,
              "phoneNumber": "phoneNumber",
              "username": "mattwondra"
            },
            {
              "id": "@batuhan:local-instagram.localhost",
              "cannotMessage": false,
              "email": "email",
              "fullName": "Batuhan İçöz",
              "imgURL": "imgURL",
              "isSelf": true,
              "phoneNumber": "phoneNumber",
              "username": "batuhan"
            }
          ],
          "total": 2
        },
        "title": "Matt Wondra",
        "type": "single",
        "unreadCount": 0,
        "isArchived": false,
        "isMuted": false,
        "isPinned": false,
        "lastActivity": "2025-08-31T19:41:41.000Z",
        "lastReadMessageSortKey": 449706228480,
        "localChatID": "1229391"
      }
    ],
    "in_groups": [
      {
        "id": "!instagram_mattwondra:local-instagram.localhost",
        "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU",
        "network": "Instagram",
        "participants": {
          "hasMore": false,
          "items": [
            {
              "id": "@mattwondra:local-instagram.localhost",
              "cannotMessage": false,
              "email": "email",
              "fullName": "Matt Wondra",
              "imgURL": "imgURL",
              "isSelf": false,
              "phoneNumber": "phoneNumber",
              "username": "mattwondra"
            },
            {
              "id": "@batuhan:local-instagram.localhost",
              "cannotMessage": false,
              "email": "email",
              "fullName": "Batuhan İçöz",
              "imgURL": "imgURL",
              "isSelf": true,
              "phoneNumber": "phoneNumber",
              "username": "batuhan"
            }
          ],
          "total": 2
        },
        "title": "Matt Wondra",
        "type": "single",
        "unreadCount": 0,
        "isArchived": false,
        "isMuted": false,
        "isPinned": false,
        "lastActivity": "2025-08-31T19:41:41.000Z",
        "lastReadMessageSortKey": 449706228480,
        "localChatID": "1229391"
      }
    ],
    "messages": {
      "chats": {
        "!signal_adamvy:local-signal.localhost": {
          "id": "!signal_adamvy:local-signal.localhost",
          "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
          "network": "Signal",
          "participants": {
            "hasMore": false,
            "items": [
              {
                "id": "@adamvy:local-signal.localhost",
                "cannotMessage": false,
                "email": "email",
                "fullName": "Adam Van Ymeren",
                "imgURL": "imgURL",
                "isSelf": false,
                "phoneNumber": "phoneNumber",
                "username": "username"
              },
              {
                "id": "@batuhan:local-signal.localhost",
                "cannotMessage": false,
                "email": "email",
                "fullName": "Batuhan İçöz",
                "imgURL": "imgURL",
                "isSelf": true,
                "phoneNumber": "phoneNumber",
                "username": "username"
              }
            ],
            "total": 2
          },
          "title": "Adam Van Ymeren",
          "type": "single",
          "unreadCount": 0,
          "isArchived": false,
          "isMuted": false,
          "isPinned": true,
          "lastActivity": "2025-08-31T17:38:20.393Z",
          "lastReadMessageSortKey": 449706228480,
          "localChatID": "1229720"
        },
        "!telegram_nick:local-telegram.localhost": {
          "id": "!telegram_nick:local-telegram.localhost",
          "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
          "network": "Telegram",
          "participants": {
            "hasMore": false,
            "items": [
              {
                "id": "@nick:local-telegram.localhost",
                "cannotMessage": false,
                "email": "email",
                "fullName": "Nick Mills-Barrett",
                "imgURL": "imgURL",
                "isSelf": false,
                "phoneNumber": "phoneNumber",
                "username": "nick"
              },
              {
                "id": "@batuhan:local-telegram.localhost",
                "cannotMessage": false,
                "email": "email",
                "fullName": "Batuhan İçöz",
                "imgURL": "imgURL",
                "isSelf": true,
                "phoneNumber": "phoneNumber",
                "username": "batuhan"
              }
            ],
            "total": 2
          },
          "title": "Nick Mills-Barrett",
          "type": "single",
          "unreadCount": 2,
          "isArchived": false,
          "isMuted": true,
          "isPinned": false,
          "lastActivity": "2025-08-31T16:45:10.123Z",
          "lastReadMessageSortKey": 449706228480,
          "localChatID": "1229721"
        }
      },
      "hasMore": true,
      "items": [
        {
          "id": "1343993",
          "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
          "chatID": "!signal_adamvy:local-signal.localhost",
          "senderID": "@adamvy:local-signal.localhost",
          "sortKey": "sortKey",
          "timestamp": "2025-08-28T11:04:29.621Z",
          "attachments": [
            {
              "type": "unknown",
              "duration": 0,
              "fileName": "fileName",
              "fileSize": 0,
              "isGif": true,
              "isSticker": true,
              "isVoiceNote": true,
              "mimeType": "mimeType",
              "posterImg": "posterImg",
              "size": {
                "height": 0,
                "width": 0
              },
              "srcURL": "srcURL"
            }
          ],
          "isSender": false,
          "isUnread": false,
          "reactions": [
            {
              "id": "id",
              "participantID": "participantID",
              "reactionKey": "reactionKey",
              "emoji": true,
              "imgURL": "imgURL"
            }
          ],
          "senderName": "Adam Van Ymeren",
          "text": "Hey, can we reschedule our meeting to 3pm?"
        },
        {
          "id": "1343994",
          "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
          "chatID": "!telegram_nick:local-telegram.localhost",
          "senderID": "@nick:local-telegram.localhost",
          "sortKey": "sortKey",
          "timestamp": "2025-08-28T14:22:15.432Z",
          "attachments": [
            {
              "type": "unknown",
              "duration": 0,
              "fileName": "fileName",
              "fileSize": 0,
              "isGif": true,
              "isSticker": true,
              "isVoiceNote": true,
              "mimeType": "mimeType",
              "posterImg": "posterImg",
              "size": {
                "height": 0,
                "width": 0
              },
              "srcURL": "srcURL"
            }
          ],
          "isSender": false,
          "isUnread": true,
          "reactions": [
            {
              "id": "id",
              "participantID": "participantID",
              "reactionKey": "reactionKey",
              "emoji": true,
              "imgURL": "imgURL"
            }
          ],
          "senderName": "Nick Mills-Barrett",
          "text": "The deployment is complete, everything looks good"
        }
      ],
      "newestCursor": null,
      "oldestCursor": "1756379069621"
    }
  }
}