API

Intro

The API can be used to make existing or new services work together with Xenon. The goal of providing this API to other developers is to make the user experience as seamless as possible. This API is at a very early stage and all endpoints are subject to change. (We will notify you before a breaking change happens)

API access is currently only given to very few people. Send merlin.gg a DM if you are interested in getting access.

Tokens have been granted to:

Wick
Bender

API Reference

All endpoints only accept and respond with a JSON body unless specifically stated.

Base Url: https://xenon.bot/api

Rate Limits

There is currently no way to tell when you will hit a rate-limit. The api doesn’t provide headers for that. If the rate limit is exceeded, the API will return a 429 status code with a JSON body. The JSON body contains a retry_after key which represents the number of milliseconds you should wait before making another request.

{
  "error": "You got ratelimited",
  "retry_after": 5000.0
}

Caching

Some endpoints cache the response to increase performance. Those endpoints will have the Cache-Control and Expiration headers set. You can use them to tell how long you can cache the data locally and reduce the load on our API.

Authentication

Most endpoints require authentication using an internal bot token. These tokens are currently manually granted to very few people. Send Merlin.gg a DM if you are interested in getting access.

The API looks for the token in the Authorization header. Unlike the discord-api, you don’t have to prefix the token with “Bot”.

Endpoints

ID Mappers `GET /mappers`

ID Mappers can be used to restore server specific settings after a backup was loaded. This endpoint will return an object containing all the ids that have changed. It can be used to translate IDs from the old server to the ids on the new one.

Might be used in a command like !restore-settings <guild-id / backup-id>.

To make sure that the user has permissions to restore settings from the specified guild, you should check the users permissions on that guild. If the guild no longer exists, you can make use of the loaders key. It contains the ids of the users that have loaded a backup with that guild combination before. This ensures that the user had at least admin on both servers at some point.

Query Parameters

Key	Description	Required	Default
source	ID of the guild where the user wants to restore the settings from (Where the backup was created) (Supplied by the user)	either "source" or "backup"	-
target	ID of the guild where the user wants to restore the settings on (Where the backup was loaded) (Most likely where the command was executed)	yes	-
backup	ID of the backup that was loaded (Supplied by the user)	either "source" or "backup"	-

JSON Body

This endpoint doesn’t accept a body

JSON Response

Key	Description	Always Returned
ids	Object of "old-id" -> "new-id"	yes
loaders	List of users that loaded backups with this guild combination (used for permission checks)	no

Example

Url GET /mappers?target=496683369665658880&source=410488579140354049

JSON Body

{}

JSON Response

{
    "source_id": "410488579140354049",
    "target_id": "496683369665658880",
    "ids": {
        "410488579140354049": "496683369665658880",
        "410520361789161472": "754098965649162251",
        "410533472055066624": "754098969658916895",
        "410534436191469570": "754098966760652860",
        "419932531828457473": "754098968748752987",
        "422869735714324499": "754098972716695573",
        "424288090316603418": "754098973509288008",
        "443833570046509057": "754098971030323321",
        "451843816484372480": "754098964390740016",
        "480435337303425025": "754098970627670056",
        "484796812851413012": "754098976092848220",
        "493698045465067530": "754098971881898206"
    },
    "loaders": [
        "386861188891279362"
    ]
}

Loader Events `WS /loaders/ws`

Receive live updates about currently running loaders. Loaders can both be templates or backups. Listening for the “done” event could be useful to restore server specific settings automatically after a backup / template was loaded. The content of the event may differ but will always include enough information to query the id mapper.

There are three types of events: start (a loader was started), status (loader status updated), done (loader has finished). Status updates are limited to 1/5s/loader, so it’s not guaranteed that you receive all status events. The status strings (e.g. “loading roles”) are internal values and might change at any time. You should always receive the “start” and “done” events.

The Authorization header must be sent with the initiating HTTP request.

Query Parameters

This endpoint doesn’t accept query parameters.

WS Send

The websocket doesn’t require you to send any information.

WS Receive

Key

Description

Always Returned

event

The loader event ("start", "done" or "status")

yes

data

Key	Description	Always Returned
id	The guild-id where the loader is running	yes
type	The type of the loader ("backup" or "template")	in "start" & "done"
user_id	The id of the user that is loading the backup or template)	in "start" & "done"
source_id	The guild-id where the template / backup was created	in "start" & "done"
backup_id	The backup-id that is being loaded	if type = "backup"
template_id	The template-id that is being loaded	if type = "template"
status	The loader status	in "status"

yes

Example

Url WS /loaders/ws

WS Send

{}

WS Receive

{
  "event": "start",
  "data": {
    "id": "756891586859892777",
    "type": "backup",
    "user_id": "386861188891279362",
    "source_id": "670235515903279105",
    "backup_id": "3zydfwqp0h"
  }
}

{
  "event": "status",
  "data": {
    "id": "756891586859892777",
    "status": "deleting roles"
  }
}

{
  "event": "status",
  "data": {
    "id": "756891586859892777",
    "status": "deleting channels"
  }
}

{
  "event": "status",
  "data": {
    "id": "756891586859892777",
    "status": "loading roles"
  }
}

{
  "event": "status",
  "data": {
    "id": "756891586859892777",
    "status": "loading channels"
  }
}

{
  "event": "done",
  "data": {
    "id": "756891586859892777",
    "type": "backup",
    "user_id": "386861188891279362",
    "source_id": "670235515903279105",
    "backup_id": "3zydfwqp0h"
  }
}

Attach bot to templates `POST /templates/{template_id}/bots`

Add your bot to the list of bots that include settings for that template. This will make your bot show up on the template details page and should only be used if you are able to restore bot settings for that template.

This can work by both listening to the DONE loader event (for servers that your bot is already on) and by providing a command for users that add your bot after loading the template.

Query Parameters

This endpoint doesn’t accept query parameters.

JSON Body

Key	Description	Required	Default
user	ID of the user that your bot is acting in behalf of. (e.g. the user that ran the command) This can be used as a simple permission check and has to match the template creator.	no	-

JSON Response

Empty json object on success.

Example

Url POST /templates/hHGhNE6wyxgF/bots

JSON Body

{"user": "647737109494497281"}

JSON Response

{}

Detach bot from templates `DELETE /templates/{template_id}/bots`

Delete your bot from the list of bots that include settings for that template. Same behavior as POST /templates/{template_id}/bots.

API

Intro

API Reference

Rate Limits

Caching

Authentication

Endpoints

ID Mappers GET /mappers

Query Parameters

JSON Body

JSON Response

Example

Loader Events WS /loaders/ws

Query Parameters

WS Send

WS Receive

Example

Attach bot to templates POST /templates/{template_id}/bots

Query Parameters

JSON Body

JSON Response

Example

Detach bot from templates DELETE /templates/{template_id}/bots

ID Mappers `GET /mappers`

Loader Events `WS /loaders/ws`

Attach bot to templates `POST /templates/{template_id}/bots`

Detach bot from templates `DELETE /templates/{template_id}/bots`