Omniplex Docs

Bots

These API endpoints are related to bots on Omniplex

Put bot asset version

PUT
/bots/{id}/assets/{kind}

Records the content version of a bot asset (avatar/banner) that was just uploaded to the CDN, so it is returned in the entity's asset_versions.

The file itself is uploaded through the frontend's upload gateway, not here. Returns a 204 on success.

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

The bot's ID

kind*string

The asset kind: banner, or avatar for teams

Request Body

application/json
  1. body
version?string

Lowercase hex prefix (16 to 64 chars) of the uploaded file's SHA-256

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X PUT 'https://spider.omniplex.gg/bots/string/assets/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}

Get bot page style

GET
/bots/{id}/page-style

The custom background, gradient and accent colour shown on the bot's page. Only approved backgrounds are returned, and nothing is returned unless the bot has premium. Returns null when the page isn't customised.

Path Parameters

id*string

The bot's ID

Response Body

Success

application/json
  1. response
accent?string

The page's accent colour as #rrggbb, or null for the viewer's own accent

blur?integer

Background blur in pixels, 0 to 24

dim?integer

How much the background is darkened or lightened toward the page colour, 30 to 90 percent

fixed?boolean

Whether the background stays put while the page scrolls

gradient?string

A preset gradient ID, custom:#rrggbb:#rrggbb for a custom two-colour gradient, or null

image_position?string

top, center or bottom

image_version?string

The approved background image's version. The image is at {CDN}/backgrounds/{bots|servers}/{id}/{version}.webp

Example Request
curl -X GET 'https://spider.omniplex.gg/bots/string/page-style'
Example Response
{  "accent": "string",  "blur": 0,  "dim": 0,  "fixed": true,  "gradient": "string",  "image_position": "string",  "image_version": "string"}

Update bot page style

PATCH
/bots/{id}/page-style

Sets the gradient, accent colour and how the background image is shown, or removes the image with remove_image. Needs premium. The accent colour has to be readable on both light and dark mode.

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

The bot's ID

Request Body

application/json
  1. body
accent?string
blur?integer
dim?integer
fixed?boolean
gradient?string
image_position?string
Value in"top""center""bottom"
remove_image?boolean

Remove the background image, including one waiting for review

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X PATCH 'https://spider.omniplex.gg/bots/string/page-style' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}
GET
/bots/{id}/page-style/manage

The page style with everything an owner needs to edit it: a background waiting for review, why the last one was rejected, and whether the bot has premium.

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

The bot's ID

Response Body

Success

application/json
  1. response
accent?string

The page's accent colour as #rrggbb, or null for the viewer's own accent

blur?integer

Background blur in pixels, 0 to 24

dim?integer

How much the background is darkened or lightened toward the page colour, 30 to 90 percent

fixed?boolean

Whether the background stays put while the page scrolls

gradient?string

A preset gradient ID, custom:#rrggbb:#rrggbb for a custom two-colour gradient, or null

image_position?string

top, center or bottom

image_version?string

The approved background image's version. The image is at {CDN}/backgrounds/{bots|servers}/{id}/{version}.webp

pending_since?string

When the pending background was uploaded

Formatdate-time
pending_version?string

An uploaded background waiting for staff review

premium?boolean

Whether page styles are available: the listing has premium or an active Page Style pass. Page styles only show while they are

rejected_reason?string

Why staff rejected the last uploaded background

unlocked_until?string

When the listing's Page Style pass from the Credit shop runs out, if one is active

Formatdate-time
Example Request
curl -X GET 'https://spider.omniplex.gg/bots/string/page-style/manage'
Example Response
{  "accent": "string",  "blur": 0,  "dim": 0,  "fixed": true,  "gradient": "string",  "image_position": "string",  "image_version": "string",  "pending_since": "2019-08-24T14:15:22Z",  "pending_version": "string",  "premium": true,  "rejected_reason": "string",  "unlocked_until": "2019-08-24T14:15:22Z"}
PUT
/bots/{id}/page-style/image

Records a background image that was just uploaded through the website's upload gateway, which re-encodes it. It waits for staff review before it shows on the page. Needs premium.

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

The bot's ID

Request Body

application/json
  1. body
version?string

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X PUT 'https://spider.omniplex.gg/bots/string/page-style/image' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}

Set bot card colour

PUT
/bots/{id}/card-color

Sets the colour that tints the bot's card, or resets it with an empty colour. Needs the Card Theme from the shop. Returns 204 on success.

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

The bot's ID

Request Body

application/json
  1. body
color?string

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X PUT 'https://spider.omniplex.gg/bots/string/card-color' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}

Record bot View

POST
/bots/{id}/views

Records that a visitor opened this bot's page. Each visitor counts once per bot per day. Known crawlers, and people who manage the bot, aren't counted. Signing in is optional. Always returns 204.

Authorization

User
headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

The bot's ID

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X POST 'https://spider.omniplex.gg/bots/string/views'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}

Record bot Invite Click

POST
/bots/{id}/invite-clicks

Records that a visitor opened this bot's invite. Each visitor counts once per bot per day. Known crawlers, and people who manage the bot, aren't counted. Signing in is optional. Always returns 204.

