---
**📚 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.
---
# (POST) Create collections
Create one or more collections to organize your links. Each collection requires a name.
**Category:** Collections
## Endpoint

POST /api/collections

Create one or more collections to organize your links. Collections are essential organizational units—every link must belong to a collection.

Each collection requires a name for identification. Optionally include a description to provide additional context about the collection's purpose or contents.

You can create multiple collections in a single request by providing an array of collection objects, making it easy to set up your organizational structure quickly.

**Endpoint**

```text
POST /api/collections
```

## Authentication

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

## Request Body

The request body must be an array of collection objects. Each object represents one collection to create.

You can create up to 10,000 collections 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 |
|---|---|---|---|---|
| name | string | Yes | body | The name of the collection. Used for identification and organization. Choose descriptive names that clearly indicate the collection's purpose. |
| description | string | No | body | Optional description providing additional context about the collection. Useful for documentation and team collaboration. |

> **Warning: Plan Limits**
> The actual maximum number of collections you can create per request may be lower than 10,000 based on your subscription plan limits and available resources. The system will enforce both the hard limit (10,000) and your plan-specific limits.

## Status Codes

### 201

Collections created successfully.

**Request**

```bash
curl -X POST "https://hoko.to/api/collections" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
      {
        "name": "Marketing Campaigns"
      }
    ]'
```

**Request**

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

**Response**

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

### 400

Invalid request body (missing required fields or invalid values).

**Request**

```bash
curl -X POST "https://hoko.to/api/collections" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
      {}
    ]'
```

**Request**

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

**Response**

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

### 401

Invalid or missing API key.

**Request**

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

**Request**

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

**Response**

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

### 403

API key does not have the required collectionsWrite scope.

**Request**

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

**Request**

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

**Response**

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

### 429

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

**Request**

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

**Request**

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

**Response**

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

## Examples

**Request**

```bash
curl -X POST "https://hoko.to/api/collections" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "Marketing Campaigns",
      "description": "All marketing campaign links"
    }
  ]'
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/collections", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {
      name: "Marketing Campaigns",
      description: "All marketing campaign links"
    }
  ])
});
const collections = await response.json();
```

**Response**

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

> **Info: Collection Requirements**
> Every link must belong to a collection. Create collections before creating links, or ensure the collectionId you reference in link creation requests exists in your workspace.

---

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