---
**📚 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 tags
Create one or more tags. Each tag requires a name, and color is optional.
**Category:** Tags
## Endpoint

POST /api/tags

Create one or more tags. Accepts an array of tag objects.

Each tag requires a name. Color is optional (defaults to "slate").

**Endpoint**

```text
POST /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 objects. Each object represents one tag to create.

You can create up to 10,000 tags 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 tag. Choose descriptive names that clearly indicate the tag's purpose. |
| color | string | No | body | The color of the tag. Must be one of the available color values (default: "slate"). |

> **Warning: Plan Limits**
> The actual maximum number of tags 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

Tags created successfully.

**Request**

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

**Request**

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

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing",
    "color": "blue"
  }
]
```

### 400

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

**Request**

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

**Request**

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

**Response**

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

### 401

Invalid or missing API key.

**Request**

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

**Request**

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

**Request**

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

**Request**

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

**Response**

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

## Examples

### Available Colors
Type: color

- slate
- gray
- zinc
- neutral
- stone
- red
- orange
- amber
- yellow
- lime
- green
- emerald
- teal
- cyan
- sky
- blue
- indigo
- violet
- purple
- fuchsia
- pink
- rose

**Request**

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

**Request**

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

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing",
    "color": "blue"
  }
]
```

---

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