API Documentation

Here you can find all the various documentation for the free API we provide to allow you to interact with the ServerDex servers.

API Key

You can find your API Key under 'Edit Server' in the Dashboard. Each Server on ServerDex has a unique API Key. This means you can only query the server directly related to the API Key.

Here is an example API Key - 11aa1111-1aa1-1a11-1a11-11aa11a111a1

---

Vote Check

We provide an API endpoint that allows you to check (a callback) for the vote_id you provided to ServerDex. This will only return a vote done within the 24 hour period of UTC.

Endpoint - https://serverdex.org/api/v1/votecheck

NameValueDescriptionAdditional
keyStringAPI Key provided in 'Edit Server'. This is used to identify you accessing your server and provides security.Required
vote_idStringThe vote_id you provided to the user when they did a vote on ServerDex.Required

Successful Response

CodeBody
200
{
  "authentication": {
    "authValid": true
  },
  "vote": {
    "found": 1,
    "server": "serverdex",
    "serverdex_user": "Debaucus",
    "vote_id": "44as-234f-fdf3",
    "vote_time": "2023-06-21T06:49:57.993Z",
    "discord_id": "136684206603501578",
    "minecraft_user": "Debaucus"
  },
  "vote_claim": {
    "claimed": false
  }
}

Error Response

CodeBody
This error is designed to show you that the key parameter is missing from your API request.
400
{
  "auth": {
    "authValid": false,
    "error": {
      "code": 400,
      "message": "Missing API key",
      "url": "https://serverdex.org/docs"
    }
  }
}
This error is designed to show you that the key parameter is invalid from your API request. Please check the API key for errors.
401
{
  "auth": {
    "authValid": false,
    "error": {
      "code": 401,
      "message": "API Key Invalid.",
      "url": "https://serverdex.org/docs"
    }
  }
}
This error is designed to show you that the vote_id parameter is missing from your API request.
400
{
  "auth": {
    "authValid": true
  },
  "vote": {
    "error": {
      "code": 400,
      "message": "Missing vote_id",
      "url": "https://serverdex.org/docs"
    }
  }
}
This error is designed to show you that the vote_id parameter has no matching vote_id in our system from your API request. This most likely means the user has not voted yet.
404
{
  "auth": {
    "authValid": true
  },
  "vote": {
    "error": {
      "code": 404,
      "message": "No vote with that vote_id found for today",
      "url": "https://serverdex.org/docs"
    }
  }
}
---

Vote Claim

This endpoint is to have a second source verify that a vote has been claimed, or allow you to run a service that is serverless. You can simply send requests to our endpoints and use our database as if it were your own for tracking votes and rewarding users.

Endpoint - https://serverdex.org/api/v1/voteclaim

NameValueDescriptionAdditional
keyStringAPI Key provided in 'Edit Server'. This is used to identify you accessing your server and provides security.Required
vote_idStringThe vote_id you provided to the user when they did a vote on ServerDex.Required

Successful Response

CodeBody
200
{
  "authentication": {
    "authValid": true
  },
  "vote": {
    "found": 1,
    "serverdex_user": "Debaucus",
    "vote_id": "44as-234f-fdf3"
  },
  "vote_claim": {
    "claimed": true
  }
}

Error Response

CodeBody
403
{
  "auth": {
    "authValid": true
  },
  "vote_claim": {
    "claimed": true,
    "error": {
      "code": 403,
      "message": "Vote with ID 44as-234f-fdf3 is already claimed.",
      "url": "https://serverdex.org/docs"
    }
  }
}
This error is designed to show you that the vote_id has already been claimed from your API request.
401
{
  "auth": {
    "authValid": true
  },
  "vote_claim": {
    "error": {
      "code": 401,
      "message": "No vote with that vote_id found",
      "url": "https://serverdex.org/docs"
    }
  }
}
This error is designed to show you that the key parameter is invalid from your API request. Please check the API key for errors.
401
{
  "auth": {
    "authValid": false,
    "error": {
      "code": 401,
      "message": "API Key Invalid.",
      "url": "https://serverdex.org/docs"
    }
  }
}