Authorization

User
headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

The bot's ID

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X POST 'https://spider.omniplex.gg/bots/string/invite-clicks'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}

Get All Bots

GET
/bots/@all

Gets approved and certified bots, filtered and sorted. Returns a set of paginated IndexBot objects

Query Parameters

page?string

The page number

sort?string

Sort order: new (default; newest first, with boosted listings on top), trending (net votes in the last 7 days, only bots with at least one vote in that window), votes (most votes this cycle) or servers (highest server count).

tag?string

Only bots with this tag (case-insensitive).

certified?string

true to only return certified bots.

Response Body

Success

application/json
  1. response
count?integer
Range0 <= value <= 18446744073709552000
per_page?integer
Range0 <= value <= 18446744073709552000
results?array<>
Example Request
curl -X GET 'https://spider.omniplex.gg/bots/@all'
Example Response
{  "count": 0,  "per_page": 0,  "results": [    {      "approximate_votes": 0,      "asset_versions": {        "property1": "string",        "property2": "string"      },      "boosted_until": "2019-08-24T14:15:22Z",      "bot_id": "string",      "card_color": "string",      "clicks": 0,      "created_at": "2019-08-24T14:15:22Z",      "featured_until": "2019-08-24T14:15:22Z",      "hidden_stats": [        "string"      ],      "highlighted": true,      "invite_clicks": 0,      "library": "string",      "nsfw": true,      "premium": true,      "servers": 0,      "shards": 0,      "short": "string",      "spotlighted_until": "2019-08-24T14:15:22Z",      "supporter_badge": true,      "tags": [        "string"      ],      "type": "string",      "user": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "vanity": "string",      "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",      "views_30d": 0,      "vote_blitz_until": "2019-08-24T14:15:22Z",      "votes": 0    }  ]}

Get Random Bots

GET
/bots/@random

Returns a list of bots from the database in random order

Response Body

Success

application/json
  1. response
bots?array<>
Example Request
curl -X GET 'https://spider.omniplex.gg/bots/@random'
Example Response
{  "bots": [    {      "approximate_votes": 0,      "asset_versions": {        "property1": "string",        "property2": "string"      },      "boosted_until": "2019-08-24T14:15:22Z",      "bot_id": "string",      "card_color": "string",      "clicks": 0,      "created_at": "2019-08-24T14:15:22Z",      "featured_until": "2019-08-24T14:15:22Z",      "hidden_stats": [        "string"      ],      "highlighted": true,      "invite_clicks": 0,      "library": "string",      "nsfw": true,      "premium": true,      "servers": 0,      "shards": 0,      "short": "string",      "spotlighted_until": "2019-08-24T14:15:22Z",      "supporter_badge": true,      "tags": [        "string"      ],      "type": "string",      "user": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "vanity": "string",      "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",      "views_30d": 0,      "vote_blitz_until": "2019-08-24T14:15:22Z",      "votes": 0    }  ]}

Get Bots Index

GET
/bots/@index

Gets the index of the bot-side of the list. Returns a ListIndexBot object

Response Body

Success

application/json
  1. response
certified?array<>

The certified bots

featured?array<>

Bots with an active featured_until from a shop purchase

most_viewed?array<>

The most viewed bots

packs?array<>

The bot packs

premium?array<>

The premium bots

recently_added?array<>

The recently added bots

spotlight?array<>

Bots with an active spotlighted_until, set by staff

top_voted?array<>

The top voted bots

