Skip to main content

Usage

Endpoint for greylist checking-adding-removing​

Endpoints related to adding-removing-checking a greylisted address.

  • POST api.bitninja.io/api/addIpToGreylist
  • POST api.bitninja.io/api/deleteIpToGreylist
  • POST api.bitninja.io/api/checkIpOnGreylist

Common details shared between ALL endpoints​

They all require a JWT token for authorization. This will require the license key you can see at https://admin.bitninja.io/main

If we include a "result_mode=json" GET parameter, the result will be in json, that will look like this:

{ result: string }

PHP status code does NOT change even if validation fails or the action fails. It will always return 200.

Before every action carried out, the API will check if it is indeed a PUBLIC valid IPV4 address or not.

The limits are as follows:

  • Greylist additions/day: 6000.
  • Greylist removals /day: 1000.
tip

The API will NOT forward the request if the IP is on our global whitelist (e.g. BitNinja's API IP addresses)

Common responses among all endpoints​

If the IP is invalid:

{result: "[1.2.3.4] is invalid"}

If the IP is private:

{result: "[1.2.3.4] is private"}

If you exceed a limit:

{result: "Sorry, but you have reached the maximum limit"}

Greylist operations​

Checking​

POST api.bitninja.io/api/checkIpOnGreylist?result_mode=json (POST Parameters: IP)

Example Responses​

If the IP is NOT greylisted:

{"result": "[1.2.3.4] is currently not on global greylist"}

If the IP is on user-level greylist:

{"result": "[1.2.3.4] is currently on your personal greylist"}

If it is greylisted:

{"result": "[1.2.3.4] is on global greylist"}

Example CURL request​

curl --location --request POST 'https://api.bitninja.io/api/checkIpOnGreylist?result_mode=json' --header 'Authorization: Bearer <jwt_token>' --form 'ip="1.2.3.4"'

Adding​

POST api.bitninja.io/api/addIpToGreylist?result_mode=json (POST Parameters: IP)

Example Responses​

If the IP is already on user-level greylist:

{"result": "[1.2.3.4] is already on your greylist"}

If the IP is on global greylist:

{"result": "[1.2.3.4] is already on global greylist"}

If the IP was successfully added to the greylist:

{"result": "[1.2.3.4] has been added to greylist"}

Example CURL request​

curl --location --request POST 'https://api.bitninja.io/api/addIpToGreylist?result_mode=json' --header 'Authorization: Bearer <jwt_token>' --form 'ip="1.2.3.4"'

Removing​

POST api.bitninja.io/api/deleteIpFromGreylist?result_mode=json (POST Parameters: IP)

Example Responses​

If the IP is not on greylist:

{"result": "[1.2.3.4] is not on greylist"}

If the IP has been successfully removed:

{"result": "[1.2.3.4] has been removed from greylist"}

Example CURL request​

curl --location --request POST 'https://api.bitninja.io/api/deleteIpFromGreylist?result_mode=json' --header 'Authorization: Bearer <jwt_token>'  --form 'ip="1.2.3.4"'