BotForge API Reference
The Premier Discovery Hub for Discord Bots
Getting Started
API Overview
The BotForge REST API gives programmatic access to our bot catalog, voting data, analytics, and moderation tools. All endpoints return JSON and are served over HTTPS at https://api.botforge.dev/v1.
Every request is rate-limited to 60 requests per minute for unauthenticated calls and 300 per minute for authenticated clients. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response. Paginated endpoints return a maximum of 50 items per page with Link headers for navigation.
BotForge currently indexes 12,847 bots across 42 categories. The API supports filtering by category, server count, verification status, and addition date. Webhook subscriptions are available for real-time notifications on bot additions, votes, and status changes — subscribe via the /webhooks endpoint.
Resources
Available Endpoints
Browse our core API resources. Each endpoint supports standard HTTP methods and returns structured JSON responses.
GET /bots
List all bots with optional filtering by category, min/max server count, verification status, and sort order. Supports cursor-based pagination. Returns bot ID, name, description, icon URL, server count, and tags.
GET /bots/{id}
Fetch detailed information for a single bot. Includes full description, invite URL, owner ID, prefix, command count, library used, last updated timestamp, and 30-day vote history.
GET /bots/{id}/votes
Retrieve vote records for a specific bot. Paginated list of voter user IDs, timestamps, and optional feedback messages. Useful for building leaderboards or reward systems.
POST /bots/{id}/vote
Cast a vote for a bot on behalf of an authenticated user. Requires a valid OAuth2 access token or API key with the vote scope. Returns the updated vote count and voter's position in the 24h leaderboard.
GET /analytics/servers
Aggregate server count data across the entire BotForge catalog. Returns daily snapshots, growth percentages, and category breakdowns. Data updates every 6 hours from cached Discord gateway statistics.
POST /webhooks
Register a webhook endpoint to receive real-time events. Supported events: bot.created, bot.updated, vote.cast, bot.verified, bot.removed. Includes signature verification via HMAC-SHA256.
Security
Authentication
BotForge supports two authentication methods: API keys for server-to-server communication and OAuth2 for user-facing applications.
API Keys — Generate keys from your BotForge Developer Dashboard at dashboard.botforge.dev/keys. Each key is scoped to specific permissions (read:bots, write:votes, read:analytics, manage:webhooks). Include your key in the Authorization header as Bearer <key>. Keys are 64-character hex strings and can be rotated without downtime.
OAuth2 — For applications that act on behalf of end users, use the OAuth2 authorization code flow. The authorization endpoint is https://discord.com/api/oauth2/authorize with BotForge-scoped permissions. Supported scopes include identify, guilds.join, and botforge.vote. Access tokens expire after 6 hours; use the refresh token endpoint to extend sessions.
All API endpoints require HTTPS. Requests without valid authentication receive a 401 Unauthorized response. Expired or revoked tokens return 403 Forbidden. For production integrations, store credentials in environment variables — never hardcode them in client-side code.
Rate Limits
Unauthenticated: 60 req/min per IP. Authenticated: 300 req/min per API key. Burst allowance of 10 requests above the limit. Exceeding limits returns 429 Too Many Requests with a Retry-After header in seconds.
Response Codes
200 Success · 201 Created · 400 Bad Request · 401 Unauthorized · 403 Forbidden · 404 Not Found · 429 Rate Limited · 500 Server Error. All errors include a JSON body with error and message fields.
Implementation
Code Examples
Quick-start snippets in popular languages to get you integrating with BotForge in minutes.
JavaScript / Node.js
Use fetch or axios to query the bots endpoint. Set your API key in the Authorization header. Parse the JSON response to render bot cards, search results, or analytics dashboards in your application.
const res = await fetch('https://api.botforge.dev/v1/bots?limit=25&sort=trending', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }); const bots = await res.json();
Python
The requests library handles authentication and pagination cleanly. Ideal for data pipelines, scheduled analytics reports, or Discord bot commands that query BotForge for recommendations.
import requests\nresp = requests.get('https://api.botforge.dev/v1/bots/829104736281948672/votes', headers={'Authorization': f'Bearer {API_KEY}'})\nvotes = resp.json()
Discord.js Bot Integration
Embed BotForge data directly into your Discord bot's slash commands. Use the /bots/{id} endpoint to generate rich embeds with bot descriptions, server counts, and invite links inside your guild.
await interaction.reply({ embeds: [new EmbedBuilder().setTitle(bot.data.name).setDescription(bot.data.description).setThumbnail(bot.data.icon)] });