Skip to main content
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:
LimitValue
Requests per minute120
PerAPI Key
Exceeded response429 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.
GET
default:"/server"
Fetch server details
Authentication: Required

Get Bot Details

Retrieve public information about your bot.
GET
default:"/bot"
Fetch bot details
Authentication: Required

Check User Vote Status

Verify if a user can vote or is on cooldown.
GET
default:"/votes/{userId}"
Check vote eligibility
Parameters:
ParameterTypeDescription
userIdstringDiscord User ID to check
Authentication: Required
{
  "success": true,
  "data": {
    "canVote": true
  }
}

Get Server Reviews

Retrieve the latest reviews for your server with flexible filtering.
GET
default:"/reviews"
Fetch server reviews
Query Parameters:
ParameterTypeDefaultMaxDescription
limitinteger1050Number of reviews to return
sortstringnewest-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:
StatusErrorDescription
401UnauthorizedInvalid or missing API Key
404Not FoundServer or resource not found
429Too Many RequestsRate limit exceeded

Code Examples

# 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_..."

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
  • Cache responses when appropriate to avoid unnecessary requests
  • Implement exponential backoff for rate limit handling
  • Batch requests when possible
  • Monitor your API usage to stay within rate limits
  • 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