# Bans API

## Add a Ban

<mark style="color:green;">`POST`</mark> `https://api.ksoft.si/bans/add`

This endpoint allows you to add bans to the list. If you don't have `BAN_MANAGER` permission your ban will be automatically converted to a ban report and we will take a look and act accordingly.

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

#### Request Body

| Name                | Type    | Description                                     |
| ------------------- | ------- | ----------------------------------------------- |
| user                | number  | Users Discord ID that you are banning/reporting |
| mod                 | number  | Users Discord ID who posted/reported the ban    |
| user\_name          | string  | Users Discord username                          |
| user\_discriminator | number  | Users Discord discriminator                     |
| reason              | string  | Reason why user should be globally banned       |
| proof               | string  | URL of the image showing the act                |
| appeal\_possible    | boolean | If appeal should be disabled for that user.     |

{% tabs %}
{% tab title="200 Ban was successfully recorded." %}

```javascript
{"success": true}
```

{% endtab %}

{% tab title="400 Errors that are the cause of badly formatted form data." %}

```javascript
{"code": 123, "error": true, "message": "missing required parameters"}
or
{"code": 124, "error": true, "message": "appeal_possible got invalid value"}
or
{"code": 124, "error": true, "message": "one of parameters got invalid value"}
```

{% endtab %}

{% tab title="409 This user is already banned." %}

```javascript
{
    "code":125,
    "error":true,
    "exists":true,
    "message":"User with this id is already on the list."
}
```

{% endtab %}
{% endtabs %}

## Get ban info

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/bans/info`

Get more information about a ban

#### Query Parameters

| Name | Type   | Description                                    |
| ---- | ------ | ---------------------------------------------- |
| user | number | Users Discord ID who's ban you'd like to check |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 This is returned if ban is found" %}

```javascript
{
    "id": "555393235682459669",
    "name": "Phantom",
    "discriminator": "9222",
    "moderator_id": "286509757546758156",
    "reason": "DM Ads",
    "proof": "https://i.imgur.com/kgMaK4I.png",
    "is_ban_active": true,
    "can_be_appealed": true,
    "timestamp": "2020-02-11T08:30:52.640887",
    "appeal_reason": null,
    "appeal_date": null,
    "requested_by": "286509757546758156",
    "exists": true
}
```

{% endtab %}

{% tab title="404 This is returned when the ban is not found." %}

```javascript
{
    "code": 404,
    "error": true,
    "exists": false,
    "message": "specified user does not exist"
}
```

{% endtab %}
{% endtabs %}

## Check user

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/bans/check`

Simple way to check if the user is banned

#### Query Parameters

| Name | Type   | Description                               |
| ---- | ------ | ----------------------------------------- |
| user | number | Users Discord ID that you'd like to check |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 It returns true or false" %}

```javascript
{
    "is_banned": true
}
```

{% endtab %}
{% endtabs %}

## Delete ban

<mark style="color:red;">`DELETE`</mark> `https://api.ksoft.si/bans/delete`

Delete a ban, only users with `BAN_MANAGER` permission can use this.

#### Query Parameters

| Name  | Type    | Description                                                                            |
| ----- | ------- | -------------------------------------------------------------------------------------- |
| user  | number  | Users Discord ID                                                                       |
| force | boolean | Default: false, if true it deletes the entry from the database instead of deactivating |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 If successful" %}

```javascript
{"done": true}
```

{% endtab %}

{% tab title="401 If you don't have BAN\_MANAGER permission" %}

```javascript
{"code": 401, "error": True, "message": "you are not authorized to remove users"}
```

{% endtab %}
{% endtabs %}

## List of bans

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/bans/list`

Pagination of bans, you can request up to 1000 records per page, default is 20.

#### Query Parameters

| Name      | Type    | Description                           |
| --------- | ------- | ------------------------------------- |
| page      | integer | Page number (default: 1)              |
| per\_page | integer | Number of bans per page (default: 20) |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "ban_count": 1592,
    "page_count": 531,
    "per_page": 3,
    "page": 1,
    "on_page": 3,
    "next_page": 2,
    "previous_page": null,
    "data": [
        {
            "id": "555393235682459669",
            "name": "Phantom",
            "discriminator": "9222",
            "moderator_id": "286509757546758156",
            "reason": "DM Ads",
            "proof": "https://i.imgur.com/kgMaK4I.png",
            "is_ban_active": true,
            "can_be_appealed": true,
            "timestamp": "2020-02-11T08:30:52.640887",
            "appeal_reason": null,
            "appeal_date": null
        },
        {
            "id": "661958388942503938",
            "name": "VPParrot",
            "discriminator": "2708",
            "moderator_id": "223456683337318402",
            "reason": "unsolicited dm ads",
            "proof": "https://i.imgur.com/klI6s35.png",
            "is_ban_active": true,
            "can_be_appealed": true,
            "timestamp": "2020-02-10T18:59:58.412203",
            "appeal_reason": null,
            "appeal_date": null
        },
        {
            "id": "578377795151855616",
            "name": "MomHunter",
            "discriminator": "2067",
            "moderator_id": "286509757546758156",
            "reason": "DM ads",
            "proof": "https://i.imgur.com/cXlzCod.jpg",
            "is_ban_active": true,
            "can_be_appealed": true,
            "timestamp": "2020-02-10T21:49:25.164282",
            "appeal_reason": null,
            "appeal_date": null
        }
    ]
}
```

{% endtab %}

{% tab title="400 Errors that you can get" %}

```javascript
{
    "error": true,
    "code": 666,
    "message": "you are evil, you cannot get more than 1000 results per page"
}
or
{
    "code": 124,
    "error": true,
    "message": "per_page parameter got invalid value"
}
or
{
    "code": 124,
    "error": true,
    "message": "page parameter got invalid value"
}
```

{% endtab %}
{% endtabs %}

## Ban updates

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/bans/updates`

Gets updates from the previous update

#### Query Parameters

| Name      | Type   | Description                                     |
| --------- | ------ | ----------------------------------------------- |
| timestamp | number | timestamp in seconds from 1.1.1970 (epoch time) |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "data": [
        {
            "id": 307898291000049684,
            "reason": "DM Advertising",
            "proof": "https://xignotic.is-going-to-rickroll.me/i/Bzx58zHJDuV7Jg.png",
            "moderator_id": 205680187394752512,
            "active": true
        },
        {
            "id": 448253132003344384,
            "reason": "Server Raiding. ",
            "proof": "https://imgur.com/a/S4Eosul",
            "moderator_id": 205680187394752512,
            "active": true
        }
    ],
    "current_timestamp": 1537800258 //store this value for the next update
}
```

{% endtab %}
{% endtabs %}