# Blacklists

Blacklist routes fetch and remove local or key blacklist entries from a hub. Global blacklists are managed by LuaProt.

## Get Blacklists

**`GET`** `/api/v1/hubs/:hubId/blacklists/get`

#### Params

| Param | Description                      |
| ----- | -------------------------------- |
| hubId | Hub ID to fetch blacklists from. |

#### Query

| Query | Description                                         |
| ----- | --------------------------------------------------- |
| hwid  | Optional HWID search. Partial matches are accepted. |

#### Response

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

```json
{
  "success": true,
  "message": "Successfully fetched blacklists.",
  "blacklists": [
    {
      "id": "global:f43fh34ui43huer3",
      "entryId": "f43fh34ui43huer3",
      "type": "Global",
      "hwid": "589401805431295092384985734",
      "reason": "Global blacklist reason",
      "key": null,
      "discordId": "123456789012345678",
      "created": 1769473337
    },
    {
      "id": "key:84c370d09e13438149d705c4",
      "entryId": "84c370d09e13438149d705c4",
      "type": "Key",
      "hwid": "589401805431295092384985734",
      "reason": "Local key reason",
      "key": "73978994376e1f3e307914c4",
      "discordId": "123456789012345678",
      "created": 1769473337
    }
  ]
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "success": false,
  "message": "Hub not found or linked to your account."
}
```

{% endtab %}
{% endtabs %}

## Delete Blacklist

**`DELETE`** `/api/v1/hubs/:hubId/blacklists/delete`

#### Params

| Param | Description                      |
| ----- | -------------------------------- |
| hubId | Hub ID the blacklist belongs to. |

#### Query

| Query | Description                                                                                     |
| ----- | ----------------------------------------------------------------------------------------------- |
| type  | `key` or `local`. `global` is accepted by the validator but cannot be deleted through this API. |
| id    | The `entryId` returned by Get Blacklists.                                                       |

{% hint style="warning" %}
Global blacklists are managed by LuaProt. A local or key blacklist that matches a global blacklist is also protected from deletion.
{% endhint %}

#### Response

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

```json
{
  "success": true,
  "message": "Blacklist removed successfully."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "success": false,
  "message": "Global blacklists are managed by LuaProt."
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "success": false,
  "message": "Blacklist entry not found."
}
```

{% endtab %}
{% endtabs %}

## Clear Blacklists

**`DELETE`** `/api/v1/hubs/:hubId/blacklists/clear`

#### Params

| Param | Description                      |
| ----- | -------------------------------- |
| hubId | Hub ID to clear blacklists from. |

{% hint style="warning" %}
Global blacklists are not removed. Local or key blacklists that match an active global blacklist are kept protected.
{% endhint %}

#### Response

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

```json
{
  "success": true,
  "message": "Blacklists cleared successfully.",
  "cleared": {
    "keys": 3,
    "locals": 2,
    "globals": 0
  }
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "success": false,
  "message": "Hub not found or linked to your account."
}
```

{% endtab %}
{% endtabs %}


---

# 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://docs.luaprot.net/luaprot/api-documentation/blacklists.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.