--- title: Search - Beeper Developer Docs --- Deprecated GET/v0/search - Beeper Desktop API server http\://localhost:23373/v0/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. **Use [`GET /v1/search`](/desktop-api-reference/resources/app/methods/search/index.md) instead.** ## Parameters ### Query Parameters **query** required User-typed search text. Literal word matching (NOT semantic). string \>= 1 characters User-typed search text. Literal word matching (NOT semantic). ## Responses ### 200 Tool executed successfully Select media typeapplication/json object **results** required object **chats** required Top chat results. Array\ object **id** required Unique identifier of the chat (room/thread ID, same as id) across Beeper. string ##### Example ``` !NCdzlIaMjZUmvmvyHU:beeper.com ``` **localChatID** Local chat ID specific to this Beeper Desktop installation. string nullable **accountID** required Beeper account ID this chat belongs to. string **network** required Display-only human-readable network name (e.g., ‘WhatsApp’, ‘Messenger’). You MUST use ‘accountID’ to perform actions. string ##### Example ``` WhatsApp ``` **title** required Display title of the chat as computed by the client/server. string **type** required Chat type: ‘single’ for direct messages, ‘group’ for group chats. string Allowed values: single group **participants** required Chat participants information. object **items** required Participants returned for this chat (limited by the request; may be a subset). Array\ A person on or reachable through Beeper. Values are best-effort and can vary by network. object **id** required Stable Beeper user ID. Use as the primary key when referencing a person. string **username** Human-readable handle if available (e.g., ‘@alice’). May be network-specific and not globally unique. string **phoneNumber** User’s phone number in E.164 format (e.g., ‘+14155552671’). Omit if unknown. string **email** Email address if known. Not guaranteed verified. string **fullName** Display name as shown in clients (e.g., ‘Alice Example’). May include emojis. string **imgURL** Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. string **cannotMessage** True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you. boolean **isSelf** True if this user represents the authenticated account’s own identity. boolean **hasMore** required True if there are more participants than included in items. boolean **total** required Total number of participants in the chat. integer **lastActivity** Timestamp of last activity. Chats with more recent activity are often more important. string format: date-time ##### Example ``` 2025-08-31T23:30:12.520Z ``` **unreadCount** required Number of unread messages. integer ##### Example ``` 3 ``` **lastReadMessageSortKey** Any of: - [integer](#tab-panel-51) - [string](#tab-panel-52) integer string **isArchived** True if chat is archived. boolean **isMuted** True if chat notifications are muted. boolean **isPinned** True if chat is pinned. boolean ##### Example ``` { "id": "!instagram_mattwondra:local-instagram.localhost", "localChatID": "1229391", "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU", "network": "Instagram", "title": "Matt Wondra", "type": "single", "participants": { "items": [ { "id": "@mattwondra:local-instagram.localhost", "username": "mattwondra", "fullName": "Matt Wondra", "cannotMessage": false, "isSelf": false }, { "id": "@batuhan:local-instagram.localhost", "username": "batuhan", "fullName": "Batuhan İçöz", "cannotMessage": false, "isSelf": true } ], "hasMore": false, "total": 2 }, "lastActivity": "2025-08-31T19:41:41.000Z", "unreadCount": 0, "lastReadMessageSortKey": 449706228480, "isArchived": false, "isMuted": false, "isPinned": false } ``` **in\_groups** required Top group results by participant matches. Array\ object **id** required Unique identifier of the chat (room/thread ID, same as id) across Beeper. string ##### Example ``` !NCdzlIaMjZUmvmvyHU:beeper.com ``` **localChatID** Local chat ID specific to this Beeper Desktop installation. string nullable **accountID** required Beeper account ID this chat belongs to. string **network** required Display-only human-readable network name (e.g., ‘WhatsApp’, ‘Messenger’). You MUST use ‘accountID’ to perform actions. string ##### Example ``` WhatsApp ``` **title** required Display title of the chat as computed by the client/server. string **type** required Chat type: ‘single’ for direct messages, ‘group’ for group chats. string Allowed values: single group **participants** required Chat participants information. object **items** required Participants returned for this chat (limited by the request; may be a subset). Array\ A person on or reachable through Beeper. Values are best-effort and can vary by network. object **id** required Stable Beeper user ID. Use as the primary key when referencing a person. string **username** Human-readable handle if available (e.g., ‘@alice’). May be network-specific and not globally unique. string **phoneNumber** User’s phone number in E.164 format (e.g., ‘+14155552671’). Omit if unknown. string **email** Email address if known. Not guaranteed verified. string **fullName** Display name as shown in clients (e.g., ‘Alice Example’). May include emojis. string **imgURL** Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. string **cannotMessage** True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you. boolean **isSelf** True if this user represents the authenticated account’s own identity. boolean **hasMore** required True if there are more participants than included in items. boolean **total** required Total number of participants in the chat. integer **lastActivity** Timestamp of last activity. Chats with more recent activity are often more important. string format: date-time ##### Example ``` 2025-08-31T23:30:12.520Z ``` **unreadCount** required Number of unread messages. integer ##### Example ``` 3 ``` **lastReadMessageSortKey** Any of: - [integer](#tab-panel-53) - [string](#tab-panel-54) integer string **isArchived** True if chat is archived. boolean **isMuted** True if chat notifications are muted. boolean **isPinned** True if chat is pinned. boolean ##### Example ``` { "id": "!instagram_mattwondra:local-instagram.localhost", "localChatID": "1229391", "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU", "network": "Instagram", "title": "Matt Wondra", "type": "single", "participants": { "items": [ { "id": "@mattwondra:local-instagram.localhost", "username": "mattwondra", "fullName": "Matt Wondra", "cannotMessage": false, "isSelf": false }, { "id": "@batuhan:local-instagram.localhost", "username": "batuhan", "fullName": "Batuhan İçöz", "cannotMessage": false, "isSelf": true } ], "hasMore": false, "total": 2 }, "lastActivity": "2025-08-31T19:41:41.000Z", "unreadCount": 0, "lastReadMessageSortKey": 449706228480, "isArchived": false, "isMuted": false, "isPinned": false } ``` **messages** required object **items** required Messages matching the query and filters. Array\ object **id** required Stable message ID for cursor pagination. string ##### Example ``` 1343993 ``` **messageID** required Stable message ID (same as id). string ##### Example ``` 1343993 ``` **chatID** required Beeper chat/thread/room ID. string ##### Example ``` !NCdzlIaMjZUmvmvyHU:beeper.com ``` **accountID** required Beeper account ID the message belongs to. string **senderID** required Sender user ID. string ##### Example ``` @kishanbagaria:local-whatsapp.localhost ``` **senderName** Resolved sender display name (impersonator/full name/username/participant name). string **timestamp** required Message timestamp. string format: date-time ##### Example ``` 2025-08-31T23:30:12.520Z ``` **sortKey** required Any of: - [string](#tab-panel-55) - [number](#tab-panel-56) string number **text** Plain-text body if present. May include a JSON fallback with text entities for rich messages. string **isSender** True if the authenticated user sent the message. boolean **attachments** Attachments included with this message, if any. Array\ object **type** required Attachment type. string Allowed values: unknown img video audio **srcURL** 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. string **mimeType** MIME type if known (e.g., ‘image/png’). string **fileName** Original filename if available. string **fileSize** File size in bytes if known. number **isGif** True if the attachment is a GIF. boolean **isSticker** True if the attachment is a sticker. boolean **isVoiceNote** True if the attachment is a voice note. boolean **duration** Duration in seconds (audio/video). number **posterImg** Preview image URL for video attachments (poster frame). May be temporary or local-only to this device; download promptly if durable access is needed. string **size** Pixel dimensions of the attachment: width/height in px. object **width** number **height** number **isUnread** True if the message is unread for the authenticated user. May be omitted. boolean **reactions** Reactions to the message, if any. Array\ object **id** required Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise. string **reactionKey** required The reaction key: an emoji (😄), a network-specific key, or a shortcode like “smiling-face”. string **imgURL** URL to the reaction’s image. May be temporary or local-only to this device; download promptly if durable access is needed. string **participantID** required User ID of the participant who reacted. string **emoji** True if the reactionKey is an emoji. boolean ##### Example ``` { "id": "1343993", "messageID": "1343993", "chatID": "!signal_adamvy:local-signal.localhost", "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY", "senderID": "@adamvy:local-signal.localhost", "senderName": "Adam Van Ymeren", "timestamp": "2025-08-28T11:04:29.621Z", "sortKey": 821744079, "text": "Hey, can we reschedule our meeting to 3pm?", "isSender": false, "isUnread": false } ``` **chats** required Map of chatID -> chat details for chats referenced in items. object ***key*** additional properties object **id** required Unique identifier of the chat (room/thread ID, same as id) across Beeper. string ##### Example ``` !NCdzlIaMjZUmvmvyHU:beeper.com ``` **localChatID** Local chat ID specific to this Beeper Desktop installation. string nullable **accountID** required Beeper account ID this chat belongs to. string **network** required Display-only human-readable network name (e.g., ‘WhatsApp’, ‘Messenger’). You MUST use ‘accountID’ to perform actions. string ##### Example ``` WhatsApp ``` **title** required Display title of the chat as computed by the client/server. string **type** required Chat type: ‘single’ for direct messages, ‘group’ for group chats. string Allowed values: single group **participants** required Chat participants information. object **items** required Participants returned for this chat (limited by the request; may be a subset). Array\ A person on or reachable through Beeper. Values are best-effort and can vary by network. object **id** required Stable Beeper user ID. Use as the primary key when referencing a person. string **username** Human-readable handle if available (e.g., ‘@alice’). May be network-specific and not globally unique. string **phoneNumber** User’s phone number in E.164 format (e.g., ‘+14155552671’). Omit if unknown. string **email** Email address if known. Not guaranteed verified. string **fullName** Display name as shown in clients (e.g., ‘Alice Example’). May include emojis. string **imgURL** Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. string **cannotMessage** True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you. boolean **isSelf** True if this user represents the authenticated account’s own identity. boolean **hasMore** required True if there are more participants than included in items. boolean **total** required Total number of participants in the chat. integer **lastActivity** Timestamp of last activity. Chats with more recent activity are often more important. string format: date-time ##### Example ``` 2025-08-31T23:30:12.520Z ``` **unreadCount** required Number of unread messages. integer ##### Example ``` 3 ``` **lastReadMessageSortKey** Any of: - [integer](#tab-panel-57) - [string](#tab-panel-58) integer string **isArchived** True if chat is archived. boolean **isMuted** True if chat notifications are muted. boolean **isPinned** True if chat is pinned. boolean ##### Example ``` { "id": "!instagram_mattwondra:local-instagram.localhost", "localChatID": "1229391", "accountID": "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU", "network": "Instagram", "title": "Matt Wondra", "type": "single", "participants": { "items": [ { "id": "@mattwondra:local-instagram.localhost", "username": "mattwondra", "fullName": "Matt Wondra", "cannotMessage": false, "isSelf": false }, { "id": "@batuhan:local-instagram.localhost", "username": "batuhan", "fullName": "Batuhan İçöz", "cannotMessage": false, "isSelf": true } ], "hasMore": false, "total": 2 }, "lastActivity": "2025-08-31T19:41:41.000Z", "unreadCount": 0, "lastReadMessageSortKey": 449706228480, "isArchived": false, "isMuted": false, "isPinned": false } ``` **hasMore** required True if additional results can be fetched using the provided cursors. boolean **oldestCursor** required Cursor for fetching older results (use with direction=‘before’). Opaque string; do not inspect. string nullable ##### Example ``` 1725489123456|c29tZUltc2dQYWdl ``` **newestCursor** required Cursor for fetching newer results (use with direction=‘after’). Opaque string; do not inspect. string nullable ##### Example ``` 1725489123456|c29tZUltc2dQYWdl ``` ##### Example ``` { "items": [ { "id": "1343993", "messageID": "1343993", "chatID": "!signal_adamvy:local-signal.localhost", "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY", "senderID": "@adamvy:local-signal.localhost", "senderName": "Adam Van Ymeren", "timestamp": "2025-08-28T11:04:29.621Z", "sortKey": 821744079, "text": "Hey, can we reschedule our meeting to 3pm?", "isSender": false, "isUnread": false }, { "id": "1343994", "messageID": "1343994", "chatID": "!telegram_nick:local-telegram.localhost", "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI", "senderID": "@nick:local-telegram.localhost", "senderName": "Nick Mills-Barrett", "timestamp": "2025-08-28T14:22:15.432Z", "sortKey": 821755234, "text": "The deployment is complete, everything looks good", "isSender": false, "isUnread": true } ], "chats": { "!signal_adamvy:local-signal.localhost": { "id": "!signal_adamvy:local-signal.localhost", "localChatID": "1229720", "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY", "network": "Signal", "title": "Adam Van Ymeren", "type": "single", "participants": { "items": [ { "id": "@adamvy:local-signal.localhost", "fullName": "Adam Van Ymeren", "cannotMessage": false, "isSelf": false }, { "id": "@batuhan:local-signal.localhost", "fullName": "Batuhan İçöz", "cannotMessage": false, "isSelf": true } ], "hasMore": false, "total": 2 }, "lastActivity": "2025-08-31T17:38:20.393Z", "unreadCount": 0, "isArchived": false, "isMuted": false, "isPinned": true }, "!telegram_nick:local-telegram.localhost": { "id": "!telegram_nick:local-telegram.localhost", "localChatID": "1229721", "accountID": "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI", "network": "Telegram", "title": "Nick Mills-Barrett", "type": "single", "participants": { "items": [ { "id": "@nick:local-telegram.localhost", "username": "nick", "fullName": "Nick Mills-Barrett", "cannotMessage": false, "isSelf": false }, { "id": "@batuhan:local-telegram.localhost", "username": "batuhan", "fullName": "Batuhan İçöz", "cannotMessage": false, "isSelf": true } ], "hasMore": false, "total": 2 }, "lastActivity": "2025-08-31T16:45:10.123Z", "unreadCount": 2, "isArchived": false, "isMuted": true, "isPinned": false } }, "hasMore": true, "oldestCursor": "1756379069621", "newestCursor": null } ``` ### 400 Invalid request parameters Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 401 Access token is missing or invalid Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 403 Access token does not have the required scope Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 404 Resource not found Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 422 Unprocessable entity - validation error Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 429 Too many requests - rate limit exceeded Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string ### 500 Internal server error Select media typeapplication/json object **error** required Error message string **code** Error code string **details** Additional error details object ***key*** additional properties string