diff --git a/docs/API/@reference.mdx b/docs/API/@reference.mdx
index 8188c91..4c88612 100644
--- a/docs/API/@reference.mdx
+++ b/docs/API/@reference.mdx
@@ -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.
diff --git a/docs/API/bot.mdx b/docs/API/bot.mdx
index cfb238d..60bb741 100644
--- a/docs/API/bot.mdx
+++ b/docs/API/bot.mdx
@@ -1,67 +1,45 @@
---
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
-
+
-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,
@@ -69,31 +47,33 @@ Gets a list of bots that match a specific query.
}
```
-## Find One Bot
+---
+
+## π§ Get a Bot by 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
-
-
+---
-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.
+
-> 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",
@@ -103,109 +83,109 @@ This example uses Luca but users are restricted to only receiving their own bots
]
```
-## Bot stats
+---
+
+## π Bot 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?
-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
-### 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 | `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 | 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"]
}
```
+
+---
diff --git a/docs/API/user.mdx b/docs/API/user.mdx
index 3ed86ab..9e2c0b0 100644
--- a/docs/API/user.mdx
+++ b/docs/API/user.mdx
@@ -5,43 +5,54 @@ description: API resource for Top.gg users
import HTTPHeader from "../../src/components/HTTPHeader";
-A user represents a User account in top.gg. It is not associated with any other platform like Discord.
+> A **user** represents an account registered on Top.gg.
+> It is **not** directly associated with any platform like Discord.
-## Find One User
+---
+
+## π€ Find One User
-Retrieves information about a particular user by their Discord user id.
+Retrieves information about a specific user by their Discord user ID.
+
+### Example cURL
```bash
curl -X GET https://top.gg/api/users/140862798832861184 \
- -H 'Content-Type: application/json' \
- -H 'Authorization: your-topgg-token'
+ -H 'Content-Type: application/json' \
+ -H 'Authorization: your-topgg-token'
```
-## Structure
-
-| Field | Type | Description |
-| ----------------- | ----------- | ----------------------------------------------------------------- |
-| id | `snowflake` | The id of the user |
-| username | `string` | The username of the user |
-| discriminator | `string` | The discriminator of the user |
-| avatar? | `string` | The avatar hash of the user's avatar |
-| defAvatar | `string` | The cdn hash of the user's avatar if the user has none |
-| bio? | `string` | The bio of the user |
-| banner? | `string` | The banner image url of the user |
-| social | `object` | The social usernames of the user |
-| social.youtube? | `string` | The youtube channel id of the user |
-| social.reddit? | `string` | The reddit username of the user |
-| social.twitter? | `string` | The twitter username of the user |
-| social.instagram? | `string` | The instagram username of the user |
-| social.github? | `string` | The github username of the user |
-| color? | `string` | The custom hex color of the user (not guaranteed to be valid hex) |
-| supporter | `boolean` | The supporter status of the user |
-| certifiedDev | `boolean` | The certified status of the user |
-| mod | `boolean` | The mod status of the user |
-| webMod | `boolean` | The website moderator status of the user |
-| admin | `boolean` | The admin status of the user |
+---
+
+## 𧱠User Object Structure
+
+| Field | Type | Description |
+|--------------------|-------------|-------------------------------------------------------------------|
+| id | `snowflake` | Discord user ID |
+| username | `string` | Username of the user |
+| discriminator | `string` | Discord discriminator (e.g., `0001`) |
+| avatar? | `string` | Avatar hash (if set) |
+| defAvatar | `string` | Default avatar hash if no custom avatar |
+| bio? | `string` | Userβs profile bio |
+| banner? | `string` | Banner image URL |
+| social | `object` | Social links object |
+| social.youtube? | `string` | YouTube channel ID |
+| social.reddit? | `string` | Reddit username |
+| social.twitter? | `string` | Twitter username |
+| social.instagram? | `string` | Instagram username |
+| social.github? | `string` | GitHub username |
+| color? | `string` | Custom hex profile color (may not be valid hex) |
+| supporter | `boolean` | Whether user is a Top.gg supporter |
+| certifiedDev | `boolean` | Whether user is a certified developer |
+| mod | `boolean` | Whether user is a moderator |
+| webMod | `boolean` | Whether user is a website moderator |
+| admin | `boolean` | Whether user is an administrator |
+
+---
+
+### π§Ύ Example Response
```json
{
@@ -58,3 +69,5 @@ curl -X GET https://top.gg/api/users/140862798832861184 \
"social": {}
}
```
+
+---
diff --git a/docs/Libraries/python.mdx b/docs/Libraries/python.mdx
index e6a8af7..3fc1641 100644
--- a/docs/Libraries/python.mdx
+++ b/docs/Libraries/python.mdx
@@ -3,36 +3,51 @@ title: Python
description: Top.gg Python library
---
-# Python Library
+# π Top.gg Python Library
-The community-maintained Python Library for Top.gg, if you experience any issues please submit an issue on our github.
+This is a **community-maintained** SDK for interacting with the [Top.gg API](https://top.gg/api) in Python.
-- [Full documentation](https://topggpy.rtfd.io/)
-- [GitHub link](https://github.com/top-gg/python-sdk)
+If you experience any issues, please [open an issue on GitHub](https://github.com/top-gg/python-sdk/issues).
-## Installation
+---
+
+## π Resources
+
+- π [Full Documentation](https://topggpy.rtfd.io/)
+- π οΈ [GitHub Repository](https://github.com/top-gg/python-sdk)
+
+---
+
+## π¦ Installation
+
+Install via pip:
-```console
-$ pip install topggpy
+```bash
+pip install topggpy
```
-## Documentation
+---
+
+## π§° Features
+
+- β
Post server count
+- β
Get bot info, server count, upvote status
+- β
Get user info
+- β
Get widgets (large, small, and custom) β see [docs.top.gg](https://docs.top.gg)
+- β
Get weekend status
+- β
Built-in webhook listener for vote handling
+- β
Auto-post server stats
+- β
Search for bots via the API
-Documentation can be found [here](https://topggpy.rtfd.io).
+---
+
+## π Notes on Webhooks
-## Features
+Before using the webhook handler:
-- POST server count
-- GET bot info, server count, upvote info
-- GET user info
-- GET widgets (large and small) including custom ones. See [docs.top.gg](https://docs.top.gg) for more info.
-- GET weekend status
-- Built-in webhook to handle Top.gg votes
-- Automated server count posting
-- Searching for bots via the API
+- Make sure the **port you're binding to is open**
+- Recommended port range: `1024β49151`
-## Additional information
+Need help? Join the [Top.gg Discord](https://discord.gg/dbl) and ask in `#development` or `#api`.
-- Before using the webhook provided by this library, make sure that you have specified port open.
-- Optimal values for port are between 1024 and 49151.
-- If you happen to need help implementing topggpy in your bot, feel free to ask in the `#development` or `#api` channels in our [Discord server](https://discord.gg/dbl)
\ No newline at end of file
+---
diff --git a/docs/index.md b/docs/index.md
index fc11709..cd6bb5c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,14 +3,37 @@ title: Home
description: Welcome to Top.gg
---
-Hi developer π₯°, welcome to top.gg developer docs. You are currently viewing **v0** of our API documentation. We're going to be working on the next version of the top.gg API (v1) soon, stay tuned!
+# π Welcome to the Top.gg Developer Docs
-## Getting Started
+Hi developer π₯° β welcome to the official documentation for Top.gg!
-If you're looking for API usage, [click here](/docs/API/@reference/) or go to the `API` section on the sidebar.
+You're currently viewing **v0** of our API documentation.
+Weβre actively working on the next version of the API (**v1**), so stay tuned for updates!
-## Getting Help
+---
+
+## π Getting Started
+
+If you're here to use the API, head over to:
+
+π [API Reference](/docs/API/@reference/)
+Or explore the **API** section from the sidebar navigation.
+
+---
-If you need some help or think you have spotted a problem with our API you can talk to us in our [`#topgg-api`](https://discord.com/channels/264445053596991498/412006692125933568) channel in our [discord server](https://discord.gg/EYHTgJX).
+## π¬ Getting Help
+
+Need assistance or found an issue?
+
+Join our developer community in the
+[`#topgg-api`](https://discord.com/channels/264445053596991498/412006692125933568) channel
+on our [Discord server](https://discord.gg/EYHTgJX).
+
+We're happy to help with:
+- Questions about the API
+- Usage of our community-maintained libraries
+- General development queries
+
+---
-You can ask questions about our community-maintained API Libraries or general queries about the API in the server.
+π Happy building!