Example Request
curl -X GET 'https://spider.omniplex.gg/bots/@index'
Example Response
{  "certified": [    {      "approximate_votes": 0,      "asset_versions": {        "property1": "string",        "property2": "string"      },      "boosted_until": "2019-08-24T14:15:22Z",      "bot_id": "string",      "card_color": "string",      "clicks": 0,      "created_at": "2019-08-24T14:15:22Z",      "featured_until": "2019-08-24T14:15:22Z",      "hidden_stats": [        "string"      ],      "highlighted": true,      "invite_clicks": 0,      "library": "string",      "nsfw": true,      "premium": true,      "servers": 0,      "shards": 0,      "short": "string",      "spotlighted_until": "2019-08-24T14:15:22Z",      "supporter_badge": true,      "tags": [        "string"      ],      "type": "string",      "user": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "vanity": "string",      "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",      "views_30d": 0,      "vote_blitz_until": "2019-08-24T14:15:22Z",      "votes": 0    }  ],  "featured": [    {      "approximate_votes": 0,      "asset_versions": {        "property1": "string",        "property2": "string"      },      "boosted_until": "2019-08-24T14:15:22Z",      "bot_id": "string",      "card_color": "string",      "clicks": 0,      "created_at": "2019-08-24T14:15:22Z",      "featured_until": "2019-08-24T14:15:22Z",      "hidden_stats": [        "string"      ],      "highlighted": true,      "invite_clicks": 0,      "library": "string",      "nsfw": true,      "premium": true,      "servers": 0,      "shards": 0,      "short": "string",      "spotlighted_until": "2019-08-24T14:15:22Z",      "supporter_badge": true,      "tags": [        "string"      ],      "type": "string",      "user": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "vanity": "string",      "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",      "views_30d": 0,      "vote_blitz_until": "2019-08-24T14:15:22Z",      "votes": 0    }  ],  "most_viewed": [    {      "approximate_votes": 0,      "asset_versions": {        "property1": "string",        "property2": "string"      },      "boosted_until": "2019-08-24T14:15:22Z",      "bot_id": "string",      "card_color": "string",      "clicks": 0,      "created_at": "2019-08-24T14:15:22Z",      "featured_until": "2019-08-24T14:15:22Z",      "hidden_stats": [        "string"      ],      "highlighted": true,      "invite_clicks": 0,      "library": "string",      "nsfw": true,      "premium": true,      "servers": 0,      "shards": 0,      "short": "string",      "spotlighted_until": "2019-08-24T14:15:22Z",      "supporter_badge": true,      "tags": [        "string"      ],      "type": "string",      "user": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "vanity": "string",      "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",      "views_30d": 0,      "vote_blitz_until": "2019-08-24T14:15:22Z",      "votes": 0    }  ],  "packs": [    {      "bot_ids": [        "string"      ],      "bots": [        {          "approximate_votes": 0,          "asset_versions": {            "property1": "string",            "property2": "string"          },          "boosted_until": "2019-08-24T14:15:22Z",          "bot_id": "string",          "card_color": "string",          "clicks": 0,          "created_at": "2019-08-24T14:15:22Z",          "featured_until": "2019-08-24T14:15:22Z",          "hidden_stats": [            "string"          ],          "highlighted": true,          "invite_clicks": 0,          "library": "string",          "nsfw": true,          "premium": true,          "servers": 0,          "shards": 0,          "short": "string",          "spotlighted_until": "2019-08-24T14:15:22Z",          "supporter_badge": true,          "tags": [            "string"          ],          "type": "string",          "user": {            "avatar": "string",            "bot": true,            "display_name": "string",            "extra_data": {              "property1": null,              "property2": null            },            "flags": [              "string"            ],            "id": "string",            "status": "string",            "username": "string"          },          "vanity": "string",          "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",          "views_30d": 0,          "vote_blitz_until": "2019-08-24T14:15:22Z",          "votes": 0        }      ],      "created_at": "2019-08-24T14:15:22Z",      "emojis": [        {          "animated": true,          "downloads": 0,          "id": "string",          "name": "string",          "position": 0,          "vanity": "string"        }      ],      "name": "string",      "owner": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "pack_type": "string",      "server_ids": [        "string"      ],      "servers": [        {          "approximate_votes": 0,          "asset_versions": {            "property1": "string",            "property2": "string"          },          "avatar": "string",          "boosted_until": "2019-08-24T14:15:22Z",          "card_color": "string",          "clicks": 0,          "featured_until": "2019-08-24T14:15:22Z",          "hidden_stats": [            "string"          ],          "highlighted": true,          "invite_clicks": 0,          "name": "string",          "nsfw": true,          "online_members": 0,          "premium": true,          "server_id": "string",          "short": "string",          "spotlighted_until": "2019-08-24T14:15:22Z",          "state": "string",          "supporter_badge": true,          "tags": [            "string"          ],          "total_members": 0,          "type": "string",          "vanity": "string",          "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",          "views_30d": 0,          "votes": 0        }      ],      "short": "string",      "sounds": [        {          "downloads": 0,          "duration_ms": 0,          "id": "string",          "name": "string",          "position": 0,          "vanity": "string"        }      ],      "stickers": [        {          "animated": true,          "downloads": 0,          "id": "string",          "name": "string",          "position": 0,          "vanity": "string"        }      ],      "tags": [        "string"      ],      "url": "string",      "vote_banned": true,      "votes": 0    }  ],  "premium": [    {      "approximate_votes": 0,      "asset_versions": {        "property1": "string",        "property2": "string"      },      "boosted_until": "2019-08-24T14:15:22Z",      "bot_id": "string",      "card_color": "string",      "clicks": 0,      "created_at": "2019-08-24T14:15:22Z",      "featured_until": "2019-08-24T14:15:22Z",      "hidden_stats": [        "string"      ],      "highlighted": true,      "invite_clicks": 0,      "library": "string",      "nsfw": true,      "premium": true,      "servers": 0,      "shards": 0,      "short": "string",      "spotlighted_until": "2019-08-24T14:15:22Z",      "supporter_badge": true,      "tags": [        "string"      ],      "type": "string",      "user": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "vanity": "string",      "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",      "views_30d": 0,      "vote_blitz_until": "2019-08-24T14:15:22Z",      "votes": 0    }  ],  "recently_added": [    {      "approximate_votes": 0,      "asset_versions": {        "property1": "string",        "property2": "string"      },      "boosted_until": "2019-08-24T14:15:22Z",      "bot_id": "string",      "card_color": "string",      "clicks": 0,      "created_at": "2019-08-24T14:15:22Z",      "featured_until": "2019-08-24T14:15:22Z",      "hidden_stats": [        "string"      ],      "highlighted": true,      "invite_clicks": 0,      "library": "string",      "nsfw": true,      "premium": true,      "servers": 0,      "shards": 0,      "short": "string",      "spotlighted_until": "2019-08-24T14:15:22Z",      "supporter_badge": true,      "tags": [        "string"      ],      "type": "string",      "user": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "vanity": "string",      "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",      "views_30d": 0,      "vote_blitz_until": "2019-08-24T14:15:22Z",      "votes": 0    }  ],  "spotlight": [    {      "approximate_votes": 0,      "asset_versions": {        "property1": "string",        "property2": "string"      },      "boosted_until": "2019-08-24T14:15:22Z",      "bot_id": "string",      "card_color": "string",      "clicks": 0,      "created_at": "2019-08-24T14:15:22Z",      "featured_until": "2019-08-24T14:15:22Z",      "hidden_stats": [        "string"      ],      "highlighted": true,      "invite_clicks": 0,      "library": "string",      "nsfw": true,      "premium": true,      "servers": 0,      "shards": 0,      "short": "string",      "spotlighted_until": "2019-08-24T14:15:22Z",      "supporter_badge": true,      "tags": [        "string"      ],      "type": "string",      "user": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "vanity": "string",      "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",      "views_30d": 0,      "vote_blitz_until": "2019-08-24T14:15:22Z",      "votes": 0    }  ],  "top_voted": [    {      "approximate_votes": 0,      "asset_versions": {        "property1": "string",        "property2": "string"      },      "boosted_until": "2019-08-24T14:15:22Z",      "bot_id": "string",      "card_color": "string",      "clicks": 0,      "created_at": "2019-08-24T14:15:22Z",      "featured_until": "2019-08-24T14:15:22Z",      "hidden_stats": [        "string"      ],      "highlighted": true,      "invite_clicks": 0,      "library": "string",      "nsfw": true,      "premium": true,      "servers": 0,      "shards": 0,      "short": "string",      "spotlighted_until": "2019-08-24T14:15:22Z",      "supporter_badge": true,      "tags": [        "string"      ],      "type": "string",      "user": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "vanity": "string",      "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",      "views_30d": 0,      "vote_blitz_until": "2019-08-24T14:15:22Z",      "votes": 0    }  ]}

