Blog Categories API

REST API endpoints for managing blog post categories.

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

{
  "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

{
  "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.

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

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.

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

PreviousPostsAPI Reference NextPost CommentsAPI Reference