Categories API

Blog categories with post counts. Public read, admin write.

Public Endpoints

GET /api/v1/categories

List all categories with their post counts.

curl https://your-site.com/api/v1/categories

Response:

{
  "success": true,
  "message": "Categories retrieved successfully",
  "data": [
    {
      "id": 5,
      "name": "Headless CMS",
      "slug": "headless-cms",
      "description": "Headless and decoupled CMS topics",
      "posts_count": 12
    }
  ]
}

posts_count includes only published posts.

GET /api/v1/categories/{slug}

Fetch a single category by slug.

curl https://your-site.com/api/v1/categories/headless-cms

GET /api/v1/categories/{slug}/posts

Paginated list of published posts in a category. Shortcut for /api/v1/posts?category={slug}.

Query parameters: same as /api/v1/posts (page, per_page).

curl "https://your-site.com/api/v1/categories/headless-cms/posts?per_page=10"

Admin Endpoints

GET /api/v1/admin/categories

List all categories (no pagination — there are rarely more than a few dozen).

POST /api/v1/admin/categories

Create a category.

{
  "name": "Tutorials",
  "slug": "tutorials",
  "description": "Step-by-step technical guides"
}

Required: name. Slug auto-generates from name if omitted.

GET /api/v1/admin/categories/{id}

Single category by numeric ID.

PATCH /api/v1/admin/categories/{id}

Partial update — send only the fields to change.

DELETE /api/v1/admin/categories/{id}

Delete a category. Posts attached to it stay (the join table row is dropped).