Skip to main content

​
Overview

Categories in Chronos Calendar are synonymous with todo lists. They provide a way to organize todo items into different groups with custom names and colors.
The terms “categories” and “lists” are used interchangeably in the API. All category endpoints are documented in the Todo Lists reference.

​
Category Management

For complete documentation on category/list management, see:

Todo Lists

Full CRUD operations for managing categories

Reorder Categories

Reorder categories using drag-and-drop

​
Quick Reference

​
Category Endpoints

All category endpoints use the /todos/todo-lists base path:
MethodEndpointDescription
GET/todos/todo-listsList all categories
POST/todos/todo-listsCreate a new category
PUT/todos/todo-lists/{list_id}Update a category
DELETE/todos/todo-lists/{list_id}Delete a category
POST/todos/todo-lists/reorderReorder categories

​
Category Schema

​
id
string
required
Unique identifier for the category (UUID)
​
userId
string
required
User ID that owns this category
​
name
string
required
Category name (encrypted, max 100 characters)
​
color
string
required
Hex color code (e.g., #3B82F6)
​
isSystem
boolean
required
Whether this is a system category (cannot be deleted)
​
order
integer
required
Sort order for displaying categories

​
Category Reordering

POST /todos/todo-lists/reorder

Reorder all categories in a single operation

​
Request Body

​
categoryIds
array
required
Array of category UUIDs in the desired display order

​
Example Request

curl -X POST https://api.chronoscalendar.com/todos/todo-lists/reorder \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "categoryIds": [
      "987fcdeb-51a2-43f1-b123-456789abcdef",
      "123e4567-e89b-12d3-a456-426614174000",
      "456e7890-e12b-34d5-a678-901234567890"
    ]
  }'

​
Example Response

{
  "message": "Reordered"
}
Categories are assigned sequential order values starting from 0. The first UUID in the array receives order: 0, the second receives order: 1, and so on.

​
System Categories

System categories are pre-created lists that cannot be deleted by users. They are identified by the isSystem: true flag.
Attempting to delete a system category will return a 400 Bad Request error with the message: “Cannot delete system list”

​
Characteristics

  • Cannot be deleted: DELETE operations are blocked
  • Can be updated: Name and color can be modified
  • Skip encryption optimization: System category names may skip encryption for performance
  • User-specific: Each user has their own set of system categories

​
Color Validation

Category colors must be valid 6-digit hex codes. Valid formats:
  • #FF5733
  • #3b82f6
  • #10B981
Invalid formats:
  • FF5733 (missing #)
  • #F57 (too short)
  • #FF57339 (too long)
  • rgb(255, 87, 51) (not hex)
{
  "name": "Work",
  "color": "#3B82F6"
}

Todo Items

Manage individual todos within categories

Reorder Todos

Reorder todos within a category

Build docs developers (and LLMs) love

Get started for freeTalk to us