Search

API Reference

Messages

Search messages

get/v0/search-messages

Search messages across chats using Beeper's message index

Query ParametersExpand Collapse

accountIDs: optional array of string

Limit search to specific Beeper account IDs (bridge instances).

chatIDs: optional array of string

Limit search to specific Beeper chat IDs.

chatType: optional "group" or "single"

Filter by chat type: 'group' for group chats, 'single' for 1:1 chats.

Accepts one of the following:

"group"

"single"

cursor: optional string

Opaque pagination cursor; do not inspect. Use together with 'direction'.

dateAfter: optional string

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').

formatdate-time

dateBefore: optional string

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').

formatdate-time

direction: optional "after" or "before"

Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided.

Accepts one of the following:

"after"

"before"

excludeLowPriority: optional boolean

Exclude messages marked Low Priority by the user. Default: true. Set to false to include all.

includeMuted: optional boolean

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.

limit: optional number

Maximum number of messages to return (1–500). Defaults to 50.

minimum0

exclusiveMinimum

maximum500

onlyWithFile: optional boolean

Only return messages that contain file attachments.

onlyWithImage: optional boolean

Only return messages that contain image attachments.

onlyWithLink: optional boolean

Only return messages that contain link attachments.

onlyWithMedia: optional boolean

Only return messages that contain any type of media attachment.

onlyWithVideo: optional boolean

Only return messages that contain video attachments.

query: optional string

Literal word search (NOT 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.

minLength0

sender: optional "me" or "others" or string

Filter by sender: 'me' (messages sent by the authenticated user), 'others' (messages sent by others), or a specific user ID string (user.id).

Accepts one of the following:

UnionMember0 = "me" or "others"

Filter by sender: 'me' (messages sent by the authenticated user), 'others' (messages sent by others), or a specific user ID string (user.id).

"me"

"others"

UnionMember1 = string

ReturnsExpand Collapse

chats: map[Chat]

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

hasMore: boolean

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

items: array of Message

Messages matching the query and filters.

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.

HTTPTypeScript

curl http://localhost:23373/v0/search-messages \
    -H "Authorization: Bearer $BEEPER_ACCESS_TOKEN"

200 example

{
  "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": 0,
      "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": 0,
      "localChatID": "1229721"
    }
  },
  "hasMore": true,
  "items": [
    {
      "id": "1343993",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "chatID": "!signal_adamvy:local-signal.localhost",
      "messageID": "1343993",
      "senderID": "@adamvy:local-signal.localhost",
      "sortKey": 821744079,
      "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",
      "messageID": "1343994",
      "senderID": "@nick:local-telegram.localhost",
      "sortKey": 821755234,
      "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

{
  "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": 0,
      "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": 0,
      "localChatID": "1229721"
    }
  },
  "hasMore": true,
  "items": [
    {
      "id": "1343993",
      "accountID": "local-signal_ba_7N74FrU29pxij_TnqfxeUHj53FY",
      "chatID": "!signal_adamvy:local-signal.localhost",
      "messageID": "1343993",
      "senderID": "@adamvy:local-signal.localhost",
      "sortKey": 821744079,
      "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",
      "messageID": "1343994",
      "senderID": "@nick:local-telegram.localhost",
      "sortKey": 821755234,
      "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"
}