---
**📚 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.
---
# (GET) Get collections
Retrieve collections from your workspace. Filter by collection ID or list all collections with pagination.
**Category:** Collections
## Endpoint

GET /api/collections

Retrieve collections from your workspace. Filter by collection ID to get specific collections, or omit the filter to retrieve all collections with pagination support.

Use this endpoint to list your collections, verify collection existence before creating links, or build collection management interfaces.

**Endpoint**

```text
GET /api/collections
```

## Authentication

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

## Query Parameters

| Parameter | Type | Required | Location | Description |
|---|---|---|---|---|
| id | string (UUID) | No | query | Filter by specific collection ID. Returns a single collection if found. |
| take | number | No | query | Number of results to return (default: 50, min: 1, max: 10,000). |
| skip | number | No | query | Number of results to skip for pagination (default: 0, min: 0). |
| sort | string | No | query | Sort order by createdAt: "asc" for oldest first, "desc" for newest first (default: "desc"). |

> **Warning: Request Limits**
> The `take` parameter supports values from 1 to 10,000. Requests above 10,000 are rejected.

## Status Codes

### 200

Successfully retrieved collections.

**Request**

```bash
curl -X GET "https://hoko.to/api/collections?take=50&sort=desc" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/collections?take=50&sort=desc", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
```

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Campaigns",
    "description": "All marketing links",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]
```

### 401

Invalid or missing API key.

**Request**

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

**Request**

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

**Response**

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

### 403

API key does not have the required collectionsRead scope.

**Request**

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

**Request**

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

**Response**

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

### 429

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

**Request**

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

**Request**

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

**Response**

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

## Examples

**Request**

```bash
curl -X GET "https://hoko.to/api/collections?take=50&sort=desc" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/collections?take=50&sort=desc", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
const collections = await response.json();
```

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Campaigns",
    "description": "All marketing links",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]
```

---

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