# Client

## Focus

**post** `/v1/focus`

Focus Beeper Desktop and optionally navigate to a specific chat, message, or pre-fill draft text and attachment.

### Body Parameters

- `chatID: optional string`

  Optional Beeper chat ID (or local chat ID) to focus after opening the app. If omitted, only opens/focuses the app.

- `draftAttachmentPath: optional string`

  Optional draft attachment path to populate in the message input field.

- `draftText: optional string`

  Optional draft text to populate in the message input field.

- `messageID: optional string`

  Optional message ID. Jumps to that message in the chat when opening.

### Returns

- `success: boolean`

  Whether the app was successfully opened/focused.

### Example

```http
curl http://localhost:23373/v1/focus \
    -X POST
```

## 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`

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

### Returns

- `results: object { chats, in_groups, messages }`

  - `chats: array of Chat`

    Top chat results.

    - `id: string`

      Unique identifier of the chat across Beeper.

    - `accountID: string`

      Account ID this chat belongs to.

    - `participants: object { hasMore, items, total }`

      Chat participants information.

      - `hasMore: boolean`

        True if there are more participants than included in items.

      - `items: array of User`

        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.

      - `"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.

    - `lastReadMessageSortKey: optional string`

      Last read message sortKey.

    - `localChatID: optional string`

      Local chat ID specific to this Beeper Desktop installation.

  - `in_groups: array of Chat`

    Top group results by participant matches.

    - `id: string`

      Unique identifier of the chat across Beeper.

    - `accountID: string`

      Account ID this chat belongs to.

    - `participants: object { hasMore, items, total }`

      Chat participants information.

      - `hasMore: boolean`

        True if there are more participants than included in items.

      - `items: array of User`

        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.

      - `"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.

    - `lastReadMessageSortKey: optional string`

      Last read message sortKey.

    - `localChatID: optional string`

      Local chat ID specific to this Beeper Desktop installation.

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

    - `chats: map[Chat]`

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

      - `id: string`

        Unique identifier of the chat across Beeper.

      - `accountID: string`

        Account ID this chat belongs to.

      - `participants: object { hasMore, items, total }`

        Chat participants information.

        - `hasMore: boolean`

          True if there are more participants than included in items.

        - `items: array of User`

          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.

        - `"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.

      - `lastReadMessageSortKey: optional string`

        Last read message sortKey.

      - `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`

      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, sortable key used to sort messages.

      - `timestamp: string`

        Message timestamp.

      - `attachments: optional array of Attachment`

        Attachments included with this message, if any.

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

          Attachment type.

          - `"unknown"`

          - `"img"`

          - `"video"`

          - `"audio"`

        - `id: optional string`

          Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path.

        - `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.

      - `linkedMessageID: optional string`

        ID of the message this is a reply to, if any.

      - `reactions: optional array of Reaction`

        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.

      - `type: optional "TEXT" or "NOTICE" or "IMAGE" or 7 more`

        Message content type. Useful for distinguishing reactions, media messages, and state events from regular text messages.

        - `"TEXT"`

        - `"NOTICE"`

        - `"IMAGE"`

        - `"VIDEO"`

        - `"VOICE"`

        - `"AUDIO"`

        - `"FILE"`

        - `"STICKER"`

        - `"LOCATION"`

        - `"REACTION"`

    - `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.

### Example

```http
curl http://localhost:23373/v1/search
```