Get Bot Changelogs Feed

GET
/bots/@changelogs

A chronological, sitewide feed of changelog entries from approved and certified bots, newest first.

Query Parameters

page?string

The page number

q?string

Search the title, content and bot name (up to 100 characters)

tag?string

Only bots with this tag (case-insensitive)

bot?string

Only this bot's entries (bot ID)

Response Body

Success

application/json
  1. response
count?integer
Range0 <= value <= 18446744073709552000
per_page?integer
Range0 <= value <= 18446744073709552000
results?array<>
Example Request
curl -X GET 'https://spider.omniplex.gg/bots/@changelogs'
Example Response
{  "count": 0,  "per_page": 0,  "results": [    {      "bot_id": "string",      "content": "string",      "created_at": "2019-08-24T14:15:22Z",      "id": "string",      "title": "string",      "user": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "version": "string"    }  ]}
GET
/bots/@changelogs/recent

The approved and certified bots that most recently posted a changelog entry, newest first.

Response Body

Success

application/json
  1. response
[index: integer]?
Example Request
curl -X GET 'https://spider.omniplex.gg/bots/@changelogs/recent'
Example Response
[  {    "bot_id": "string",    "latest_at": "2019-08-24T14:15:22Z",    "updates": 0,    "user": {      "avatar": "string",      "bot": true,      "display_name": "string",      "extra_data": {        "property1": null,        "property2": null      },      "flags": [        "string"      ],      "id": "string",      "status": "string",      "username": "string"    }  }]

Search Bot Commands

GET
/bots/@commands

Cross-bot command search across approved and certified bots. Matches command names and descriptions; at least one of query, bot or tag is required.

Query Parameters

query?string

Text to find in command names and descriptions (up to 100 characters, matched literally)

bot?string

Only this bot's commands (bot ID)

tag?string

Only bots with this tag (case-insensitive)

page?string

The page number

Response Body

Success

application/json
  1. response
count?integer
Range0 <= value <= 18446744073709552000
per_page?integer
Range0 <= value <= 18446744073709552000
results?array<>
Example Request
curl -X GET 'https://spider.omniplex.gg/bots/@commands'
Example Response
{  "count": 0,  "per_page": 0,  "results": [    {      "bot": {        "avatar": "string",        "bot": true,        "display_name": "string",        "extra_data": {          "property1": null,          "property2": null        },        "flags": [          "string"        ],        "id": "string",        "status": "string",        "username": "string"      },      "bot_id": "string",      "category": "string",      "description": "string",      "id": "string",      "name": "string",      "usage": "string"    }  ]}
GET
/bots/@commands/bots

Approved and certified bots that have documented commands, most-voted first, with their command count and a preview of command names.

Response Body

Success

application/json
  1. response
[index: integer]?
Example Request
curl -X GET 'https://spider.omniplex.gg/bots/@commands/bots'
Example Response
[  {    "bot_id": "string",    "commands": 0,    "preview": [      "string"    ],    "user": {      "avatar": "string",      "bot": true,      "display_name": "string",      "extra_data": {        "property1": null,        "property2": null      },      "flags": [        "string"      ],      "id": "string",      "status": "string",      "username": "string"    }  }]

