API 1.0.0REST APIStable

API Reference

Complete documentation of all available endpoints

Base URL

Shell

https://labs.conscherry.com/api/v1

Telemetry & Attribution Headers

Clients may optionally include non-sensitive telemetry headers to help diagnose integrations and attribute usage. These headers are advisory — do not include secrets or personally identifiable information. The API records a whitelisted set of headers when an API key is provided.

Recommended headers:
X-SDK-Name — SDK or client name (max 50 chars)
X-SDK-Version — SDK version (max 50 chars)
X-SDK-Lang — language/runtime (e.g. "javascript")
X-SDK-Instance-Id — anonymous instance id (alphanumeric, - or _, max 64 chars)
User-Agent — optional client UA (max ~200 chars)

Note: these headers are advisory. The API key is the authoritative signal for attribution. Avoid sending PII in headers; SDKs should batch telemetry client-side before sending.

Authentication

Only the stats posting endpoint requires authentication using your API key in the Authorization header:

Shell

Authorization: Bearer YOUR_API_KEY

Public endpoints (no auth required): GET /bots, GET /bots/:id, GET /users, GET /website

Authenticated endpoints (API key required): POST /stats, GET /stats

Note: The API v1 is read-only for public data. Bot submissions and user management must be done through the authenticated web interface.

List Bots

GET/bots

Query Parameters

Parameters for listing bots
Name	Type	Required	Default	Description
limit	number	No	20 (max 100)	Number of results
offset	number	No	0 (max 5000)	Pagination offset
sort	string	No	-votes	Sort order (e.g., -votes, -guilds)
search	string	No	-	Search query
category	string	No	-	Filter by category
certified	boolean	No	-	Filter certified bots
verified	boolean	No	-	Filter verified bots
nsfw	boolean	No	-	Filter NSFW bots

Response

200 OK

JSON

1{
2  "success": true,
3  "data": [
4    {
5      "id": "123456789012345678",
6      "name": "Bot Name",
7      "description": "Short description",
8      "logo": "https://...",
9      "votes": 150,
10      "guilds": 5000,
11      "certified": false,
12      "verified": true,
13      "nsfw": false,
14      "categories": ["moderation", "fun"],
15      "owner": {
16        "id": "...",
17        "username": "Owner",
18        "avatar": "..."
19      }
20    }
21  ],
22  "pagination": {
23    "limit": 20,
24    "offset": 0,
25    "total": 245,
26    "hasMore": true
27  }
28}

Note: responses for list endpoints include Cache-Control headers for CDN caching where appropriate (e.g., /bots uses short s-maxage to enable CDN caching: s-maxage=60).

Get Website Statistics

GET/website

Get public statistics about the entire platform/website.

Response

200 OK

JSON

1{
2  "success": true,
3  "data": {
4    "bots": {
5      "total": 1234,
6      "approved": 1150,
7      "certified": 42,
8      "verified": 380
9    },
10    "users": 5678,
11    "votes": 125430,
12    "guilds": 2500000
13  }
14}

Note: the website statistics endpoint is cached for short periods to reduce load; responses include Cache-Control headers (e.g., s-maxage=120).

Get Bot by ID

GET/bots/:id

Get detailed information about a specific bot using its Discord client ID.

Response

200 OK

JSON

1{
2  "success": true,
3  "data": {
4    "id": "123456789012345678",
5    "name": "Bot Name",
6    "description": "Full description",
7    "shortDescription": "Short description",
8    "logo": "https://...",
9    "banner": "https://...",
10    "inviteUrl": "https://discord.com/oauth2/authorize?...",
11    "supportServerUrl": "https://discord.gg/...",
12    "websiteUrl": "https://...",
13    "documentationUrl": "https://docs...",
14    "githubUrl": "https://github.com/...",
15    "categories": ["moderation", "fun"],
16    "tags": ["music", "games"],
17    "prefix": "!",
18    "votes": 1500,
19    "guilds": 50000,
20    "certified": false,
21    "verified": true,
22    "partnered": false,
23    "nsfw": false,
24    "owner": {
25      "id": "...",
26      "username": "Owner",
27      "avatar": "..."
28    },
29    "averageRating": 4.5,
30    "reviewCount": 42,
31    "createdAt": "2024-01-01T00:00:00.000Z",
32    "updatedAt": "2024-01-15T10:30:00.000Z"
33  }
34}

List Users

GET/users

Query Parameters

Parameters for listing users
Name	Type	Required	Default	Description
limit	number	No	20 (max 100)	Number of results
offset	number	No	0 (max 5000)	Pagination offset
sort	string	No	-totalBots	Sort order (e.g., -totalBots, -totalVotes)
search	string	No	-	Search query

Response

JSON

