API

Mirage apps and bots

Applications, bot users and tokens, installing into servers, slash commands, interactions and events.

See Mirage. An application has a bot user and a token (Authorization: Bot si_bot_…) that reaches the Mirage routes bots may use, within the permissions of the role it was installed with. Interactions and events are POSTed to the app's endpoint, signed with its Ed25519 key (x-signature-ed25519 over x-signature-timestamp and the body); the endpoint must answer a signed PING and refuse a badly signed one before it's saved.

Every route below, with its parameters, request and response, errors and samples, is in the API reference.

Route	What it does
`GET /v1/hooks/messaging/apps/:appId/icon`	An app's image icon (a redirect), when it has one. No authentication.
`POST /v1/hooks/messaging/webhooks/:appId/:token`	A follow-up message from the app's bot (`content`), as a reply to the original response. The interaction's token (15 minutes) is the only credential.
`PATCH /v1/hooks/messaging/webhooks/:appId/:token/messages/@original`	Edits the original response to an interaction, or posts it after a deferred answer (`content`).
`DELETE /v1/hooks/messaging/webhooks/:appId/:token/messages/@original`	Deletes the original response to an interaction.
`GET /v1/messaging/applications`	Your applications (the developer portal's Mirage Bots), oldest first: each with its bot, public key, interactions endpoint, events and install settings.
`POST /v1/messaging/applications`	Makes an application (`name` 2 to 32 characters, `description`, `icon` emoji; an image icon is uploaded after) with its bot user (`bot_…`), an Ed25519 key pair that signs what Mirage sends it, and a bot token (`si_bot_…`) returned this once.
`GET /v1/messaging/applications/:appId`	One of your applications; with a bot token, `@me` is the bot's own.
`PATCH /v1/messaging/applications/:appId`	Changes an application: `name`, `description`, `icon` (an emoji, an uploaded `image:<version>`, or null); `installTypes` (`guild` for servers, `user` for people's own accounts); `interactionsUrl` (HTTPS, saved only once it answers a signed PING with `{"type": 1}` and refuses a badly signed one with 401; null removes it); `events` (`message_mention`, `member_join`); `public` (listed in the App Directory, and anyone who manages a server may add it); `permissions` its install link asks for.
`DELETE /v1/messaging/applications/:appId`	Deletes an application: its bot leaves every server and its roles go, with its commands and token.
`POST /v1/messaging/applications/:appId/token`	Resets the bot token: the old one stops working at once; the new one is returned this once.
`POST /v1/messaging/applications/:appId/icon/uploads`	Where to PUT an image icon (`mime`: PNG, JPEG, WebP or GIF; `size` up to 1 MB); then set the answer's `icon` (`image:<version>`) with a PATCH. Its owner.
`GET /v1/messaging/applications/:appId/deliveries`	What Mirage sent the app's interactions endpoint lately (kept for days, as platform data sets): `kind` (`command`, `component`, `modal`, `autocomplete`, `event:<type>`, `ping`), a summary, the status, time taken and any error, newest first. `kind` filters, `before` pages. Its owner.
`GET /v1/messaging/me/applications`	Apps you added to your account (user installs): their commands work in every server you're in.
`PUT /v1/messaging/me/applications/:appId`	Adds an app that allows user installs to your account (up to a limit set as platform data). Where a server doesn't give outside apps `USE_EXTERNAL_APPS`, only you see its answers.
`DELETE /v1/messaging/me/applications/:appId`	Removes an app from your account.
`GET /v1/messaging/applications/:appId/commands`	The app's global slash commands. Its owner, or its bot with its token.
`PUT /v1/messaging/applications/:appId/commands`	Replaces the app's global commands with these (up to 100): `name`, `description`, and `options` (`string`, `integer`, `number`, `boolean`, `user`, `channel` or `role`; required ones first; `choices`, or `autocomplete` for the app to suggest values as they're typed). Its owner, or its bot.
`POST /v1/messaging/applications/:appId/commands`	Adds or replaces one global command (by `name`).
`DELETE /v1/messaging/applications/:appId/commands/:command`	Deletes a global command.
`GET /v1/messaging/applications/:appId/servers/:serverId/commands`	The app's commands for one server its bot is in.
`PUT /v1/messaging/applications/:appId/servers/:serverId/commands`	Replaces the app's commands for one server its bot is in; there they take the place of global commands of the same name.
`POST /v1/messaging/applications/:appId/servers/:serverId/commands`	Adds or replaces one of the app's commands for a server.
`DELETE /v1/messaging/applications/:appId/servers/:serverId/commands/:command`	Deletes one of the app's commands for a server.
`GET /v1/messaging/applications/:appId/authorize`	What an install link shows (`permissions` from the link, else the app's): the app, the permissions it asks for, and the servers you manage (`installed` where its bot already is). A private app shows only to its owner.
`POST /v1/messaging/applications/:appId/install`	Adds the app's bot to a server you manage (`serverId`; `permissions`, only ones you have). It joins with a role named after it holding them, which can't be deleted, given or taken by hand; removing the bot removes the role. `MANAGE_SERVER`.
`GET /v1/messaging/servers/:serverId/integrations`	The server's apps: Caity (built in) and the bots people added, with who added them, what they were given and their commands. `MANAGE_SERVER`.
`DELETE /v1/messaging/servers/:serverId/integrations/:appId`	Removes an app's bot and its role from the server. Caity can't be removed: keep it out of channels with channel permissions. `MANAGE_SERVER`.
`GET /v1/messaging/directory`	The App Directory: Caity, then public apps by how many servers use them; with `serverId`, which are already there.
`GET /v1/messaging/servers/:serverId/commands`	Every slash command you can use in a server (the composer's "/" list): Caity's, then each app's.
`POST /v1/messaging/channels/:channelId/interactions`	Uses a slash command (`appId`, `name`, `options` as `{ name, value }`) in a channel or thread where you can send messages; the app's bot must be able to post there too. The app's endpoint gets a signed interaction (type 2, with a `token`) and answers within 3 seconds with a message (`{"type": 4, "data": {"content": …, "components": …}}`; `flags: 64` shows it only to you), a modal (type 9) or deferred (`{"type": 5}`), then follows up with the token. Apps on your account answer where their bot isn't a member (only to you without `USE_EXTERNAL_APPS`). Caity answers `/caity` from its worker (deferred).
`POST /v1/messaging/channels/:channelId/interactions/autocomplete`	What an option with `autocomplete` suggests while it's typed (`appId`, `name`, `options` with the one being typed `focused`): the app gets a signed interaction (type 4) and answers with up to 25 `choices`.
`POST /v1/messaging/channels/:channelId/messages/:messageId/components`	Presses a button or chooses in a select menu on an app's message (`customId`, `values` for a menu): the app gets a signed interaction (type 3) and answers with a message (type 4, `flags: 64` for only you), deferred (5 or 6), a change to the message (7) or a modal (9). Returns `message`, `updated` or `modal`. In a user, role or channel select (types 5, 6 and 8) every value must be a member, a role, or a channel you can see of the menu's `channelTypes`; the app gets them in `resolved`.
`GET /v1/messaging/channels/:channelId/messages/:messageId/components/:customId/choices`	What a user, role or channel select on an app's message offers you: the server's members, its roles, or the channels you can see (`q` narrows by name; up to 25), and its `defaultValues` among them (`choices`, `defaults`). Nothing goes to the app.
`POST /v1/messaging/modals/:modalId`	Submits a modal an app showed you (`components` as `{ customId, value }`): the app gets a signed interaction (type 5) and answers as for a component.