Get Bot

GET
/bots/{id}

Gets a bot by id

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

The bots ID

Query Parameters

target?string

No longer used. Views and invite clicks are recorded with POST /bots/{id}/views and POST /bots/{id}/invite-clicks.

include?string

What extra fields to include, comma-seperated.long => bot long description

team_includes?string

If the bot is team-owned, what entities of the team to include

Response Body

Success

application/json
  1. response
approval_note?string

The note for the bot's approval

approximate_votes?integer

The bot's approximate vote count, used for home page listing etc.

asset_versions?

Content versions of uploaded CDN assets by kind (avatar/banner). Append as ?v= to the asset URL. A missing kind means unknown, not absent

auto_votes?integer

How many of this month's upvotes came from Auto-vote

auto_votes_opt_out?boolean

Whether the bot refuses automatic votes from auto-vote subscribers

boosted_until?string

If set and in the future, the bot gets priority placement in listings until this time

Formatdate-time
bot_id?string

The bot's ID

captcha_opt_out?boolean

Whether the bot should have captchas shown if the user has captcha_sponsor_enabled

card_color?string

The bot's Card Theme colour as #rrggbb, empty when it has no Card Theme or no colour set

card_theme?boolean

Whether the bot has bought the Card Theme, which unlocks card_color

cert_reason?string

The reason for the bot being certified

claimed_by?string

The user who claimed the bot

clicks?integer

The bot's total click count

client_id?string

The bot's associated client ID validated using that top-secret Oauth2 API! Used in anti-abuse measures.

created_at?string

The bot's creation date

Formatdate-time
extra_links?array<>

The bot's links that it wishes to advertise

featured_until?string

If set and in the future, the bot appears in the home page's Featured section until this time

Formatdate-time
hidden_stats?array<>

Stats the owner chose to hide. Hidden stats are returned as zero unless you manage this listing

highlighted?boolean

Whether the bot has an active Highlighted Card from the shop

highlighted_until?string

If set and in the future, the bot's card has an accent glow until this time

Formatdate-time
invite?string

The bot's invite URL. Must be present

invite_clicks?integer

The bot's invite click count (via users inviting the bot from IBL)

itag?string

The bot's internal ID. An artifact of database migrations.

Formatuuid
last_claimed?string

The bot's last claimed date

Formatdate-time
last_japi_update?string

The last time the bot was updated via JAPI

Formatdate-time
last_stats_post?string

The list time the bot posted stats to the list. Null if never posted

Formatdate-time
library?string

The bot's library

long?string

The bot's long description in raw format (HTML/markdown etc. based on the bots settings). May not always be present (e.g. 'long' not in include)

moderation_categories?array<>

Which moderation categories were flagged (e.g. sexual, harassment), empty if not flagged or moderation wasn't run

moderation_flagged?boolean

Whether OpenAI's moderation endpoint flagged the bot's short/long description at submission time. A signal for reviewers, not a verdict

nsfw?boolean

Whether the bot is NSFW or not

owner?

The bot owner's user information. If in a team, this will be null and team_owner will instead be set

prefix?string

The bot's prefix

premium?boolean

Whether the bot is a premium bot or not

premium_period_length?integer

The period of premium for the bot in nanoseconds

Formatint64
servers?integer

The bot's server count

shard_list?array<>

The number of servers per shard

shards?integer

The bot's shard count

short?string

The bot's short description

spotlighted_until?string

If set and in the future, the bot appears in the home page's Spotlight section until this time

Formatdate-time
start_premium_period?string
Formatdate-time
supporter_badge?boolean

Whether the bot's owner has purchased the cosmetic supporter badge from the shop

tags?array<>

The bot's tags (e.g. music, moderation, etc.)

team_owner?

If the bot is in a team, who owns the bot. If not in a team, this will be null and owner will instead be set

total_uptime?integer

The bot's all-time number of uptime checks. Includes older checks that weren't reliable, so use uptime_percent to show uptime

type?string

The bot's type (e.g. pending/approved/certified/denied etc.). Note that we do not filter out denied/banned bots in API

unique_clicks?integer

The bot's unique click count based on SHA256 hashed IPs

Formatint64
updated_at?string

The bot's last update date

Formatdate-time
uptime?integer

The bot's all-time number of successful uptime checks. Includes older checks that weren't reliable, so use uptime_percent to show uptime

uptime_checks?integer

How many uptime checks ran in the last 30 days

uptime_last_checked?string

The bot's last uptime check

Formatdate-time
uptime_percent?number

The share of uptime checks in the last 30 days where the bot was online, from 0 to 100. Null when it hasn't been seen online in that time

Formatdouble
user?

The bot's user information

users?integer

The bot's user count

vanity?string

The bot's vanity URL

vanity_ref?string

The corresponding vanities itag, this also works to ensure that all bots have an associated vanity

Formatuuid
views_30d?integer

Views in the last 30 days, counting each visitor once per listing per day

vote_banned?boolean

Whether the bot is vote banned or not

vote_blitz_until?string

If set and in the future, the bot's vote cooldown is halved until this time

Formatdate-time
votes?integer

