Categories organize blog posts into logical groups for navigation and filtering.

## List Blog Categories

```
GET /api/v1/blog-categories
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 50 | Categories per page (1-100) |
| `offset` | `number` | 0 | Categories to skip |
| `query` | `string` | – | Search by name or slug |
| `active` | `boolean` | – | Filter by active status |

### Response

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "storeId": "store-123",
      "name": "Tutorials",
      "slug": "tutorials",
      "description": "Step-by-step guides and how-tos",
      "image": "https://cdn.example.com/tutorials.jpg",
      "position": "0|aaaaaa:",
      "active": true,
      "seo": {},
      "createdAt": "2024-01-10T08:30:00.000Z",
      "updatedAt": "2024-01-10T08:30:00.000Z",
      "postCount": 5
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 50
  }
}
```

---

## Get Blog Category

```
GET /api/v1/blog-categories/:idOrSlug
```

Returns a single blog category by UUID or slug.

### Response

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "storeId": "store-123",
  "name": "Tutorials",
  "slug": "tutorials",
  "description": "Step-by-step guides and how-tos",
  "image": "https://cdn.example.com/tutorials.jpg",
  "position": "0|aaaaaa:",
  "active": true,
  "seo": {
    "title": "Tutorials - Our Blog",
    "description": "Browse our tutorial articles"
  },
  "createdAt": "2024-01-10T08:30:00.000Z",
  "updatedAt": "2024-01-10T08:30:00.000Z"
}
```

---

## Create Blog Category

```
POST /api/v1/blog-categories
```

### Body Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | Blog category display name |
| `slug` | `string` | No | URL slug – lowercase letters, numbers, and hyphens only. Auto-generated from `name` if omitted. |
| `description` | `string \| null` | No | Plain text description |
| `image` | `string \| null` | No | Image URL |

Unknown fields are rejected.

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Tutorials","description":"Step-by-step guides and how-tos"}' \
  https://your-store.yns.store/api/v1/blog-categories
```

---

## Update Blog Category

```
PATCH /api/v1/blog-categories/:idOrSlug
```

Accepts a UUID or a slug. All fields are optional – send only what you want to change.

### Body Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `string` | New display name |
| `slug` | `string` | New URL slug |
| `description` | `string \| null` | Description, or `null` to clear |
| `image` | `string \| null` | Image URL, or `null` to clear |
| `active` | `boolean` | Whether the category is visible on the storefront |

```bash
curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"active":false}' \
  https://your-store.yns.store/api/v1/blog-categories/tutorials
```

---

## Delete Blog Category

```
DELETE /api/v1/blog-categories/:idOrSlug
```

Returns `404` if no category matches the identifier.

```bash
curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/blog-categories/tutorials
```