Skip to main content

​
Overview

Todo lists are containers for organizing todo items. Each list has a name, color, and order. System lists cannot be deleted. Base URL: /todos/todo-lists Authentication: All endpoints require authentication via Bearer token. Encryption: The name field is encrypted at rest using AES-GCM with user-specific keys. System lists skip encryption for the name field.

​
List Todo Lists

GET /todos/todo-lists

Retrieve all todo lists for the authenticated user

​
Response

Returns an array of todo list objects ordered by the order field.
​
id
string
required
Unique identifier for the list (UUID)
​
userId
string
required
User ID that owns this list
​
name
string
required
List name (decrypted from storage)
​
color
string
required
Hex color code (e.g., #FF5733)
​
isSystem
boolean
required
Whether this is a system-generated list (cannot be deleted)
​
order
integer
required
Sort order for displaying lists

​
Example Request

curl -X GET https://api.chronoscalendar.com/todos/todo-lists \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "userId": "user_123",
    "name": "Work Tasks",
    "color": "#3B82F6",
    "isSystem": false,
    "order": 0
  },
  {
    "id": "987fcdeb-51a2-43f1-b123-456789abcdef",
    "userId": "user_123",
    "name": "Personal",
    "color": "#10B981",
    "isSystem": true,
    "order": 1
  }
]

​
Create Todo List

POST /todos/todo-lists

Create a new todo list

​
Request Body

​
name
string
required
List name (max 100 characters, will be encrypted)
​
color
string
required
Hex color code matching pattern ^#[0-9a-fA-F]{6}$

​
Response

Returns the created todo list object.
​
id
string
required
Unique identifier for the created list
​
userId
string
required
User ID that owns this list
​
name
string
required
List name (decrypted)
​
color
string
required
Hex color code
​
isSystem
boolean
required
Always false for user-created lists
​
order
integer
required
Automatically assigned order (minimum existing order - 1)

​
Example Request

curl -X POST https://api.chronoscalendar.com/todos/todo-lists \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shopping List",
    "color": "#F59E0B"
  }'

​
Example Response

{
  "id": "456e7890-e12b-34d5-a678-901234567890",
  "userId": "user_123",
  "name": "Shopping List",
  "color": "#F59E0B",
  "isSystem": false,
  "order": -1
}

​
Error Responses

​
Update Todo List

PUT /todos/todo-lists/{list_id}

Update an existing todo list

​
Path Parameters

​
list_id
string
required
UUID of the list to update

​
Request Body

All fields are optional. Only provided fields will be updated.
​
name
string
New list name (max 100 characters, will be encrypted)
​
color
string
New hex color code matching pattern ^#[0-9a-fA-F]{6}$
​
order
integer
New sort order

​
Response

Returns the updated todo list object.

​
Example Request

curl -X PUT https://api.chronoscalendar.com/todos/todo-lists/456e7890-e12b-34d5-a678-901234567890 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Grocery Shopping",
    "color": "#EF4444"
  }'

​
Example Response

{
  "id": "456e7890-e12b-34d5-a678-901234567890",
  "userId": "user_123",
  "name": "Grocery Shopping",
  "color": "#EF4444",
  "isSystem": false,
  "order": -1
}

​
Error Responses

​
Delete Todo List

DELETE /todos/todo-lists/{list_id}

Delete a todo list

​
Path Parameters

​
list_id
string
required
UUID of the list to delete

​
Response

​
message
string
Confirmation message: “List deleted”

​
Example Request

curl -X DELETE https://api.chronoscalendar.com/todos/todo-lists/456e7890-e12b-34d5-a678-901234567890 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "message": "List deleted"
}

​
Error Responses

​
Reorder Lists

POST /todos/todo-lists/reorder

Reorder all todo lists at once

​
Request Body

​
categoryIds
array
required
Array of list UUIDs in the desired order

​
Response

​
message
string
Confirmation message: “Reordered”

​
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"
}
The first UUID in the array will be assigned order: 0, the second order: 1, and so on.

​
Data Security

Encryption Details: The name field is encrypted using AES-GCM (256-bit) with:
  • User-specific keys derived via HKDF-SHA256
  • 12-byte random IV per encryption
  • Additional authenticated data (AAD) includes user ID
  • System lists skip encryption for performance

​
Rate Limiting

All endpoints are subject to the API rate limit configured in application settings. Exceeding the rate limit will return a 429 Too Many Requests response.

Build docs developers (and LLMs) love

Get started for freeTalk to us