---
**📚 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.
---
# (PUT) Update/Upsert tags
Update existing tags or create new ones with upsert operations.
**Category:** Tags
## Endpoint

PUT /api/tags

Upsert (update or insert) one or more tags. If id is provided, the tag is updated. If the ID does not exist, the request fails. To create new tags, omit the id field.

This endpoint is useful for synchronization scenarios where you want to ensure tags exist with specific properties.

**Endpoint**

```text
PUT /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. Include the id field to update an existing tag, or omit it to create a new one.

You can upsert 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 |
|---|---|---|---|---|
| id | string (UUID) | Yes | body | Required when updating. Omit to create a new tag. If provided, it must exist in your workspace or the request fails. |
| name | string | No | body | The name of the tag. Required when creating a new tag (no id). Optional when updating. |
| color | string | No | body | The color of the tag. Optional. Defaults to \"slate\" when creating a new tag. |

> **Info: Update Behavior**
> When updating, only the fields you include are changed. Omitted fields keep their current values. For new tags (no id), color defaults to \"slate\" if omitted.

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

### 200

Tags updated or created successfully.

**Request**

```bash
curl -X PUT "https://hoko.to/api/tags" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Updated Tag",
      "color": "green"
    }
  ]'
```

**Request**

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

**Response**

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

### 400

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

**Request**

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

**Request**

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

**Response**

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

### 401

Invalid or missing API key.

**Request**

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

**Request**

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

**Request**

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

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags", {
  method: "PUT",
  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 PUT "https://hoko.to/api/tags" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Updated Tag",
      "color": "green"
    }
  ]'
```

**Request**

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

**Response**

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

---

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