--- title: "Search" method: GET path: "/v1/search" tags: ["App"] --- # 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. ## Query parameters - `query` string, required — User-typed search text. Literal word matching (non-semantic). ## Response `200` Request executed successfully - UnifiedSearchOutput - `results` object, required - `chats` Chat[], required — Top chat results. - `id` string, required — Unique identifier of the chat across Beeper. - `localChatID` string, nullable — Local chat ID specific to this Beeper Desktop installation. - `accountID` string, required — Account ID this chat belongs to. - `title` string, required — Display title of the chat as computed by the client/server. - `type` 'single' | 'group', required — Chat type: 'single' for direct messages, 'group' for group chats. - `participants` object, required — Chat participants information. - `items` object[], required — Participants returned for this chat (limited by the request; may be a subset). - `id` string, required — Stable Beeper user ID. Use as the primary key when referencing a person. - `username` string — Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `phoneNumber` string — User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `email` string — Email address if known. Not guaranteed verified. - `fullName` string — Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL` string — Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `cannotMessage` 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. - `isSelf` boolean — True if this user represents the authenticated account's own identity. - `hasMore` boolean, required — True if there are more participants than included in items. - `total` integer, required — Total number of participants in the chat. - `lastActivity` string, date-time — Timestamp of last activity. - `unreadCount` integer, required — Number of unread messages. - `lastReadMessageSortKey` string — Last read message sortKey. - `isArchived` boolean — True if chat is archived. - `isMuted` boolean — True if chat notifications are muted. - `isPinned` boolean — True if chat is pinned. - `in_groups` Chat[], required — Top group results by participant matches. - `id` string, required — Unique identifier of the chat across Beeper. - `localChatID` string, nullable — Local chat ID specific to this Beeper Desktop installation. - `accountID` string, required — Account ID this chat belongs to. - `title` string, required — Display title of the chat as computed by the client/server. - `type` 'single' | 'group', required — Chat type: 'single' for direct messages, 'group' for group chats. - `participants` object, required — Chat participants information. - `items` object[], required — Participants returned for this chat (limited by the request; may be a subset). - `id` string, required — Stable Beeper user ID. Use as the primary key when referencing a person. - `username` string — Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `phoneNumber` string — User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `email` string — Email address if known. Not guaranteed verified. - `fullName` string — Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL` string — Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `cannotMessage` 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. - `isSelf` boolean — True if this user represents the authenticated account's own identity. - `hasMore` boolean, required — True if there are more participants than included in items. - `total` integer, required — Total number of participants in the chat. - `lastActivity` string, date-time — Timestamp of last activity. - `unreadCount` integer, required — Number of unread messages. - `lastReadMessageSortKey` string — Last read message sortKey. - `isArchived` boolean — True if chat is archived. - `isMuted` boolean — True if chat notifications are muted. - `isPinned` boolean — True if chat is pinned. - `messages` SearchMessagesOutput, required - `items` Message[], required — Messages matching the query and filters. - `id` string, required — Message ID. - `chatID` string, required — Unique identifier of the chat. - `accountID` string, required — Beeper account ID the message belongs to. - `senderID` string, required — Sender user ID. - `senderName` string — Resolved sender display name (impersonator/full name/username/participant name). - `timestamp` string, date-time, required — Message timestamp. - `sortKey` string, required — A unique, sortable key used to sort messages. - `type` 'TEXT' | 'NOTICE' | 'IMAGE' | 'VIDEO' | 'VOICE' | 'AUDIO' | 'FILE' | 'STICKER' | 'LOCATION' | 'REACTION' — Message content type. Useful for distinguishing reactions, media messages, and state events from regular text messages. - `text` string — Plain-text body if present. May include a JSON fallback with text entities for rich messages. - `isSender` boolean — True if the authenticated user sent the message. - `attachments` Attachment[] — Attachments included with this message, if any. - `id` string — Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path. - `type` 'unknown' | 'img' | 'video' | 'audio', required — Attachment type. - `srcURL` 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. - `mimeType` string — MIME type if known (e.g., 'image/png'). - `fileName` string — Original filename if available. - `fileSize` number — File size in bytes if known. - `isGif` boolean — True if the attachment is a GIF. - `isSticker` boolean — True if the attachment is a sticker. - `isVoiceNote` boolean — True if the attachment is a voice note. - `duration` number — Duration in seconds (audio/video). - `posterImg` 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` object — Pixel dimensions of the attachment: width/height in px. - `width` number - `height` number - `isUnread` boolean — True if the message is unread for the authenticated user. May be omitted. - `linkedMessageID` string — ID of the message this is a reply to, if any. - `reactions` Reaction[] — Reactions to the message, if any. - `id` string, required — Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise. - `reactionKey` string, required — The reaction key: an emoji (😄), a network-specific key, or a shortcode like "smiling-face". - `imgURL` string — URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed. - `participantID` string, required — User ID of the participant who reacted. - `emoji` boolean — True if the reactionKey is an emoji. - `chats` object, required — Map of chatID -> chat details for chats referenced in items. - `hasMore` boolean, required — True if additional results can be fetched using the provided cursors. - `oldestCursor` string, nullable, required — Cursor for fetching older results (use with direction='before'). Opaque string; do not inspect. - `newestCursor` string, nullable, required — Cursor for fetching newer results (use with direction='after'). Opaque string; do not inspect. ## Other responses - `400` — Invalid request parameters - `401` — Access token is missing or invalid - `403` — Access token does not have the required scope - `404` — Resource not found - `422` — Unprocessable entity - validation error - `429` — Too many requests - rate limit exceeded - `500` — Internal server error --- [API](https://skmtc.net/beeper/apis/beeper-desktop-api.md) · [All operations](https://skmtc.net/beeper/apis/beeper-desktop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/beeper/beeper-desktop-api/revisions/5a8ac7b545c4/schema)