Skip to content

Rework of some of the sites pages #98

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Rework of some of the sites pages #98

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 29 additions & 7 deletions docs/API/@reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,42 @@ title: 🌟 Getting Started
description: Basics of the API
---

Our API is HTTPS/REST for general operations such as sending `POST` requests and receiving `GET` requests.
## 🔗 Overview

#### Base Url
Top.gg's API is a standard **RESTful** interface using **HTTPS**.
You interact with it via common HTTP verbs like:

[https://top.gg/api](https://top.gg/api)
- `GET` to retrieve data
- `POST` to submit or update data

## Authentication
---

## 🌐 Base URL

To access our API you need to authorize yourself, this can be done by using your discord bot list token. Your token can be obtained from your bot page settings under **Webhooks** (https://top.gg/bot/:yourbotid/webhooks replacing `:yourbotid` with the ID of your bot).
All requests are made to:

```
https://top.gg/api
```

---

Authentication is performed with the `Authorization` HTTP header as such
## 🔐 Authentication

```json:title=HTTP%20Headers
To access the API, you must authenticate with your **bot's API token**.

> You can find your token under your bot's page:
> `https://top.gg/bot/:yourbotid/webhooks`
> *(replace `:yourbotid` with your actual bot ID)*

Include the token in the `Authorization` header:

```json title="HTTP Headers"
{
"Authorization": "your-topgg-token-here"
}
```

---

✅ You're now ready to begin using the Top.gg API. Continue to the [Bots](/docs/API/bot) or [Users](/docs/API/users) sections for full endpoints.
246 changes: 113 additions & 133 deletions docs/API/bot.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,99 +1,79 @@
---
title: Bots
description: API resource for a bots or apps on a platform like Discord
description: API reference for interacting with bots on the platform.
---

import HTTPHeader from "../../src/components/HTTPHeader";

> Bot endpoints are subject to [stricter rate limits](/docs/Resources/ratelimits#resource-specific-ratelimits) than others.
> ⚠️ Bot endpoints are subject to [stricter rate limits](/docs/Resources/ratelimits#resource-specific-ratelimits).

## Search Bots
---

## 🔍 Search Bots

<HTTPHeader type="GET" path="bots" />
<deprecated/>
<deprecated />

Gets a list of bots that match a specific query.
Returns a list of bots matching a query.

### Query String Parameters
### Query Parameters

| Field | Type | Description | Default |
| ------ | -------- | -------------------------------------------------------------- | ---------- |
| limit | `number` | The amount of bots to return. Max. 500 | 50 |
| offset | `number` | Amount of bots to skip | 0 |
| sort | `string` | The field to sort by. Prefix with - to reverse the order | |
| fields | `string` | A comma separated list of fields to show | All fields |
| Field | Type | Description | Default |
|--------|----------|----------------------------------------------------------|------------|
| limit | number | Max number of bots to return (max 500) | 50 |
| offset | number | Number of bots to skip | 0 |
| sort | string | Field to sort by (use `-` prefix to reverse sort order) | |
| fields | string | Comma-separated fields to include | All fields |

### Response Fields
### Response

| Field | Type | Description |
|---------|-----------------------|-----------------------------------------------|
| results | [`Bot[]`](#bot-structure) | The matching bots |
| limit | number | The limit used |
| offset | number | The offset used |
| count | number | Number of bots returned |
| total | number | Total matching bots |

| Field | Type | Description |
| ------- | ------------------------- | --------------------------------------------- |
| results | [`Bot[]`](#bot-structure) | The matching bots |
| limit | `number` | The limit used |
| offset | `number` | The offset used |
| count | `number` | The length of the results array |
| total | `number` | The total number of bots matching your search |
#### Example Response

```json:title=/bots?search%3DLuca
```json title="/bots?search=Luca"
{
"results": [
{
"defAvatar": "6debd47ed13483642cf09e832ed0bc1b",
"invite": "",
"website": "https://discordbots.org",
"support": "KYZsaFb",
"github": "https://github.com/DiscordBotList/Luca",
"longdesc": "Luca only works in the **Discord Bot List** server. \r\nPrepend commands with the prefix `-` or `@Luca#1375`. \r\n**Please refrain from using these commands in non testing channels.**\r\n- `botinfo @bot` Shows bot info, title redirects to site listing.\r\n- `bots @user`* Shows all bots of that user, includes bots in the queue.\r\n- `owner / -owners @bot`* Shows all owners of that bot.\r\n- `prefix @bot`* Shows the prefix of that bot.\r\n* Mobile friendly version exists. Just add `noembed` to the end of the command.\r\n",
"shortdesc": "Luca is a bot for managing and informing members of the server",
"prefix": "- or @Luca#1375",
"clientid": "264811613708746752",
"avatar": "7edcc4c6fbb0b23762455ca139f0e1c9",
"id": "264811613708746752",
"discriminator": "1375",
"username": "Luca",
"date": "2017-04-26T18:08:17.125Z",
"server_count": 2,
"guilds": ["417723229721853963", "264445053596991498"],
"shards": [],
"monthlyPoints": 19,
"points": 397,
"certifiedBot": false,
"owners": ["129908908096487424"],
"tags": ["Moderation", "Role Management", "Logging"],
"donatebotguildid": ""
}
],
"results": [ { "id": "264811613708746752", "username": "Luca", "...": "..." } ],
"limit": 1,
"offset": 0,
"count": 1,
"total": 7
}
```

## Find One Bot
---

## 🧍 Get a Bot by ID

<HTTPHeader type="GET" path="bots/:bot_id" />

Finds a single bot
Returns a single bot object by ID.

### Example Response

[`Bot`](/docs/API/bot/#example-structure) **or** 404
[`Bot`](#bot-structure) object or HTTP 404 if not found.

## Last 1000 Votes

<HTTPHeader type="GET" path="bots/:bot_id/votes" />
---

Gets the last 1000 voters for your bot.
## 🗳️ Last 1000 Votes

> If your bot receives more than 1000 votes monthly you cannot use this endpoints and must use `webhooks` and implement your own caching instead.
<HTTPHeader type="GET" path="bots/:bot_id/votes" />

> This endpoint only returns unique votes, it does not include double votes (weekend votes).
Returns the last 1000 **unique** voters.

This example uses Luca but users are restricted to only receiving their own bots' votes. Replace the id with your own bot.
> ⚠️ If your bot receives over 1k votes/month, use webhooks + your own cache.
>
> Double (weekend) votes are not included here.

### Example Response
### Example

```json:title=/bots/1234/votes
```json title="/bots/1234/votes"
[
{
"username": "Xetera",
Expand All @@ -103,109 +83,109 @@ This example uses Luca but users are restricted to only receiving their own bots
]
```

## Bot stats
---

## 📊 Bot Stats

<HTTPHeader type="GET" path="bots/:bot_id/stats" />

Specific stats about a bot.
Returns public stats about the bot.

### Response
### Response Fields

| Field | Type | Description |
| ------------- | ---------- | ------------------------------------------------------------------------------ |
| server_count? | `number` | The amount of servers the bot is in |
| shards | `number[]` | The amount of servers the bot is in per shard. Always present but can be empty |
| shard_count? | `number` | The amount of shards a bot has |
| Field | Type | Description |
|---------------|------------|---------------------------------------------------------------|
| server_count? | number | Total server count |
| shards | number[] | Server count per shard (can be empty) |
| shard_count? | number | Number of shards configured |

---

## Individual User Vote
## 👤 Has User Voted?

<HTTPHeader type="GET" path="bots/:bot_id/check" />

Checking whether or not a user has voted for your bot. Safe to use even if you have over 1k monthly votes.
Checks if a user has voted in the past 12 hours.

### Params
### Query Parameters

| Field | Type | Description |
| ------ | ----------- | ----------------- |
| userId | `snowflake` | User's Discord ID |
|--------|-------------|-------------------|
| userId | snowflake | User’s Discord ID |

### Example Response

```json:title=/bots/9876/check?userId%3D1234
```json title="/bots/9876/check?userId=1234"
{
"voted": 1
}
```

## Post Stats
---

## 📤 Post Stats

<HTTPHeader type="POST" path="bots/:bot_id/stats" />

### Post Body

| Field | Type | Description | Required |
| ------------ | ---------------------- | ------------------------------------------------------------------------------------------------- | -------- |
| server_count | `number` \| `number[]` | Amount of servers the bot is in. If an Array, it acts like shards | ✔️ |
| shards | `number[]` | Amount of servers the bot is in per shard. | ❌ |
| shard_id | `number` | The zero-indexed id of the shard posting. Makes server_count set the shard specific server count. | ❌ |
| shard_count | `number` | The amount of shards the bot has. | ❌ |

## Bot Structure

| Field | Type | Description |
| ---------------- | ------------- | ----------------------------------------------------------------------------- |
| id | `string` | The id of the bot |
| username | `string` | The username of the bot |
| discriminator | `string` | The discriminator of the bot |
| avatar? | `string` | The avatar hash of the bot's avatar |
| defAvatar? | `string` | The cdn hash of the bot's avatar if the bot has none |
| lib <deprecated/>| `string` | The library of the bot |
| prefix | `string` | The prefix of the bot |
| shortdesc | `string` | The short description of the bot |
| longdesc? | `string` | The long description of the bot. Can contain HTML and/or Markdown |
| tags | `string[]` | The tags of the bot |
| website? | `string` | The website url of the bot |
| support? | `string` | The support server invite code of the bot |
| github? | `string` | The link to the github repo of the bot |
| owners | `snowflake[]` | of Snowflakes The owners of the bot. First one in the array is the main owner |
| guilds | `snowflake[]` | of Snowflakes The guilds featured on the bot page |
| invite? | `string` | The custom bot invite url of the bot |
| date | `datestring` | The date when the bot was approved |
| server_count? | `number` | The amount of servers the bot has according to posted stats. |
| shard_count? | `number` | The amount of shards the bot has according to posted stats. |
| certifiedBot | `boolean` | The certified status of the bot |
| vanity? | `string` | The vanity url of the bot |
| points | `number` | The amount of upvotes the bot has |
| monthlyPoints | `number` | The amount of upvotes the bot has this month |
| donatebotguildid | `string` | The guild id for the donatebot setup |

### Example Structure
Posts bot stats to the platform.

### Body Parameters

| Field | Type | Description | Required |
|--------------|----------------------|-----------------------------------------------------------------------------|----------|
| server_count | number or number[] | Server count or per-shard counts | ✅ |
| shards | number[] | Per-shard server counts (alternative to above) | ❌ |
| shard_id | number | If using shards, sets which shard is sending stats | ❌ |
| shard_count | number | Total shard count | ❌ |

---

## 📦 Bot Structure

Describes the shape of a full `Bot` object.

| Field | Type | Description |
|------------------|-------------|-----------------------------------------------------------------|
| id | string | Bot ID |
| username | string | Username |
| discriminator | string | Discord tag |
| avatar? | string | Avatar hash |
| defAvatar? | string | Default avatar hash |
| lib <deprecated/>| string | Library used |
| prefix | string | Command prefix |
| shortdesc | string | Short description |
| longdesc? | string | Long description (supports HTML/Markdown) |
| tags | string[] | Bot category tags |
| website? | string | Bot’s website |
| support? | string | Support server invite code |
| github? | string | GitHub repo link |
| owners | snowflake[] | Array of owners (first is the primary) |
| guilds | snowflake[] | Featured guilds |
| invite? | string | Custom invite URL |
| date | datestring | Date the bot was approved |
| server_count? | number | Server count (from posted stats) |
| shard_count? | number | Shard count |
| certifiedBot | boolean | If the bot is certified |
| vanity? | string | Vanity URL |
| points | number | Total upvotes |
| monthlyPoints | number | Monthly upvotes |
| donatebotguildid | string | Guild ID for donatebot integration |

### Example

```json
{
"defAvatar": "6debd47ed13483642cf09e832ed0bc1b",
"invite": "",
"website": "https://discordbots.org",
"support": "KYZsaFb",
"github": "https://github.com/DiscordBotList/Luca",
"longdesc": "Luca only works in the **Discord Bot List** server. \r\nPrepend commands with the prefix `-` or `@Luca#1375`. \r\n**Please refrain from using these commands in non testing channels.**\r\n- `botinfo @bot` Shows bot info, title redirects to site listing.\r\n- `bots @user`* Shows all bots of that user, includes bots in the queue.\r\n- `owner / -owners @bot`* Shows all owners of that bot.\r\n- `prefix @bot`* Shows the prefix of that bot.\r\n* Mobile friendly version exists. Just add `noembed` to the end of the command.\r\n",
"username": "Luca",
"id": "264811613708746752",
"shortdesc": "Luca is a bot for managing and informing members of the server",
"prefix": "- or @Luca#1375",
"clientid": "264811613708746752",
"avatar": "7edcc4c6fbb0b23762455ca139f0e1c9",
"id": "264811613708746752",
"discriminator": "1375",
"username": "Luca",
"date": "2017-04-26T18:08:17.125Z",
"server_count": 2,
"shard_count": 1,
"guilds": ["417723229721853963", "264445053596991498"],
"shards": [],
"monthlyPoints": 19,
"owners": ["129908908096487424"],
"points": 397,
"monthlyPoints": 19,
"certifiedBot": false,
"owners": ["129908908096487424"],
"tags": ["Moderation", "Role Management", "Logging"],
"donatebotguildid": ""
"tags": ["Moderation", "Role Management", "Logging"]
}
```

---
Loading