Endpoint Index
Every v1 endpoint at a glance, with links to the full reference.
Base URL
https://labs.conscherry.com/api/v1
Authentication
Public read endpoints need no key. Writing stats, sending heartbeats and checking votes require an API key sent as a Bearer token.
Authorization: Bearer YOUR_API_KEY
Endpoints
| Method | Path | Access | Description |
|---|---|---|---|
| GET | /bots | Public | List and search bots |
| GET | /bots/:id | Public | Get one bot |
| GET | /users | Public | List users |
| GET | /website | Public | Site-wide statistics |
| POST | /stats | API key | Post server, user and shard counts |
| GET | /stats | API key | Read your posted statistics |
| POST | /heartbeat | API key | Mark your bot online without posting stats |
| GET | /bots/:id/check | API key | Check whether a user has voted |
Full parameters and responses are in the API Reference. Vote checks and heartbeats are covered in Vote Webhooks.
Posting stats
Send your bot’s counts so the listing stays accurate. The server accepts one update per bot every 5 minutes, so posting hourly is plenty.
curl -X POST https://labs.conscherry.com/api/v1/stats \-H "Authorization: Bearer YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{"botId":"123456789012345678","guildCount":1234,"userCount":45000,"shardCount":2}'
The server count field may be sent as guildCount, serverCount or server_count.
Rate limits
Responses include X-RateLimit-* headers, and 429 responses add Retry-After. Exact quotas per scope are listed in Rate Limiting.
Vote webhooks
Get a signed POST for every vote, with automatic retries and delivery history. Payloads, signature verification and rewards are documented in Vote Webhooks.
Errors
| Status | Meaning |
|---|---|
| 400 | Invalid request parameters or body |
| 401 | Missing or invalid API key |
| 403 | Key lacks the required permission |
| 404 | Resource not found |
| 429 | Rate limited. Wait for Retry-After |
| 500 | Something went wrong on our end |
See Error Handling for the response format and a retry example.
Keep going
Need more help?
Ask in our Discord or email support@conscherry.com.