Getting Started

The very first thing you will need is an API key! You can sign up for one for free right here

ALL requests to the API MUST be sent with the header of "AuthKey":"your api key" or you will be given a 401 error (HTTP Unauthorized). All endpoints return a JSON response, in one of two formats: For a successful response, it will give a status of success, a code of 200, and a data block, with the result object for the endpoint (specifics for each endpoint can be found in the endpoints tab).

For example:
{"status": "success", "code": "200", "data": {"result": 5}, "remaining": 45}
An error will provide a status of error, along with an appropriate error code, and a description in most cases. For some errors additional information will also be sent, such as if you are sending requests too fast, or if you are out of request 'points' for the current time allotment.

For example:
{"status": "error", "code": "401", "desc": "you need to specify your api key"}
In addition to the above, all successful payloads will also have a "remaining" field at the end, specifying how many more calls to the API you have left available. The "points bucket" resets each night at 00:00 (midnight) EST.


API Endpoints

Unless otherwise stated, it is safe to assume that the endpoint you are trying to use, uses the GET method, with you API key assigned to the AuthKey header.

The Endpoints are:

List Endpoint

This will return a list of all available endpoints in the following format:

{"status": "success","code": "200","data": {"result": {"list": "get a list of api actions","random": "get a random number"}}, "remaining": 985}

Random Endpoint

This returns n number of numbers between min and max as specified in the endpoint call. As an example, with a query of ?action=random&n=5&min=1&max=1000 we got:

{"status": "success","code": "200","data": {"result": [273,90,46,328,520]}, "remaining": 476}
What this breaks down to is five numbers (n=5) with a minimum value of 1 (min=1) and a max value of 1000 (max=1000).

If you do not specify any parameters, the API assumes one number (n=1) between 1 (min=1) and 6 (max=6), which would be a default 6-sided die roll. You can specify only one or two parameters as well, such as specifying a min and max, but no amount, and the API will assume those default values for any parameters not specified.

  • ?action=random&n=5 - This will give you five numbers between 1 and 6
  • ?action=random&max=20 - This gives you a single number between 1 and 20 (commonly known as a d20).
  • ?action=random&n=6&max=20 - This gives you 6 d20 (see point above)

Images Endpoint

Grabs a random image from the specified category! If you do not specify a category, it will return a list of the categories available to choose from. Current Categories are:

  • cat
  • dog
  • bird
A successful response will look like the following:
{"status": "success","code": "200","data": {"result": ""},"remaining": 988}

WordGen Endpoint

This endpoint takes a single parameter (level), and selects a random word from a list of the top 3,000 most commonly used words in the English dictionary, and sends it to you as both the word, and the word after being shuffled. It will also return the level that the word is considered (easy, medium, or hard). If you specify the level parameter, you will get a word from that level/difficulty. If you do not specify the level desired, it will randomly select any word from the list, regardless of level. An example response using the query of gives a result of:

{"status": "success","code": "200","data": {"result": {"word": "FRONT","shuffled": "ONFTR","level": "medium"}},"remaining": 990}

Bancheck Endpoint

This will allow you to check a known (discord) user ID against the global banlist. If the user is not on the list, you will get a message similar to the following:

{"status": "success","code": "200","data": {"result": {"banned": false}},"remaining": 991}
Whereas if the user is listed, you will get a response similar to:
{"status": "success","code": "200","data": {"result": {"banned": true,"reason": "Server Raiding","date": "Sep 5th 2019, 9:35:17 am","proof": ""}},"remaining": 990}