1{
2  "success": true,
3  "data": [
4    {
5      "id": "123456789012345678",
6      "username": "username",
7      "avatar": "https://...",
8      "stats": {
9        "totalBots": 5,
10        "approvedBots": 4,
11        "totalVotes": 1250,
12        "totalViews": 50000,
13        "joinedAt": "2024-01-01T00:00:00.000Z"
14      }
15    }
16  ],
17  "pagination": {
18    "limit": 20,
19    "offset": 0,
20    "total": 450,
21    "hasMore": true
22  }
23}

Post Bot Statistics

POST/statsRequires auth

Request Body

JSON

1{
2  "botId": "123456789012345678", // Required: Your bot client ID
3  "guildCount": number,           // Required: Number of guilds (alias: serverCount/server_count)
4  "userCount": number,            // Required: Total unique users (alias: user_count)
5  "shardCount": number,           // Optional: Number of shards (alias: shard_count or shards[].length)
6  "uptime": number,               // Optional: Bot uptime in seconds
7  "ping": number,                 // Optional: Bot ping in milliseconds
8  "customFields": {               // Optional: Custom fields
9    "[key]": string | number
10  }
11}

Compatibility: accepts serverCount/server_count and shard_count/shards like top.gg/DBL.

Rate limit: the server enforces one stats update per bot every 5 minutes. Exceeding requests return 429 with Retry-After: 300. We recommend posting stats hourly to avoid rate limits and spikes; hourly updates are sufficient for most analytics and reduce load on both the client and server.

Required permission: write:stats

Response

JSON

1{
2  "success": true,
3  "message": "Stats updated successfully",
4  "data": {
5    "id": "stat_01hxyz",
6    "botId": "123456789012345678",
7    "guildCount": 1200,
8    "userCount": 42000,
9    "createdAt": "2024-01-15T10:30:00Z"
10  }
11}

Get Bot Statistics

GET/statsRequires auth

Query Parameters

Parameters for fetching stats
Name	Type	Required	Default	Description
botId	string	Yes	-	Bot client ID you own
limit	number	No	10 (max 100)	Limit number of records

Required permission: read:stats or write:stats

Response

JSON

1{
2  "success": true,
3  "data": [
4    {
5      "_id": "string",
6      "botId": "123456789012345678",
7      "userId": "string",
8      "guildCount": number,
9      "userCount": number,
10      "shardCount": number,
11      "createdAt": "2024-01-15T10:30:00Z"
12    }
13  ]
14}

Error Responses

All errors follow a consistent format:

JSON

1{
2  "success": false,
3  "error": "Error message",
4  "code": "ERROR_CODE",
5  "statusCode": 400
6}

Common Error Codes

UNAUTHORIZED - Missing or invalid API key

INVALID_REQUEST - Invalid request parameters

RATE_LIMITED - Rate limit exceeded

NOT_FOUND - Resource not found

SERVER_ERROR - Internal server error

PreviousError Handling Next Endpoint Index

Need more help?

Ask in our Discord or email support@conscherry.com.

Support Discord

API 1.0.0REST APIStable

API Reference

Complete documentation of all available endpoints

Base URL

Shell

https://labs.conscherry.com/api/v1

Telemetry & Attribution Headers

Note: these headers are advisory. The API key is the authoritative signal for attribution. Avoid sending PII in headers; SDKs should batch telemetry client-side before sending.

Authentication

Only the stats posting endpoint requires authentication using your API key in the Authorization header:

Shell

Authorization: Bearer YOUR_API_KEY

Public endpoints (no auth required): GET /bots, GET /bots/:id, GET /users, GET /website

Authenticated endpoints (API key required): POST /stats, GET /stats

Note: The API v1 is read-only for public data. Bot submissions and user management must be done through the authenticated web interface.

List Bots

GET/bots

Query Parameters

Parameters for listing bots
Name	Type	Required	Default	Description
limit	number	No	20 (max 100)	Number of results
offset	number	No	0 (max 5000)	Pagination offset
sort	string	No	-votes	Sort order (e.g., -votes, -guilds)
search	string	No	-	Search query
category	string	No	-	Filter by category
certified	boolean	No	-	Filter certified bots
verified	boolean	No	-	Filter verified bots
nsfw	boolean	No	-	Filter NSFW bots

Response

200 OK

JSON

1{
2  "success": true,
3  "data": [
4    {
5      "id": "123456789012345678",
6      "name": "Bot Name",
7      "description": "Short description",
8      "logo": "https://...",
9      "votes": 150,
10      "guilds": 5000,
11      "certified": false,
12      "verified": true,
13      "nsfw": false,
14      "categories": ["moderation", "fun"],
15      "owner": {
16        "id": "...",
17        "username": "Owner",
18        "avatar": "..."
19      }
20    }
21  ],
22  "pagination": {
23    "limit": 20,
24    "offset": 0,
25    "total": 245,
26    "hasMore": true
27  }
28}

Note: responses for list endpoints include Cache-Control headers for CDN caching where appropriate (e.g., /bots uses short s-maxage to enable CDN caching: s-maxage=60).

