Documentation Index
Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
Use this file to discover all available pages before exploring further.
Sub-categories live under a category and group related offers. They support soft-delete, version tracking, and audit logging. For the full sub-categories documentation integrated with the Categories API, see the Categories API reference.
All sub-categories support soft-delete (a deletedAt timestamp is set instead of permanent removal), version tracking (the version field auto-increments on every update), and audit logging (before/after snapshots are recorded for every CRUD operation).
Base path
List sub-categories
GET /api/v1/sub-categories
ordinal ascending. Optionally filter by parent category. By default, soft-deleted sub-categories are excluded.
Query Parameters
| Parameter | Type | Required | Description |
|---|
categoryId | string | No | Filter by parent category ID. |
limit | integer | No | Maximum results per page. Default 25. |
cursor | string | No | Cursor for keyset pagination. |
includeDeleted | string | No | Set to "true" to include soft-deleted sub-categories. |
Response 200
{
"data": [
{
"id": "sub_01",
"tenantId": "t_001",
"categoryId": "cat_01",
"name": "Premium Cards",
"description": "High-tier credit card products",
"icon": "",
"status": "active",
"ordinal": 0,
"version": 1,
"deletedAt": null,
"customFields": [],
"category": { "id": "cat_01", "name": "Acquisition" },
"_count": { "offers": 12 },
"createdAt": "2026-03-10T12:00:00.000Z",
"updatedAt": "2026-03-10T12:00:00.000Z"
}
],
"pagination": {
"total": 3,
"limit": 25,
"hasMore": false,
"nextCursor": null
}
}
Create a sub-category
POST /api/v1/sub-categories
Request Body
| Field | Type | Required | Description |
|---|
categoryId | string | Yes | Parent category ID. |
name | string | Yes | Sub-category name. |
description | string | No | Optional description. |
icon | string | No | Icon identifier. |
status | enum | No | "active" (default), "draft", "paused", "archived". |
ordinal | integer (>= 0) | No | Sort order. Default 0. |
customFields | array | No | Custom field definitions (same schema as categories). |
Example
curl -X POST https://playground.kaireonai.com/api/v1/sub-categories \
-H "Content-Type: application/json" \
-H "X-Tenant-Id: my-tenant" \
-d '{
"categoryId": "cat_credit_cards",
"name": "Premium Cards",
"description": "High-tier credit card products",
"status": "active"
}'
Response 201
Returns the created sub-category with its parent category relation, version: 1, and deletedAt: null. An audit log entry is created with a create action.
Error codes
| Code | Reason |
|---|
400 | Validation error (missing categoryId or name). |
401 | Missing or invalid API key / session. |
403 | Insufficient role (requires editor or admin). |
409 | A sub-category with that name already exists. |
Update a sub-category
PUT /api/v1/sub-categories
version field is auto-incremented and a before/after audit snapshot is recorded.
Request Body
| Field | Type | Required | Description |
|---|
id | string | Yes | Sub-category ID to update. |
Response 200
Returns the updated sub-category object with the incremented version.
Error codes
| Code | Reason |
|---|
400 | Validation error or missing id. |
401 | Missing or invalid API key / session. |
403 | Insufficient role. |
409 | A sub-category with that name already exists. |
Delete a sub-category (soft-delete)
DELETE /api/v1/sub-categories?id={subCategoryId}
deletedAt timestamp. The version is incremented.
Query Parameters
| Parameter | Type | Required | Description |
|---|
id | string | Yes | Sub-category ID to delete. |
Response 200
Error codes
| Code | Reason |
|---|
400 | Missing id, entity not found, or entity already deleted. |
401 | Missing or invalid API key / session. |
403 | Insufficient role. |
To restore a soft-deleted sub-category, use POST /api/v1/restore?entityType=subCategory&id={subCategoryId} (admin only).
Role requirements
| Method | Minimum role |
|---|
| GET | viewer |
| POST | editor |
| PUT | editor |
| DELETE | editor |
