{"openapi":"3.1.0","info":{"title":"DiscoListing API","version":"1.0.0","description":"Server and bot lookups return all approved listings, including adult listings marked nsfw: true without a key: 60 requests/minute per IP, even when a key is supplied. Vote checks, vote history and bot stats updates require a listing API key: 120 requests/minute per key. Rate-limit responses return 429 with Retry-After in seconds."},"servers":[{"url":"https://discolisting.com"}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"Listing API key from Dashboard → Integrations (lst_…)"}},"schemas":{"Server":{"type":"object","properties":{"id":{"type":"string","description":"Listing ID"},"guildId":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"shortDescription":{"type":"string"},"url":{"type":"string","format":"uri"},"inviteUrl":{"type":["string","null"],"format":"uri"},"iconUrl":{"type":["string","null"],"format":"uri"},"memberCount":{"type":"integer"},"onlineCount":{"type":"integer"},"qualityScore":{"type":"number"},"votes30d":{"type":"integer"},"tags":{"type":"array","items":{"type":"string"}},"category":{"type":"string"},"languages":{"type":"array","items":{"type":"string"}},"nsfw":{"type":"boolean"}},"required":["id","guildId","slug","name","shortDescription","url","inviteUrl","iconUrl","memberCount","onlineCount","qualityScore","votes30d","tags","category","languages","nsfw"]},"Error":{"type":"object","properties":{"error":{"type":"string","example":"Invalid API key"}},"required":["error"]},"Bot":{"type":"object","properties":{"id":{"type":"string","description":"Listing ID"},"botId":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"shortDescription":{"type":"string"},"url":{"type":"string","format":"uri"},"inviteUrl":{"type":"string","format":"uri"},"iconUrl":{"type":["string","null"],"format":"uri"},"serverCount":{"type":"integer"},"shardCount":{"type":"integer"},"statsUpdatedAt":{"type":["string","null"],"format":"date-time"},"qualityScore":{"type":"number"},"votes30d":{"type":"integer"},"tags":{"type":"array","items":{"type":"string"}},"prefix":{"type":["string","null"]},"nsfw":{"type":"boolean"}},"required":["id","botId","slug","name","shortDescription","url","inviteUrl","iconUrl","serverCount","shardCount","statsUpdatedAt","qualityScore","votes30d","tags","prefix","nsfw"]},"VoteCheck":{"type":"object","properties":{"voted":{"type":"boolean"},"votedAt":{"type":["string","null"],"format":"date-time"},"nextVoteAt":{"type":["string","null"],"format":"date-time"},"cooldownHours":{"type":"integer"}},"required":["voted","votedAt","nextVoteAt","cooldownHours"]},"VoteList":{"type":"object","properties":{"votes":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"votedAt":{"type":"string","format":"date-time"}},"required":["userId","votedAt"]}}},"required":["votes"]},"BotStats":{"type":"object","properties":{"serverCount":{"type":"integer"},"shardCount":{"type":"integer"}},"required":["serverCount","shardCount"]},"BotStatsInput":{"type":"object","properties":{"serverCount":{"type":"integer","minimum":0,"maximum":100000000},"shardCount":{"type":"integer","minimum":1,"maximum":100000},"shardId":{"type":"integer","minimum":0,"maximum":100000}},"required":["serverCount"]}},"parameters":{}},"paths":{"/api/v1/servers/{id}":{"get":{"tags":["Servers"],"summary":"Get a listed server","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Discord ID, listing ID or slug","example":"123456789012345678"},"required":true,"description":"Discord ID, listing ID or slug","name":"id","in":"path"}],"responses":{"200":{"description":"Server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/bots/{id}":{"get":{"tags":["Bots"],"summary":"Get a listed bot","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Discord ID, listing ID or slug","example":"123456789012345678"},"required":true,"description":"Discord ID, listing ID or slug","name":"id","in":"path"}],"responses":{"200":{"description":"Bot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bot"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/votes/check":{"get":{"tags":["Votes"],"summary":"Has a user voted recently?","description":"True when the Discord user voted for the listing that owns the API key within the current cooldown window.","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{17,20}$","description":"Discord user ID","example":"123456789012345678"},"required":true,"description":"Discord user ID","name":"userId","in":"query"}],"responses":{"200":{"description":"Vote status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoteCheck"}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/votes":{"get":{"tags":["Votes"],"summary":"Recent votes","description":"Newest first. Paginate with `before` (the `votedAt` of the last item).","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"before","in":"query"}],"responses":{"200":{"description":"Votes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoteList"}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stats":{"post":{"tags":["Bots"],"summary":"Post bot stats","description":"Report your bot server count. Sharded bots can post per shard with `shardId` and `shardCount`; the total is the sum of shard reports from the last 24 hours. Post at most once a minute per shard.","security":[{"ApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotStatsInput"}}}},"responses":{"200":{"description":"Stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotStats"}}}},"400":{"description":"Invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too often","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}