---
**📚 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 links
Delete one or more links using soft delete. Historical analytics data is preserved.
**Category:** Links
## Endpoint

DELETE /api/links

Delete one or more links using soft delete. Soft delete marks links as deleted without permanently removing them from the database, allowing for potential recovery and maintaining referential integrity.

Accepts an array of link IDs to delete. All specified links must belong to your workspace. The endpoint returns the IDs of successfully deleted links.

Deleted links are no longer accessible via the API and will not appear in GET requests, but historical analytics data associated with these links is preserved.

**Endpoint**

```text
DELETE /api/links
```

## Authentication

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

## Request Body

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

You can delete up to 10,000 links in a single request. However, the actual maximum may be lower based on your subscription plan limits and available resources.

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

> **Warning: Request Size**
> You can delete up to 10,000 links in a single request. Requests above 10,000 IDs are rejected.

## Status Codes

### 200

Links deleted successfully.

**Request**

```bash
curl -X DELETE "https://hoko.to/api/links" \
  -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/links", {
  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/links" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    "invalid-id"
  ]'
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/links", {
  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/links" \
  -H "Authorization: Bearer invalid_key"
```

**Request**

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

**Response**

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

### 403

API key does not have the required linksWrite scope.

**Request**

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

**Request**

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

**Response**

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

### 429

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

**Request**

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

**Request**

```javascript
const response = await fetch("https://hoko.to/api/links", {
  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/links" \
  -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/links", {
  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 links cannot be restored through the API. While the data is preserved for analytics purposes, the links themselves are no longer accessible. Ensure you have backups or exports before performing bulk deletions.

---

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