# Endpoint reference

> **Tip:** Prefer a machine-readable spec? The full [OpenAPI 3.1 document](https://portal.cherry.fun/openapi.json) covers every endpoint on this page, including the dual `cherry_sk_` / `cherry_bot_` bearer schemes and the required scope per operation. Import it into Postman, generate a client, or hand it to an agent.

Every Cherry API endpoint at a glance. Two surfaces, each with its own key and base URL - see [Authentication](https://portal.cherry.fun/docs/api/authentication.md):

- **Apps API:** base `https://api.cherry.fun/api/v1/apps`, project key `Bearer cherry_sk_<projectId>_<secret>`.
- **Bot API:** base `https://api.cherry.fun/api/v1/bots`, bot key `Bearer cherry_bot_<botId>_<secret>`.

## Apps API: App

| Method | Path | Scope | Description |
|---|---|---|---|
| `GET` | `/apps/me` |  | Your project key's context: scopes, bot wallet, rate limits. |

## Apps API: Groups (rooms)

| Method | Path | Scope | Description |
|---|---|---|---|
| `POST` | `/apps/groups` | `groups:create` | [Create a room](https://portal.cherry.fun/docs/api/rooms.md). Returns `{ roomId }`. |
| `GET` | `/apps/groups` | `groups:manage` | List your project's rooms (cursor-paginated). |
| `GET` | `/apps/groups/:roomId` | `groups:manage` | Get one room. |
| `PATCH` | `/apps/groups/:roomId` | `groups:manage` | Update title / description / avatar / settings. |
| `DELETE` | `/apps/groups/:roomId` | `groups:manage` | Delete a project-created room. |

## Apps API: Members

| Method | Path | Scope | Description |
|---|---|---|---|
| `POST` | `/apps/groups/:roomId/members` | `members:invite` | [Bulk-invite wallets](https://portal.cherry.fun/docs/api/members.md) (`autoAccept` optional). |
| `DELETE` | `/apps/groups/:roomId/members/:wallet` | `members:moderate` | Kick a member. |
| `POST` | `/apps/groups/:roomId/members/:wallet/ban` | `members:moderate` | Ban (`deleteMessages` optional). |
| `POST` | `/apps/groups/:roomId/members/:wallet/unban` | `members:moderate` | Unban. |
| `POST` | `/apps/groups/:roomId/members/:wallet/mute` | `members:moderate` | Mute (`untilTs` optional). |
| `POST` | `/apps/groups/:roomId/members/:wallet/unmute` | `members:moderate` | Unmute. |
| `POST` | `/apps/groups/:roomId/members/:wallet/role` | `members:moderate` | Set role (`admin`/`moderator`/`member`). |

## Apps API: Messages

| Method | Path | Scope | Description |
|---|---|---|---|
| `POST` | `/apps/groups/:roomId/messages` | `messages:send` | [Send a message](https://portal.cherry.fun/docs/api/messages.md) as the app bot. |
| `GET` | `/apps/groups/:roomId/messages` | `messages:read` | List messages (newest first). |
| `DELETE` | `/apps/groups/:roomId/messages/:messageId` | `messages:delete` | Delete a message. |

## Bot API

Bot endpoints take a JSON body (no path params) and act as the bot's wallet.

| Method | Path | Scope | Description |
|---|---|---|---|
| `GET` | `/bots/me` |  | The bot's identity, wallet, and scopes. |
| `POST` | `/bots/sendDirectMessage` | `bots:dm:send` | DM a user as the bot. |
| `GET` | `/bots/getDirectChat` | `bots:dm:read` | DM history with one user. |
| `POST` | `/bots/sendGroupMessage` | `bots:groups:send` | Post a message into a group. |
| `POST` | `/bots/sendInteractiveMessage` | `bots:interactive` | Send a message with inline buttons / keyboard. |
| `POST` | `/bots/answerCallbackQuery` | `bots:callback:answer` | Respond to an inline button press. |
| `POST` | `/bots/banGroupMember` | `bots:groups:moderate` | [Ban](https://portal.cherry.fun/docs/api/members.md) (`{ roomId, wallet, deleteMessages? }`). |
| `POST` | `/bots/unbanGroupMember` | `bots:groups:moderate` | Unban (`{ roomId, wallet }`). |
| `POST` | `/bots/kickGroupMember` | `bots:groups:moderate` | Kick (`{ roomId, wallet }`). |
| `POST` | `/bots/muteGroupMember` | `bots:groups:moderate` | Mute (`{ roomId, wallet }`). |
| `POST` | `/bots/unmuteGroupMember` | `bots:groups:moderate` | Unmute (`{ roomId, wallet }`). |
| `POST` | `/bots/deleteGroupMessage` | `bots:groups:moderate` | Delete a message (`{ roomId, messageId }`). |
| `POST` | `/bots/editMessageText` | `messages:edit` | Edit a message the bot sent. |
| `POST` | `/bots/editMessageReplyMarkup` | `messages:edit` | Replace the inline keyboard on a message the bot sent. |
| `GET` | `/bots/getUpdates` | `bots:updates:poll` | Long-poll for updates (Telegram-style). |
| `POST` | `/bots/setWebhook` | `bots:webhook:manage` | Configure a webhook for updates. |
| `POST` | `/bots/deleteWebhook` | `bots:webhook:manage` | Remove the configured webhook. |

> **Note:** Bot moderation is gated by **two** layers: the `bots:groups:moderate` scope <em>and</em> the bot's in-room role (owner/admin/moderator). See [Members &amp; moderation](https://portal.cherry.fun/docs/api/members.md).

See [Scopes](https://portal.cherry.fun/docs/api/scopes.md) and [Rate limits & errors](https://portal.cherry.fun/docs/api/rate-limits.md) for the cross-cutting rules.