The bot's vote count

Example Request
curl -X GET 'https://spider.omniplex.gg/bots/string'
Example Response
{  "approval_note": "string",  "approximate_votes": 0,  "asset_versions": {    "property1": "string",    "property2": "string"  },  "auto_votes": 0,  "auto_votes_opt_out": true,  "boosted_until": "2019-08-24T14:15:22Z",  "bot_id": "string",  "captcha_opt_out": true,  "card_color": "string",  "card_theme": true,  "cert_reason": "string",  "claimed_by": "string",  "clicks": 0,  "client_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "extra_links": [    {      "name": "string",      "value": "string"    }  ],  "featured_until": "2019-08-24T14:15:22Z",  "hidden_stats": [    "string"  ],  "highlighted": true,  "highlighted_until": "2019-08-24T14:15:22Z",  "invite": "string",  "invite_clicks": 0,  "itag": "6b5f8e7b-1e8c-4611-b693-ee8faa950c62",  "last_claimed": "2019-08-24T14:15:22Z",  "last_japi_update": "2019-08-24T14:15:22Z",  "last_stats_post": "2019-08-24T14:15:22Z",  "library": "string",  "long": "string",  "moderation_categories": [    "string"  ],  "moderation_flagged": true,  "nsfw": true,  "owner": {    "avatar": "string",    "bot": true,    "display_name": "string",    "extra_data": {      "property1": null,      "property2": null    },    "flags": [      "string"    ],    "id": "string",    "status": "string",    "username": "string"  },  "prefix": "string",  "premium": true,  "premium_period_length": 0,  "servers": 0,  "shard_list": [    0  ],  "shards": 0,  "short": "string",  "spotlighted_until": "2019-08-24T14:15:22Z",  "start_premium_period": "2019-08-24T14:15:22Z",  "supporter_badge": true,  "tags": [    "string"  ],  "team_owner": {    "approximate_votes": 0,    "asset_versions": {      "property1": "string",      "property2": "string"    },    "created_at": "2019-08-24T14:15:22Z",    "entities": {      "bots": [        {          "approximate_votes": 0,          "asset_versions": {            "property1": "string",            "property2": "string"          },          "boosted_until": "2019-08-24T14:15:22Z",          "bot_id": "string",          "card_color": "string",          "clicks": 0,          "created_at": "2019-08-24T14:15:22Z",          "featured_until": "2019-08-24T14:15:22Z",          "hidden_stats": [            "string"          ],          "highlighted": true,          "invite_clicks": 0,          "library": "string",          "nsfw": true,          "premium": true,          "servers": 0,          "shards": 0,          "short": "string",          "spotlighted_until": "2019-08-24T14:15:22Z",          "supporter_badge": true,          "tags": [            "string"          ],          "type": "string",          "user": {            "avatar": "string",            "bot": true,            "display_name": "string",            "extra_data": {              "property1": null,              "property2": null            },            "flags": [              "string"            ],            "id": "string",            "status": "string",            "username": "string"          },          "vanity": "string",          "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",          "views_30d": 0,          "vote_blitz_until": "2019-08-24T14:15:22Z",          "votes": 0        }      ],      "members": [        {          "created_at": "2019-08-24T14:15:22Z",          "data_holder": true,          "flags": [            "string"          ],          "itag": "6b5f8e7b-1e8c-4611-b693-ee8faa950c62",          "mentionable": true,          "service": "string",          "team_id": "string",          "user": {            "avatar": "string",            "bot": true,            "display_name": "string",            "extra_data": {              "property1": null,              "property2": null            },            "flags": [              "string"            ],            "id": "string",            "status": "string",            "username": "string"          }        }      ],      "servers": [        {          "approximate_votes": 0,          "asset_versions": {            "property1": "string",            "property2": "string"          },          "avatar": "string",          "boosted_until": "2019-08-24T14:15:22Z",          "card_color": "string",          "clicks": 0,          "featured_until": "2019-08-24T14:15:22Z",          "hidden_stats": [            "string"          ],          "highlighted": true,          "invite_clicks": 0,          "name": "string",          "nsfw": true,          "online_members": 0,          "premium": true,          "server_id": "string",          "short": "string",          "spotlighted_until": "2019-08-24T14:15:22Z",          "state": "string",          "supporter_badge": true,          "tags": [            "string"          ],          "total_members": 0,          "type": "string",          "vanity": "string",          "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",          "views_30d": 0,          "votes": 0        }      ],      "targets": [        "string"      ]    },    "extra_links": [      {        "name": "string",        "value": "string"      }    ],    "id": "string",    "name": "string",    "nsfw": true,    "service": "string",    "short": "string",    "tags": [      "string"    ],    "updated_at": "2019-08-24T14:15:22Z",    "vanity": "string",    "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",    "vote_banned": true,    "votes": 0  },  "total_uptime": 0,  "type": "string",  "unique_clicks": 0,  "updated_at": "2019-08-24T14:15:22Z",  "uptime": 0,  "uptime_checks": 0,  "uptime_last_checked": "2019-08-24T14:15:22Z",  "uptime_percent": 0.1,  "user": {    "avatar": "string",    "bot": true,    "display_name": "string",    "extra_data": {      "property1": null,      "property2": null    },    "flags": [      "string"    ],    "id": "string",    "status": "string",    "username": "string"  },  "users": 0,  "vanity": "string",  "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",  "views_30d": 0,  "vote_banned": true,  "vote_blitz_until": "2019-08-24T14:15:22Z",  "votes": 0}

Delete Bot

DELETE
/bots/{id}

Deletes a bot from the list. This is irreversible. You must have 'Delete Bots' in the team if the bot is in a team. Returns 204 on success.

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

Bot ID

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X DELETE 'https://spider.omniplex.gg/bots/string'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}

