> For the complete documentation index, see [llms.txt](https://sentineldocs.metatable.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sentineldocs.metatable.dev/luau-sdk/banapi-documentation.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.