Todo Items

Overview

Todo items represent individual tasks within todo lists. Each item has a title, completion status, optional scheduled date, and belongs to a specific list. Base URL: /todos Authentication: All endpoints require authentication via Bearer token. Encryption: The title field is encrypted at rest using AES-GCM with user-specific keys.

List Todo Items

GET /todos

Retrieve todo items for the authenticated user

Query Parameters

listId

string

Filter todos by list ID. Use "all" or omit to retrieve all todos.

Response

Returns an array of todo objects ordered by the order field.

string

required

Unique identifier for the todo (UUID)

userId

string

required

User ID that owns this todo

title

string

required

Todo title (decrypted from storage)

completed

boolean

required

Whether the todo is marked as complete

scheduledDate

string | null

required

ISO date string when the todo is scheduled (e.g., "2026-03-15"), or null

listId

string

required

UUID of the list this todo belongs to

order

integer

required

Sort order for displaying todos

createdAt

string

required

ISO timestamp when the todo was created

updatedAt

string

required

ISO timestamp when the todo was last updated

Example Request

# Get all todos
curl -X GET https://api.chronoscalendar.com/todos \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get todos for a specific list
curl -X GET "https://api.chronoscalendar.com/todos?listId=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

[
  {
    "id": "abc12345-6789-def0-1234-56789abcdef0",
    "userId": "user_123",
    "title": "Review pull requests",
    "completed": false,
    "scheduledDate": "2026-03-05",
    "listId": "123e4567-e89b-12d3-a456-426614174000",
    "order": 0,
    "createdAt": "2026-03-04T10:30:00Z",
    "updatedAt": "2026-03-04T10:30:00Z"
  },
  {
    "id": "def67890-abcd-1234-5678-90abcdef1234",
    "userId": "user_123",
    "title": "Buy groceries",
    "completed": true,
    "scheduledDate": null,
    "listId": "987fcdeb-51a2-43f1-b123-456789abcdef",
    "order": 1,
    "createdAt": "2026-03-03T14:20:00Z",
    "updatedAt": "2026-03-04T09:15:00Z"
  }
]

Create Todo Item

POST /todos

Create a new todo item

Request Body

title

string

required

Todo title (max 500 characters, will be encrypted)

listId

string

required

UUID of the list this todo belongs to (must exist and belong to user)

scheduledDate

string | null

ISO date string (e.g., "2026-03-15"), or null

Response

Returns the created todo object.

string

required

Unique identifier for the created todo

userId

string

required

User ID that owns this todo

title

string

required

Todo title (decrypted)

completed

boolean

required

Always false for newly created todos

scheduledDate

string | null

required

Scheduled date if provided

listId

string

required

List UUID

order

integer

required

Automatically assigned order (minimum existing order - 1)

createdAt

string

required

Creation timestamp

updatedAt

string

required

Update timestamp (same as createdAt initially)

Example Request

curl -X POST https://api.chronoscalendar.com/todos \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Finish API documentation",
    "listId": "123e4567-e89b-12d3-a456-426614174000",
    "scheduledDate": "2026-03-10"
  }'

Example Response

{
  "id": "new12345-6789-abcd-ef01-234567890abc",
  "userId": "user_123",
  "title": "Finish API documentation",
  "completed": false,
  "scheduledDate": "2026-03-10",
  "listId": "123e4567-e89b-12d3-a456-426614174000",
  "order": -1,
  "createdAt": "2026-03-04T15:45:00Z",
  "updatedAt": "2026-03-04T15:45:00Z"
}

Error Responses

Show 400 Bad Request

Invalid listId (list doesn’t exist or doesn’t belong to user)
Title exceeds 500 characters

Show 500 Internal Server Error

Failed to create todo in database

Update Todo Item

PUT /todos/{todo_id}

Update an existing todo item

Path Parameters

todo_id

string

required

UUID of the todo to update

Request Body

All fields are optional. Only provided non-null fields will be updated.

title

string

New todo title (max 500 characters, will be encrypted)

completed

boolean

New completion status

scheduledDate

string | null

New scheduled date (ISO format) or null to remove

listId

string

Move todo to a different list (must exist and belong to user)

order

integer

New sort order

Response

Returns the updated todo object.

Example Request

curl -X PUT https://api.chronoscalendar.com/todos/abc12345-6789-def0-1234-56789abcdef0 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "completed": true,
    "scheduledDate": "2026-03-06"
  }'

Example Response

{
  "id": "abc12345-6789-def0-1234-56789abcdef0",
  "userId": "user_123",
  "title": "Review pull requests",
  "completed": true,
  "scheduledDate": "2026-03-06",
  "listId": "123e4567-e89b-12d3-a456-426614174000",
  "order": 0,
  "createdAt": "2026-03-04T10:30:00Z",
  "updatedAt": "2026-03-04T16:20:00Z"
}

Error Responses

Show 404 Not Found

Todo not found or doesn’t belong to the user

Show 400 Bad Request

Invalid listId (list doesn’t exist or doesn’t belong to user)
Title exceeds 500 characters

Delete Todo Item

DELETE /todos/{todo_id}

Delete a todo item

Path Parameters

todo_id

string

required

UUID of the todo to delete

Response

message

string

Confirmation message: “Todo deleted”

Example Request

curl -X DELETE https://api.chronoscalendar.com/todos/abc12345-6789-def0-1234-56789abcdef0 \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "message": "Todo deleted"
}

Error Responses

Show 404 Not Found

Todo not found or doesn’t belong to the user

Data Security

Encryption Details: The title field is encrypted using AES-GCM (256-bit) with:

User-specific keys derived via HKDF-SHA256 from master key
12-byte random initialization vector (IV) per encryption
Additional authenticated data (AAD) including user ID
Base64 encoding for storage (IV + ciphertext)

If decryption fails, the title is returned as "[Decryption Error]".

Field Validation

Important Constraints:

Titles are limited to 500 characters before encryption
The listId must reference an existing list owned by the user
Dates must be in ISO format (YYYY-MM-DD)
Null values for non-nullable fields (title, listId, completed, order) are filtered out during updates

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.

Authentication

Calendar

Todos

Overview

List Todo Items

GET /todos

Query Parameters

Response

Example Request

Example Response

Create Todo Item

POST /todos

Request Body

Response

Example Request

Example Response

Error Responses

Update Todo Item

PUT /todos/{todo_id}

Path Parameters

Request Body

Response

Example Request

Example Response

Error Responses

Delete Todo Item

DELETE /todos/{todo_id}

Path Parameters

Response

Example Request

Example Response

Error Responses

Data Security

Field Validation

Rate Limiting

Build docs developers (and LLMs) love

Authentication

Calendar

Todos

​Overview

​List Todo Items

GET /todos

​Query Parameters

​Response

​Example Request

​Example Response

​Create Todo Item

POST /todos

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Update Todo Item

PUT /todos/{todo_id}

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Delete Todo Item

DELETE /todos/{todo_id}

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Data Security

​Field Validation

​Rate Limiting

Build docs developers (and LLMs) love

Overview

List Todo Items

Query Parameters

Response

Example Request

Example Response

Create Todo Item

Request Body

Response

Example Request

Example Response

Error Responses

Update Todo Item

Path Parameters

Request Body

Response

Example Request

Example Response

Error Responses

Delete Todo Item

Path Parameters

Response

Example Request

Example Response

Error Responses

Data Security

Field Validation

Rate Limiting