# BanAPI Documentation

{% hint style="danger" %}
This documentation is relatively the same for v2.0.0 of the SentinelAPI, however to index/call a method properly in the BanAPI you must call it as `SentinelAPI.BanAPI:method(...)`, an example would be: `SentinelAPI.BanAPI:BanAsync(...)`
{% endhint %}

This document provides an in-depth overview of the `SentinelAPI` module, which serves as the backbone for managing bans, unbans, and other moderation-related features in Sentinel. The API interacts with Roblox services and Sentinel Open Cloud API endpoints to enforce moderation effectively.

***

### Module Overview **Dependencies**:

* `Config`: Configuration settings for Sentinel.
* `Types`: Type definitions used across Sentinel.
* `Enum`: Enum definitions for ban types and lengths.
* `RichBan`: Helper functions for advanced ban features.

***

### SentinelAPI Methods

#### 1. **BanAsync**

Bans a player from the experience.

**Signature**:

```lua
function BanAsync(Player: Player, BanConfig: types.BanConfig): boolean
```

**Parameters**:

* `Player`: The `Player` instance to ban.
* `BanConfig`: A table with configuration details (see `BanConfig` type).

**Returns**:\
`boolean` - Whether the ban was successful.

**Example**:

```lua
SentinelAPI:BanAsync(player, {
    Moderator = 12345,
    BanType = "Global",
    BanLengthType = "Permanent",
    PublicReason = "Violation of rules",
    PrivateReason = "Severe offense",
    BanUniversal = true,
})
```

***

#### 2. **OfflineBanAsync**

Bans a user by their UserId, even if they are offline.

**Signature**:

```lua
function OfflineBanAsync(UserId: number, BanConfig: types.BanConfig): boolean
```

**Parameters**:

* `UserId`: The Roblox UserId to ban.
* `BanConfig`: A table with ban details (see `BanConfig` type).

**Returns**:\
`boolean` - Whether the ban was successful.

***

#### 3. **BatchBanAsync**

Bans multiple players at once.

**Signature**:

```lua
function BatchBanAsync(PlayerList: {Player}, BanConfig: types.BanConfig): (boolean, number, number)
```

**Parameters**:

* `PlayerList`: A list of `Player` instances to ban.
* `BanConfig`: Ban configuration details.

**Returns**:

* `boolean`: Whether all bans were successful.
* `number`: Count of successful bans.
* `number`: Count of failed bans.

***

#### 4. **BatchOfflineBanAsync**

Bans multiple users by their UserIds.

**Signature**:

```lua
function BatchOfflineBanAsync(UserIds: {number}, BanConfig: types.BanConfig): (boolean, number, number)
```

**Parameters**:

* `UserIds`: List of UserIds to ban.
* `BanConfig`: Ban configuration details.

**Returns**:

* `boolean`: Whether all bans were successful.
* `number`: Count of successful bans.
* `number`: Count of failed bans.

***

#### 5. **UnbanAsync**

Unbans a user by their UserId.

**Signature**:

```lua
function UnbanAsync(UserId: number, Reason: string): boolean
```

**Parameters**:

* `UserId`: The UserId to unban.
* `Reason`: Reason for the unban.

**Returns**:\
`boolean` - Whether the unban was successful.

***

#### 6. **IsPlayerBanned**

Checks if a player is banned.

**Signature**:

```lua
function IsPlayerBanned(Player: Player): boolean
```

**Parameters**:

* `Player`: The `Player` instance to check.

**Returns**:\
`boolean` - Whether the player is banned.

***

#### 7. **IsUserIdBanned**

Checks if a UserId is banned.

**Signature**:

```lua
function IsUserIdBanned(UserId: number): boolean
```

**Parameters**:

* `UserId`: The UserId to check.

**Returns**:\
`boolean` - Whether the UserId is banned.

***

#### 8. **GetPendingBans**

Retrieves the list of pending bans.

**Signature**:

```lua
function GetPendingBans(): types.BanList?
```

**Returns**:

* `types.BanList?`: A list of pending bans or `nil` if an error occurs.

***

#### 9. **GetPendingUnbans**

Retrieves the list of pending unbans.

**Signature**:

```lua
function GetPendingUnbans(): types.BanList?
```

**Returns**:

* `types.BanList?`: A list of pending unbans or `nil` if an error occurs.

***

#### 10. **ProccessPendingBans**

Processes all pending bans and applies them.

**Signature**:

```lua
function ProccessPendingBans(): void
```

***

#### 11. **ProccessPendingUnbans**

Processes all pending unbans and applies them.

**Signature**:

```lua
function ProccessPendingUnbans(): void
```

***

#### 12. **ReplicateUpdatedBan**

Updates and replicates a ban.

**Signature**:

```lua
function ReplicateUpdatedBan(UserId: number, BanConfig: types.BanConfig): boolean
```

**Parameters**:

* `UserId`: The UserId to update the ban for.
* `BanConfig`: Updated ban configuration.

**Returns**:\
`boolean` - Whether the update was successful.

***

### Error Handling

Errors during API calls (e.g., HTTP requests) are logged with `warn` statements when `Config.DEBUG_INFO_ENABLED` is true. Developers should monitor the output for warnings if operations fail.

***

### Example Workflow

1. Ban a player temporarily:

   ```lua
   SentinelAPI:BanAsync(player, {
       Moderator = 12345,
       BanType = "Experience",
       BanLengthType = "Temporary",
       BanLength = "1d",
       PublicReason = "Spamming",
       PrivateReason = "Chat abuse",
       BanUniversal = false,
   })
   ```
2. Unban a player:

   ```lua
   SentinelAPI:UnbanAsync(12345678, "Appeal accepted.")
   ```
3. Process all pending bans:

   ```lua
   SentinelAPI:ProccessPendingBans()
   ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sentineldocs.metatable.dev/luau-sdk/banapi-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.