--- title: "Search messages" method: GET path: "/v1/messages/search" tags: ["Messages"] --- # Search messages `GET /v1/messages/search` Search messages across chats using Beeper's message index ## Query parameters - `query` string — Literal word search (non-semantic). Finds messages containing these EXACT words in any order. Use single words users actually type, not concepts or phrases. Example: use "dinner" not "dinner plans", use "sick" not "health issues". If omitted, returns results filtered only by other parameters. - `cursor` string — Opaque pagination cursor; do not inspect. Use together with 'direction'. - `direction` 'after' | 'before' — Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided. - `chatIDs` string[] — Limit search to specific chat IDs. - `accountIDs` string[] — Limit search to specific account IDs. - `chatType` 'group' | 'single' — Filter by chat type: 'group' for group chats, 'single' for 1:1 chats. - `mediaTypes` string[] — Filter messages by media types. Use ['any'] for any media type, or specify exact types like ['video', 'image']. Omit for no media filtering. - `sender` string — Filter by sender: 'me' (messages sent by the authenticated user), 'others' (messages sent by others), or a specific user ID string (user.id). - `dateAfter` string, date-time — Only include messages with timestamp strictly after this ISO 8601 datetime (e.g., '2024-07-01T00:00:00Z' or '2024-07-01T00:00:00+02:00'). - `dateBefore` string, date-time — Only include messages with timestamp strictly before this ISO 8601 datetime (e.g., '2024-07-31T23:59:59Z' or '2024-07-31T23:59:59+02:00'). - `limit` integer — Maximum number of messages to return. - `excludeLowPriority` boolean, nullable — Exclude messages marked Low Priority by the user. Default: true. Set to false to include all. - `includeMuted` boolean, nullable — Include messages in chats marked as Muted by the user, which are usually less important. Default: true. Set to false if the user wants a more refined search. ## Response `200` Request executed successfully - SearchMessagesOutput - `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)