# Blog categories · Management API

> Management API reference for blog categories: GET /sites/{id}/blog/categories, POST /sites/{id}/blog/categories.

> Markdown version of https://kanorio.com/en/developers/management-api/blog_categories. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp

Base URL: `https://app.kanorio.com/api/v1` · [Errors](https://kanorio.com/en/developers/basics/errors) · [Pagination](https://kanorio.com/en/developers/basics/pagination)

### List blog categories

`GET /sites/{id}/blog/categories`

- Stability: beta
- Permission: `posts:view`
- Rate limit: default (120/minute per token)
- MCP tool: `blog_categories_list`

List this website's blog categories (id, slug, name, counts.posts). Use the ids in posts.create / posts.update categoryIds and primaryCategoryId. Errors: FORBIDDEN, INVALID_CURSOR.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Website id. Get it from sites.list or from sites.create. |
| `limit` | query | integer | no | Maximum number of items to return, 1–100. Defaults to 20. |
| `cursor` | query | string | no | Opaque cursor from the previous page's nextCursor. Omit for the first page. |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object[] | yes | — |
| `data[].id` | string | yes | — |
| `data[].slug` | string | yes | — |
| `data[].name` | string | yes | — |
| `data[].description` | string \| null | yes | — |
| `data[].sortOrder` | integer | yes | — |
| `data[].counts` | object | yes | Published post count. |
| `data[].counts.posts` | integer | yes | Number of published posts in this taxonomy. |
| `hasMore` | boolean | yes | True when another page exists; pass nextCursor to fetch it. |
| `nextCursor` | string \| null | yes | Cursor for the next page, or null on the last page. |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `FORBIDDEN` | 403 | — |
| `INVALID_CURSOR` | 400 | — |

```bash
curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/blog/categories" \
  -H "Authorization: Bearer $KANORIO_TOKEN"
```

```json
{
  "data": [
    {
      "id": "cat_example01",
      "slug": "bread-notes",
      "name": "Bread Notes",
      "description": "Notes from the bakehouse.",
      "sortOrder": 0,
      "counts": {
        "posts": 3
      }
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

### Create a blog category

`POST /sites/{id}/blog/categories`

- Stability: beta
- Permission: `blog:manage`
- Rate limit: default (120/minute per token)
- MCP tool: `blog_categories_create`

Create a blog category (name, optional slug and description). Returns the created category with its id for use in posts.create / posts.update. Errors: FORBIDDEN, VALIDATION, SLUG_TAKEN.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Website id. Get it from sites.list or from sites.create. |

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Display name of the category. |
| `slug` | string | no | URL slug; generated automatically from name when omitted. |
| `description` | string | no | Optional category description. |

**Response** (201)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `category` | object | yes | — |
| `category.id` | string | yes | — |
| `category.slug` | string | yes | — |
| `category.name` | string | yes | — |
| `category.description` | string \| null | yes | — |
| `category.sortOrder` | integer | yes | — |
| `category.counts` | object | yes | Published post count. |
| `category.counts.posts` | integer | yes | Number of published posts in this taxonomy. |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `FORBIDDEN` | 403 | — |
| `VALIDATION` | 400 | — |
| `SLUG_TAKEN` | 409 | — |

```bash
curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/blog/categories" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Bread Notes","description":"Notes from the bakehouse."}'
```

```json
{
  "category": {
    "id": "cat_example01",
    "slug": "bread-notes",
    "name": "Bread Notes",
    "description": "Notes from the bakehouse.",
    "sortOrder": 0,
    "counts": {
      "posts": 0
    }
  }
}
```