Get Bot Metadata

GET
/bots/{client_id}/meta

Gets the metadata of a bot such as whether it is already in the database/bot id checks

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

client_id*string

The client ID

Query Parameters

fallback_bot_id?string

The fallback bot ID to use if japi.rest is offline

Response Body

Success

application/json
  1. response
avatar?string

The bot's avatar

bot_id?string

The bot's ID

bot_public?boolean

Whether or not the bot is public

client_id?string

The bot's client ID

description?string

The suggested description for the bot

fallback?boolean

Whether or not we had to fall back to JAPI.rest from Discord's own RPC endpoint

fetch_errors?

The errors that occurred when fetching the bot

flags?array<>

The bot's flags

guild_count?integer

The bot's guild count

list_type?string

If this is empty, then it is not on the list

name?string

The bot's name

tags?array<>

The suggested tags for the bot

Example Request
curl -X GET 'https://spider.omniplex.gg/bots/string/meta'
Example Response
{  "avatar": "string",  "bot_id": "string",  "bot_public": true,  "client_id": "string",  "description": "string",  "fallback": true,  "fetch_errors": {    "property1": "string",    "property2": "string"  },  "flags": [    "string"  ],  "guild_count": 0,  "list_type": "string",  "name": "string",  "tags": [    "string"  ]}

Get Bot Analytics

GET
/bots/{id}/analytics

Returns the bot's daily votes, views, invite clicks and counts over time. You must have 'Edit Bots' in the bot's team.

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

The bot's ID

Query Parameters

days?string

How many days to return, ending today (UTC). Between 7 and 365, defaults to 30.

Response Body

Success

application/json
  1. response
days?array<>

One entry per day, oldest first, ending today (UTC)

tracked_since?string

The first day views, invite clicks and counts were recorded, null if not yet. Votes are available for the whole range.

Example Request
curl -X GET 'https://spider.omniplex.gg/bots/string/analytics'
Example Response
{  "days": [    {      "auto_votes": 0,      "day": "string",      "invite_clicks": 0,      "online_members": 0,      "servers": 0,      "total_members": 0,      "users": 0,      "views": 0,      "votes": 0    }  ],  "tracked_since": "string"}

Get Bot SEO Info

GET
/bots/{id}/seo

Gets the minimal SEO information about a bot for embed/search purposes. Used by v4 website for meta tags

Path Parameters

id*string

The bots ID

Response Body

Success

application/json
  1. response
avatar?string

The entities resolved avatar URL (not just hash)

id?string

ID of the entity

name?string

Name of the entity

short?string

Short description of the entity

vanity?string

The entity's vanity code, used to build its canonical URL. Omitted when it has none

Example Request
curl -X GET 'https://spider.omniplex.gg/bots/string/seo'
Example Response
{  "avatar": "string",  "id": "string",  "name": "string",  "short": "string",  "vanity": "string"}

Get Similar Bots

GET
/bots/{id}/similar

Returns up to 6 other approved/certified bots sharing at least one tag with this bot (case-insensitive), ranked by shared tags with rarer tags weighted higher, then votes. NSFW bots are only included when this bot is NSFW.

Path Parameters

id*string

Bot ID

Response Body

Success

application/json
  1. response
[index: integer]?
Example Request
curl -X GET 'https://spider.omniplex.gg/bots/string/similar'
Example Response
[  {    "approximate_votes": 0,    "asset_versions": {      "property1": "string",      "property2": "string"    },    "boosted_until": "2019-08-24T14:15:22Z",    "bot_id": "string",    "card_color": "string",    "clicks": 0,    "created_at": "2019-08-24T14:15:22Z",    "featured_until": "2019-08-24T14:15:22Z",    "hidden_stats": [      "string"    ],    "highlighted": true,    "invite_clicks": 0,    "library": "string",    "nsfw": true,    "premium": true,    "servers": 0,    "shards": 0,    "short": "string",    "spotlighted_until": "2019-08-24T14:15:22Z",    "supporter_badge": true,    "tags": [      "string"    ],    "type": "string",    "user": {      "avatar": "string",      "bot": true,      "display_name": "string",      "extra_data": {        "property1": null,        "property2": null      },      "flags": [        "string"      ],      "id": "string",      "status": "string",      "username": "string"    },    "vanity": "string",    "vanity_ref": "e1b95001-3370-4367-9787-1fb904c7b8c7",    "views_30d": 0,    "vote_blitz_until": "2019-08-24T14:15:22Z",    "votes": 0  }]

Post Bot Stats

POST
/bots/stats

