The Rankly Public API allows server owners and developers to programmatically access server data, check vote status, and retrieve reviews.
Base Configuration
Base URL: https://api.rankly.live/api/v1
Authentication
All API requests require authentication using an API Key. Generate your API Key in your server dashboard:
Dashboard Path: Edit Server → Advanced Setup → API Key
Keep your API Key secure and never share it publicly. Treat it like a password to your server data.
Rate Limiting
The Public API enforces rate limits to ensure fair usage:
Limit Value Requests per minute 120 Per API Key Exceeded response 429 Too Many Requests
Rate limit headers are planned for a future update. Currently, responses don’t include rate limit information.
Endpoints
Get Server Details
Retrieve public information about your server.
Authentication: Required
Get Bot Details
Retrieve public information about your bot.
Authentication: Required
Check User Vote Status
Verify if a user can vote or is on cooldown.
GET
default: "/votes/{userId}"
Check vote eligibility
Parameters:
Parameter Type Description userIdstring Discord User ID to check
Authentication: Required
{
"success" : true ,
"data" : {
"canVote" : true
}
}
Get Server Reviews
Retrieve the latest reviews for your server with flexible filtering.
Query Parameters:
Parameter Type Default Max Description limitinteger 10 50 Number of reviews to return sortstring newest- Sort order: newest, highest, lowest
Authentication: Required
Error Handling
All API errors follow a consistent JSON structure:
{
"success" : false ,
"error" : "Error message description"
}
Common Error Codes:
Status Error Description 401 UnauthorizedInvalid or missing API Key 404 Not FoundServer or resource not found 429 Too Many RequestsRate limit exceeded
Code Examples
cURL
JavaScript
Python
Go
# Get server details
curl -X GET "https://api.rankly.live/api/v1/server" \
-H "X-API-Key: rk_live_..." \
-H "Content-Type: application/json"
# Check user vote status
curl -X GET "https://api.rankly.live/api/v1/votes/123456789" \
-H "X-API-Key: rk_live_..."
# Get reviews (sorted by highest rating)
curl -X GET "https://api.rankly.live/api/v1/reviews?limit=25&sort=highest" \
-H "X-API-Key: rk_live_..."
const API_KEY = "rk_live_..." ;
const BASE_URL = "https://api.rankly.live/api/v1" ;
// Get server details
async function getServerDetails () {
const response = await fetch ( ` ${ BASE_URL } /server` , {
headers: { "X-API-Key" : API_KEY }
});
return response . json ();
}
// Check vote status
async function checkVoteStatus ( userId ) {
const response = await fetch ( ` ${ BASE_URL } /votes/ ${ userId } ` , {
headers: { "X-API-Key" : API_KEY }
});
return response . json ();
}
// Get reviews
async function getReviews ( limit = 10 , sort = "newest" ) {
const params = new URLSearchParams ({ limit , sort });
const response = await fetch ( ` ${ BASE_URL } /reviews? ${ params } ` , {
headers: { "X-API-Key" : API_KEY }
});
return response . json ();
}
import requests
API_KEY = "rk_live_..."
BASE_URL = "https://api.rankly.live/api/v1"
headers = { "X-API-Key" : API_KEY }
# Get server details
def get_server_details ():
response = requests.get( f " { BASE_URL } /server" , headers = headers)
return response.json()
# Check vote status
def check_vote_status ( user_id ):
response = requests.get( f " { BASE_URL } /votes/ { user_id } " , headers = headers)
return response.json()
# Get reviews
def get_reviews ( limit = 10 , sort = "newest" ):
params = { "limit" : limit, "sort" : sort}
response = requests.get( f " { BASE_URL } /reviews" , headers = headers, params = params)
return response.json()
package main
import (
" fmt "
" net/http "
" io/ioutil "
)
const (
APIKey = "rk_live_..."
BaseURL = "https://api.rankly.live/api/v1"
)
func getServerDetails () {
req , _ := http . NewRequest ( "GET" , BaseURL + "/server" , nil )
req . Header . Add ( "X-API-Key" , APIKey )
client := & http . Client {}
resp , _ := client . Do ( req )
body , _ := ioutil . ReadAll ( resp . Body )
fmt . Println ( string ( body ))
}
Best Practices
Store API keys in environment variables, never hardcode them
Use HTTPS for all requests (never HTTP)
Rotate keys regularly if they may be compromised
Use different keys for different applications
Implement retry logic with exponential backoff for failed requests
Handle rate limit responses (429) gracefully
Log API errors for debugging purposes
Provide meaningful error messages to users
What’s Next