botliy API v1

Developer API Docs

Seamlessly integrate your Discord bot with botliy. Post live stats, retrieve votes, and process real-time webhooks. Built for developers, by developers.

BASE URL https://botliy.online

Format: JSON

Auth: Bearer Token

Rate Limit: 1 req/sec

Need Developer Support?

If you encounter issues or need help implementing the API, join our Discord server and ask in the #api-support channel. We're here to help.

Quick Start

Get your bot integrated in three simple steps.

1

List your bot

Submit your bot for review. Once approved, head to the edit page to generate your API token and Webhook Secret.

2

Authenticate Requests

Include your token in the headers of protected endpoints: Authorization: your_api_token.

3

Implement Logic

Set up an interval (e.g., 30 mins) to POST your server count, and create an HTTP endpoint on your server to receive Webhook vote events.

Authorization

Protected routes require your unique bot API token. This must be passed via the Authorization header.

HTTP Header

Authorization: your_api_token_here

IP Whitelisting (Recommended)

Enhance security by locking your API token to specific IP addresses via the bot edit panel. Unauthorized IPs will receive a 403 Forbidden response.

Rate Limits

To ensure platform stability, all API requests are subject to rate limiting based on your IP address.

Global Limit: 1 request per second per IP.
Stat Posting: We recommend posting stats every 15-30 minutes. Do not post on every guild join/leave event.

HTTP 429 Too Many Requests

If you exceed the rate limit, the API will reject requests with a 429 status. Repeated abuse may result in temporary blacklisting.

Post Stats

POST /api/bots/:id/stats

Update your bot's live server and shard counts on the platform. Auth Required

Parameter	Type	Description
`server_count` Req	integer	Total number of servers the bot is in.
`shard_count`	integer	Total number of active shards.

Request Body

JSON

{ "server_count": 15420, "shard_count": 2 }

Responses

200Stats updated successfully.

401Missing or invalid Authorization token.

404Bot not found.

Get Stats

GET /api/bots/:id/stats

Retrieve the current server and shard counts registered for a bot. No Auth

Response

JSON

{ "error": false, "server_count": 15420, "shard_count": 2 }

Get Votes

GET /api/bots/:id/votes

Fetch an array of the 1,000 most recent votes for your bot. Auth Required

Response

JSON

{ "error": false, "votes": [ { "username": "User123", "id": "123456789012345678", "date": "2026-03-10T12:00:00.000Z" } ] }

Check Vote (Auth)

GET /api/bots/:id/check

Check if a specific user has voted in the last 12 hours (Returns 1 or 0). Auth Required

Query Param	Type	Description
`userId` Req	string	Discord snowflake ID of the user.

Example Request

GET /api/bots/123456789/check?userId=987654321

Response

JSON

{ "error": false, "voted": 1 // 1 = Voted, 0 = Not Voted }

Get Bot Info

GET /api/bots/:id

Retrieve comprehensive public data about a specific bot. No Auth

Field	Type	Description
`id`	string	Bot's Discord ID
`username`	string	Bot's Username
`tags`	array	Array of category tags
`votes`	number	Total upvotes
`server_count`	number	Current server count
`average_rating`	number	Rating out of 5.0
`presence`	string	online/idle/dnd/offline

Search Bots

GET /api/bots

Search and filter the bot registry with pagination. No Auth

Query Param	Type	Description
`q`	string	Search query matching username/description
`tag`	string	Filter by exact tag
`sort`	string	Sort by: `votes`, `new`, `servers`
`limit`	number	Results per page (1-50, default: 20)
`offset`	number	Pagination offset (default: 0)

Example Request

GET /api/bots?q=music&tag=Music&sort=votes&limit=10

Get Reviews

GET /api/bots/:id/reviews

Retrieve user reviews and calculated average rating for a bot. No Auth

JSON Response

{ "average_rating": 4.8, "total": 12, "reviews": [ { "user_id": "123456789", "rating": 5, "content": "Great bot!", "date": "2026-03-10T12:00:00Z" } ] }

Has User Voted (Public)

GET /api/bots/:id/has-voted/:userId

Public endpoint to check if a user has voted. Ideal for client-side checks or simple bots. No Auth

JSON Response

{ "error": false, "bot_id": "123", "user_id": "456", "voted": true, "next_vote_at": "2026-03-10T18:00:00Z" }

Platform Stats

GET /api/stats

Get global metrics for the botliy platform. No Auth

{
                  "total_bots": 1250,
                  "total_votes": 45000,
                  "total_servers": 1200000
                  }
                

Get Tags

GET /api/tags

Retrieve all valid categories and their bot counts. No Auth

{
                  "tags": [
                  { "name": "Music", "count": 142 },
                  { "name": "Moderation", "count": 98 }
                  ]
                  }
                

Webhook Events

Receive real-time POST requests to your server immediately when a user votes for your bot. Configure the URL in your bot edit panel.

POST Your Configured URL

We send JSON payloads. Verify authenticity using the Authorization header.

Headers Received

Authorization: your_webhook_secret_here
                  Content-Type: application/json

JSON Payload Received

{
                  "bot": "123456789012345678", // Your Bot ID
                  "user": "876543210987654321", // Voter ID
                  "type": "upvote"
                  }
                

Node.js (express)

index.js

TypeScript

index.ts

import express, { Request, Response } from 'express'; const app = express(); app.use(express.json()); app.post('/webhook', (req: Request, res: Response) => { if (req.headers.authorization !== process.env.SECRET) { return res.status(401).send("Unauthorized"); } const userId: string = req.body.user; res.sendStatus(200); });

Python (Flask)

app.py

from flask import Flask, request, jsonify app = Flask(__name__) @app.route('/webhook', methods=['POST']) def webhook(): if request.headers.get('Authorization') != 'SECRET': return 'Unauthorized', 401 user = request.json.get('user') return 'OK', 200

Go

main.go

package main import ( "encoding/json"; "net/http" ) type Webhook struct { User string `json:"user"` } func handler(w http.ResponseWriter, r *http.Request) { if r.Header.Get("Authorization") != "SECRET" { http.Error(w, "Unauthorized", 401) return } var p Webhook json.NewDecoder(r.Body).Decode(&p) w.WriteHeader(200) }