This endpoint posts the stats of a bot. status is optional and self-reports the bot's presence (online/idle/dnd/offline) — post it periodically to keep it fresh, it will otherwise keep showing the last value posted.

Authorization

Bot
headerBot-Auth<token>

Requires a bot token. Should be prefixed with Bot in Authorization header.

Request Body

application/json
  1. body
servers?integer

The server count

Range0 <= value <= 18446744073709552000
shard_list?array<>

The shard list

shards?integer

The shard count

Range0 <= value <= 18446744073709552000
status?string
Value in"online""idle""dnd""offline"
users?integer

The user count (not used in webpage)

Range0 <= value <= 18446744073709552000

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X POST 'https://spider.omniplex.gg/bots/stats' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}

Add Bot

PUT
/bots

Adds a bot to the database. Returns 204 on success

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Request Body

application/json
  1. body
bot_id?string
client_id?string
extra_links?array<>
invite?string
library?string
long?string
nsfw?boolean
prefix?string
short?string
staff_note?string
tags?array<string>
team_owner?string

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X PUT 'https://spider.omniplex.gg/bots' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}

Update Bot Settings

PATCH
/bots/{id}/settings

Updates a bots settings. You must have 'Edit Bot Settings' in the team if the bot is in a team. Returns 204 on success

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

Bot ID

Request Body

application/json
  1. body
auto_votes_opt_out?boolean
captcha_opt_out?boolean
card_color?string
extra_links?array<>
hidden_stats?array<>

Stats to hide from public view: servers, shards, uptime (which also hides the online status), views and invites. Leave it out to keep the current choice

invite?string
library?string
long?string
nsfw?boolean
prefix?string
short?string
tags?array<string>

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X PATCH 'https://spider.omniplex.gg/bots/string/settings' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}

Get Bot Commands

GET
/bots/{id}/commands

Gets the commands a bot's owner/team has documented for it.

Authorization

User
headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

Bot ID

Response Body

Success

application/json
  1. response
commands?array<>
Example Request
curl -X GET 'https://spider.omniplex.gg/bots/string/commands'
Example Response
{  "commands": [    {      "category": "string",      "created_at": "2019-08-24T14:15:22Z",      "description": "string",      "id": "string",      "name": "string",      "position": 0,      "updated_at": "2019-08-24T14:15:22Z",      "usage": "string"    }  ]}

Update Bot Commands

PUT
/bots/{id}/commands

Replaces the whole list of documented commands for a bot. You must have 'Edit Bot Settings' in the team if the bot is in a team.

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

Bot ID

Request Body

application/json
  1. body
commands?array<>

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X PUT 'https://spider.omniplex.gg/bots/string/commands' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}

Get Bot Changelogs

GET
/bots/{id}/changelogs

Gets the changelog/announcement entries a bot's owner/team has posted.

Authorization

User
headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

Bot ID

Response Body

Success

application/json
  1. response
changelogs?array<>
Example Request
curl -X GET 'https://spider.omniplex.gg/bots/string/changelogs'
Example Response
{  "changelogs": [    {      "content": "string",      "created_at": "2019-08-24T14:15:22Z",      "created_by": "string",      "id": "string",      "title": "string",      "version": "string"    }  ]}

Create Bot Changelog

POST
/bots/{id}/changelogs

Posts a new changelog/announcement entry for a bot. You must have 'Edit Bot Settings' in the team if the bot is in a team.

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

Bot ID

Request Body

application/json
  1. body
content?string
title?string
version?string

Response Body

Success

application/json
  1. response
content?string
created_at?string
Formatdate-time
created_by?string
id?string
title?string
version?string
Example Request
curl -X POST 'https://spider.omniplex.gg/bots/string/changelogs' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "content": "string",  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "id": "string",  "title": "string",  "version": "string"}

Delete Bot Changelog

DELETE
/bots/{id}/changelogs/{changelog_id}

Removes a changelog/announcement entry. You must have 'Edit Bot Settings' in the team if the bot is in a team.

Authorization

headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

id*string

Bot ID

changelog_id*string

Changelog entry ID

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X DELETE 'https://spider.omniplex.gg/bots/string/changelogs/string'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}

Patch Bot Team

PATCH
/users/{uid}/bots/{bid}/teams

Transfers a bot to another team.

Semantically equivalent to:

  • Remove bot in question from list
  • Readd bot to list with same data
  • Transfer bot ownership to team

The below are the requirements for this due to the above:

  • The user must have the "Delete Bots" permission in the team they are transferring the bot from
  • The user must have the "Add New Bots" permission in the team they are transferring the bot to

The bots ownership will be transferred to the new team.

Returns a 204 on success

Authorization

User
headerUser-Auth<token>

Requires a user token. Should be prefixed with User in Authorization header.

Path Parameters

uid*string

User ID

bid*string

Bot ID

Request Body

application/json
  1. body
team_id?string

The team ID to add the bot to

Response Body

Success

application/json
  1. response
context?

Context of the error. Usually used for validation error contexts

message?string

Message of the error

Example Request
curl -X PATCH 'https://spider.omniplex.gg/users/string/bots/string/teams' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "context": {    "property1": "string",    "property2": "string"  },  "message": "string"}