Skip to main content
ADMIN ACCESS REQUIRED - This endpoint requires authentication with an ADMIN role.

​
Overview

Creates a new category in the system. Categories are used to organize articles and subcategories.

​
Authentication

This endpoint requires:
  • Valid JWT token in the Authorization header
  • User must have ADMIN role

​
Request Body

​
name
string
required
The name of the category. Must be unique.
  • Required: Yes
  • Type: String
  • Max Length: 255 characters
​
description
string
Optional description of the category.
  • Required: No
  • Type: String
  • Max Length: 255 characters

​
Validation Rules

  • name: Required, string, maximum 255 characters
  • description: Optional (nullable), string, maximum 255 characters

​
Response

​
success
boolean
required
Indicates if the request was successful
​
message
string
required
Success message indicating the category was created
​
data
object
required
​
category
object
required
The newly created category object
​
id
integer
required
Unique identifier for the category
​
name
string
required
Category name (max 255 characters)
​
description
string
Optional category description (max 255 characters)
​
created_at
string
required
Timestamp when the category was created
​
updated_at
string
required
Timestamp when the category was last updated
​
deleted_at
string
Timestamp when the category was soft deleted (null for new categories)

​
Code Examples

curl -X POST "https://api.example.com/category" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "name": "Hardware",
    "description": "Hardware related issues and repairs"
  }'

​
Response Examples

​
Success Response (201 Created)

{
  "success": true,
  "message": "Category created successfully",
  "data": {
    "category": {
      "id": 3,
      "name": "Hardware",
      "description": "Hardware related issues and repairs",
      "created_at": "2026-03-08T12:45:00.000000Z",
      "updated_at": "2026-03-08T12:45:00.000000Z",
      "deleted_at": null
    }
  }
}

​
Validation Error Response (422 Unprocessable Entity)

Returned when validation fails: 
{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}

​
Unauthorized Response (401 Unauthorized)

{
  "success": false,
  "message": "Unauthenticated"
}

​
Forbidden Response (403 Forbidden)

Returned when the authenticated user does not have ADMIN role: 
{
  "success": false,
  "message": "Unauthorized. Admin access required."
}

​
Error Codes

Status CodeDescription
201Success - Category created
401Unauthorized - Invalid or missing JWT token
403Forbidden - User does not have ADMIN role
422Validation Error - Invalid input data
500Internal Server Error

​
Notes

  • The category name should be unique across the system
  • Categories can have multiple subcategories and articles associated with them
  • Soft deletes are enabled, so deleted categories are marked with a deleted_at timestamp rather than being permanently removed

Build docs developers (and LLMs) love

Get started for freeTalk to us