API

Mirage Discord bridge

Linking Discord accounts, bridging a server with a Discord server, channel pairs and importing from Discord.

See Mirage. A server bridges with one Discord server where Caity's bot is: in each pair of channels, messages, edits, deletes and reactions cross the way you choose. Connecting and pairing check both sides, so you link your Discord account first (POST me/discord, then Discord sends you back to the Mirage app). Messages that came from Discord carry display (the name and avatar they were sent with, source: "discord" and their ids there); people who linked their account write as themselves. Files of messages sent to Discord are reachable by the token in their link, under /v1/hooks/messaging.

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/discord/files/:token/:filename`	A file of a message sent to Discord: a redirect to it (cached 5 minutes). The link's token is the only credential; it goes when the message is deleted. No authentication.
`GET /v1/messaging/discord`	Whether the Discord bridge is set up here (`available`, else `reason`), whether accounts can be linked (`linking`), the link that adds the bot to a Discord server (`inviteUrl`) and the bot's name.
`GET /v1/messaging/me/discord`	Your linked Discord account (`account`: id, username, name, when linked), or `null`, and whether linking is available.
`POST /v1/messaging/me/discord`	Starts linking your Discord account: `url` is Discord's consent page (OAuth2 `identify` with PKCE and a one-time state, good for 10 minutes). Discord sends you back to the Mirage app's `/discord/callback`.
`POST /v1/messaging/me/discord/callback`	Finishes linking with what Discord sent back (`code`, `state`), for the person who started. Discord's token is used once to read who you are, then revoked. A Discord account links to one person.
`DELETE /v1/messaging/me/discord`	Unlinks your Discord account: your Discord messages show as from Discord again.
`GET /v1/messaging/servers/:serverId/discord`	The server's bridge: what's set up, your Discord account, the Discord server it's bridged with (or `null`), and its channel pairs with anything the bot still needs in each. `MANAGE_SERVER`.
`PUT /v1/messaging/servers/:serverId/discord`	Bridges the server with a Discord server (`guildId`) the bot is in, where your linked Discord account has Manage Server. A Discord server bridges with one Mirage server. `MANAGE_SERVER`.
`DELETE /v1/messaging/servers/:serverId/discord`	Ends the bridge: its pairs go, their webhooks leave Discord and a running import stops. Messages already across stay. `MANAGE_SERVER`.
`GET /v1/messaging/servers/:serverId/discord/guilds`	Discord servers you could bridge here: the bot is in them and your linked Discord account manages them (`bridged`: taken by another Mirage server). `MANAGE_SERVER`.
`GET /v1/messaging/servers/:serverId/discord/channels`	Both sides' channels, what each is paired with, what the bot can do in each Discord channel (read, webhooks, reactions) and what you can (read, post), and whether you can make channels on each side. `MANAGE_SERVER`.
`POST /v1/messaging/servers/:serverId/discord/channels`	Pairs a Mirage channel (`channelId`, or `newChannel: { name }`) with a Discord channel (`discordChannelId`, or `newDiscordChannel: { name }`) and a `direction`: `both`, `to_discord` or `to_mirage`. You must read both channels and post where messages go; the bot needs Manage Webhooks there for messages going to Discord. `MANAGE_SERVER` (and `MANAGE_CHANNELS` here, or Manage Channels on Discord, for new channels).
`PATCH /v1/messaging/servers/:serverId/discord/channels/:channelId`	Changes which way a pair carries messages (`direction`); a webhook is made when Mirage's messages start going to Discord. `MANAGE_SERVER`.
`DELETE /v1/messaging/servers/:serverId/discord/channels/:channelId`	Unpairs a channel; its webhook leaves Discord. `MANAGE_SERVER`.
`GET /v1/messaging/servers/:serverId/discord/import`	The latest import from Discord and how far it got (roles, channels, messages, files), or `null`. `MANAGE_SERVER`.
`POST /v1/messaging/servers/:serverId/discord/import`	Imports from the bridged Discord server in the background: chosen channels (`channelIds`) with their categories, `roles` (only permissions you have) and each text channel's newest `messages` (as many as the platform's limit allows, 5,000 by default; files copied; members' Discord roles follow for linked people). Channels you choose must be readable by your Discord account. `MANAGE_SERVER`, plus `MANAGE_ROLES` and `MANAGE_CHANNELS` for those.
`DELETE /v1/messaging/servers/:serverId/discord/import`	Stops the running import after its current step; what it made stays. `MANAGE_SERVER`.
`POST /v1/messaging/servers/:serverId/discord/import/resume`	Continues the latest import from where it stopped, when it stopped with a problem or stopped moving (`stalled`, or waiting to retry: `retryAt`). `MANAGE_SERVER`.
`POST /v1/messaging/servers/:serverId/discord/import/pairs`	After an import finished: pairs each imported text, announcement and forum channel with the Discord channel it came from (`direction`, default both; `discordChannelIds` for some only). Returns each channel's result. `MANAGE_SERVER`.