From 48eb7e5bbd5426199c5fe3de030d61599463a2bf Mon Sep 17 00:00:00 2001 From: Antiscammer-Dev-team Date: Sat, 14 Jun 2025 03:34:31 -0400 Subject: [PATCH] Rework of site Cleanup and stylization --- docs/API/@reference.mdx | 36 ++++-- docs/API/bot.mdx | 246 +++++++++++++++++--------------------- docs/API/user.mdx | 69 ++++++----- docs/Libraries/python.mdx | 59 +++++---- docs/index.md | 35 +++++- 5 files changed, 249 insertions(+), 196 deletions(-) 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!