---
**📚 Main Documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)
This is an individual endpoint documentation file. For the complete API reference, see the main documentation above.
---
# (DELETE) Delete tags
Permanently delete one or more tags (hard delete).
**Category:** Tags
## Endpoint

DELETE /api/tags

Delete one or more tags (hard delete). This permanently removes tags from your workspace.

Accepts an array of tag IDs to delete. All specified tags must belong to your workspace.

**Endpoint**

```text
DELETE /api/tags
```

## Authentication

Requires authentication with an API key that has the tagsWrite scope.

## Request Body

The request body must be an array of tag IDs (UUIDs) to delete.

You can delete up to 10,000 tags in a single request. Requests above 10,000 IDs are rejected.

| Parameter | Type | Required | Location | Description |
|---|---|---|---|---|
| body | array<string> | Yes | body | Array of tag IDs (UUIDs) to delete. All IDs must be valid and belong to your workspace. |

> **Warning: Request Size**
> Ensure the request body contains at least one valid tag ID.

## Status Codes

### 200

Tags deleted successfully.

**Request**

```bash
curl -X DELETE "https://hoko.to/api/tags" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    "550e8400-e29b-41d4-a716-446655440000"
  ]'
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    "550e8400-e29b-41d4-a716-446655440000"
  ])
});
const result = await response.json();
```

**Response**

```json
{
  "deletedIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

### 400

Invalid request body (missing IDs, invalid UUIDs, or IDs not found in your workspace).

**Request**

```bash
curl -X DELETE "https://hoko.to/api/tags" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    "invalid-id"
  ]'
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    "invalid-id"
  ])
});
```

**Response**

```json
{
  "error": {
    "en": "Invalid request",
    "ar": "طلب غير صالح"
  }
}
```

### 401

Invalid or missing API key.

**Request**

```bash
curl -X DELETE "https://hoko.to/api/tags" \
  -H "Authorization: Bearer invalid_key"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer invalid_key"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Invalid API key",
    "ar": "مفتاح API غير صالح"
  }
}
```

### 403

API key does not have the required tagsWrite scope.

**Request**

```bash
curl -X DELETE "https://hoko.to/api/tags" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Missing required scopes",
    "ar": "الصلاحيات المطلوبة مفقودة"
  },
  "missingScopes": ["tagsWrite"]
}
```

### 429

Rate limit exceeded. Check X-RateLimit-* headers for details.

**Request**

```bash
curl -X DELETE "https://hoko.to/api/tags" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Rate limit exceeded",
    "ar": "تم تجاوز حد المعدل"
  },
  "retryAfter": 60
}
```

## Examples

**Request**

```bash
curl -X DELETE "https://hoko.to/api/tags" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    "550e8400-e29b-41d4-a716-446655440000"
  ]'
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    "550e8400-e29b-41d4-a716-446655440000"
  ])
});
const result = await response.json();
```

**Response**

```json
{
  "deletedIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

> **Warning: Permanent Action**
> Deleted tags cannot be restored. This is a hard delete operation that permanently removes tags from your workspace. Links that had these tags will no longer have those tag associations.

---

**Back to main documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)