Get Website Statistics

GET/website

Get public statistics about the entire platform/website.

Response

200 OK

JSON

1{
2  "success": true,
3  "data": {
4    "bots": {
5      "total": 1234,
6      "approved": 1150,
7      "certified": 42,
8      "verified": 380
9    },
10    "users": 5678,
11    "votes": 125430,
12    "guilds": 2500000
13  }
14}

Note: the website statistics endpoint is cached for short periods to reduce load; responses include Cache-Control headers (e.g., s-maxage=120).

Get Bot by ID

GET/bots/:id

Get detailed information about a specific bot using its Discord client ID.

Response

200 OK

JSON

1{
2  "success": true,
3  "data": {
4    "id": "123456789012345678",
5    "name": "Bot Name",
6    "description": "Full description",
7    "shortDescription": "Short description",
8    "logo": "https://...",
9    "banner": "https://...",
10    "inviteUrl": "https://discord.com/oauth2/authorize?...",
11    "supportServerUrl": "https://discord.gg/...",
12    "websiteUrl": "https://...",
13    "documentationUrl": "https://docs...",
14    "githubUrl": "https://github.com/...",
15    "categories": ["moderation", "fun"],
16    "tags": ["music", "games"],
17    "prefix": "!",
18    "votes": 1500,
19    "guilds": 50000,
20    "certified": false,
21    "verified": true,
22    "partnered": false,
23    "nsfw": false,
24    "owner": {
25      "id": "...",
26      "username": "Owner",
27      "avatar": "..."
28    },
29    "averageRating": 4.5,
30    "reviewCount": 42,
31    "createdAt": "2024-01-01T00:00:00.000Z",
32    "updatedAt": "2024-01-15T10:30:00.000Z"
33  }
34}

List Users

GET/users

Query Parameters

Parameters for listing users
Name	Type	Required	Default	Description
limit	number	No	20 (max 100)	Number of results
offset	number	No	0 (max 5000)	Pagination offset
sort	string	No	-totalBots	Sort order (e.g., -totalBots, -totalVotes)
search	string	No	-	Search query

Response

JSON

1{
2  "success": true,
3  "data": [
4    {
5      "id": "123456789012345678",
6      "username": "username",
7      "avatar": "https://...",
8      "stats": {
9        "totalBots": 5,
10        "approvedBots": 4,
11        "totalVotes": 1250,
12        "totalViews": 50000,
13        "joinedAt": "2024-01-01T00:00:00.000Z"
14      }
15    }
16  ],
17  "pagination": {
18    "limit": 20,
19    "offset": 0,
20    "total": 450,
21    "hasMore": true
22  }
23}

Post Bot Statistics

POST/statsRequires auth

Request Body

JSON

1{
2  "botId": "123456789012345678", // Required: Your bot client ID
3  "guildCount": number,           // Required: Number of guilds (alias: serverCount/server_count)
4  "userCount": number,            // Required: Total unique users (alias: user_count)
5  "shardCount": number,           // Optional: Number of shards (alias: shard_count or shards[].length)
6  "uptime": number,               // Optional: Bot uptime in seconds
7  "ping": number,                 // Optional: Bot ping in milliseconds
8  "customFields": {               // Optional: Custom fields
9    "[key]": string | number
10  }
11}

Compatibility: accepts serverCount/server_count and shard_count/shards like top.gg/DBL.

Required permission: write:stats

Response

JSON

1{
2  "success": true,
3  "message": "Stats updated successfully",
4  "data": {
5    "id": "stat_01hxyz",
6    "botId": "123456789012345678",
7    "guildCount": 1200,
8    "userCount": 42000,
9    "createdAt": "2024-01-15T10:30:00Z"
10  }
11}

Get Bot Statistics

GET/statsRequires auth

Query Parameters

Parameters for fetching stats
Name	Type	Required	Default	Description
botId	string	Yes	-	Bot client ID you own
limit	number	No	10 (max 100)	Limit number of records

Required permission: read:stats or write:stats

Response

JSON

1{
2  "success": true,
3  "data": [
4    {
5      "_id": "string",
6      "botId": "123456789012345678",
7      "userId": "string",
8      "guildCount": number,
9      "userCount": number,
10      "shardCount": number,
11      "createdAt": "2024-01-15T10:30:00Z"
12    }
13  ]
14}

Error Responses

All errors follow a consistent format:

JSON

1{
2  "success": false,
3  "error": "Error message",
4  "code": "ERROR_CODE",
5  "statusCode": 400
6}

Common Error Codes

UNAUTHORIZED - Missing or invalid API key

INVALID_REQUEST - Invalid request parameters

RATE_LIMITED - Rate limit exceeded

NOT_FOUND - Resource not found

SERVER_ERROR - Internal server error

PreviousError Handling Next Endpoint Index

Need more help?

Ask in our Discord or email support@conscherry.com.

Support Discord