Skip to main content

​
Task Model

The Task entity represents an individual to-do item with completion tracking and category assignment.

​
Schema Definition

​
_id
string
required
Unique identifier (UUID v4) automatically generated by the API.Example: "550e8400-e29b-41d4-a716-446655440000"
​
title
string
required
The task title or name.Validation:
  • Minimum length: 3 characters
  • Maximum length: 25 characters
  • Automatically trimmed (whitespace removed)
Example: "Complete documentation"
​
description
string
Optional detailed description of the task.Validation:
  • Maximum length: 25 characters
  • Automatically trimmed
Example: "Write API reference docs"
​
completed
boolean
default:"false"
Indicates whether the task has been completed.Behavior:
  • Defaults to false when not specified
  • When changed from false to true, finishedAt is automatically set
  • When changed from true to false, finishedAt is automatically removed
Example: true
​
categoryId
string
default:"uncategorized"
The UUID of the category this task belongs to, or the special value "uncategorized".Behavior:
  • Defaults to "uncategorized" when not specified or empty string provided
  • Can be set to any valid TaskCategory _id
  • When a category is deleted, all associated tasks are reassigned to "uncategorized"
Example: "550e8400-e29b-41d4-a716-446655440000" or "uncategorized"
​
createdAt
string
required
ISO 8601 timestamp indicating when the task was created.Behavior:
  • Automatically set by the API on creation
  • Read-only (cannot be modified)
  • Format: YYYY-MM-DDTHH:mm:ss.sssZ
Example: "2026-03-11T14:30:00.000Z"
​
updatedAt
string
ISO 8601 timestamp indicating when the task was last modified.Behavior:
  • Automatically set by the API on every update operation
  • Read-only (cannot be manually set)
  • Format: YYYY-MM-DDTHH:mm:ss.sssZ
Example: "2026-03-11T15:45:00.000Z"
​
finishedAt
string | null
ISO 8601 timestamp indicating when the task was marked as completed.Behavior:
  • Automatically set when completed changes from false to true
  • Automatically removed when completed changes from true to false
  • Read-only (cannot be manually set)
  • null or absent for incomplete tasks
  • Format: YYYY-MM-DDTHH:mm:ss.sssZ
Example: "2026-03-11T16:00:00.000Z" or null

​
Complete Example

{
  "_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Write API documentation",
  "description": "Create comprehensive docs",
  "completed": true,
  "categoryId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "createdAt": "2026-03-11T10:00:00.000Z",
  "updatedAt": "2026-03-11T16:00:00.000Z",
  "finishedAt": "2026-03-11T16:00:00.000Z"
}

​
TaskCategory Model

The TaskCategory entity represents a category or label for organizing tasks.

​
Schema Definition

​
_id
string
required
Unique identifier (UUID v4) automatically generated by the API.Example: "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
​
name
string
required
The category name.Validation:
  • Minimum length: 2 characters
  • Maximum length: 25 characters
  • Automatically trimmed (whitespace removed)
  • Should be unique (though not enforced at database level)
Example: "Work", "Personal", "Shopping"

​
Complete Example

TaskCategory Example
{
  "_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "name": "Work"
}

​
Validation Rules Summary

All validation is performed using Zod schemas on the server side.

​
Task Validation

FieldTypeRequiredMinMaxDefault
titlestringYes325-
descriptionstringNo-25-
completedbooleanNo--false
categoryIdstringNo--“uncategorized”

​
TaskCategory Validation

FieldTypeRequiredMinMaxDefault
namestringYes225-

​
Database Implementation

The API uses db-local for data persistence.

​
Special Values

​
”uncategorized”

The string literal "uncategorized" is a special value used for tasks without a category assignment:
  • It is NOT a UUID
  • It is the default value when no categoryId is provided
  • Tasks are automatically reassigned to this value when their category is deleted
  • You can explicitly set a task’s categoryId to empty string ("") to use this default
Do not create a TaskCategory with the name or ID “uncategorized” - this could cause confusion with the default value.

​
Type Definitions

For TypeScript projects, here are the recommended type definitions: 
interface Task {
  _id: string;
  title: string;
  description?: string;
  completed: boolean;
  categoryId: string;
  createdAt: string;
  updatedAt?: string;
  finishedAt?: string | null;
}

interface TaskCategory {
  _id: string;
  name: string;
}

interface CreateTaskInput {
  title: string;
  description?: string;
  completed?: boolean;
  categoryId?: string;
}

interface UpdateTaskInput {
  title?: string;
  description?: string;
  completed?: boolean;
  categoryId?: string;
}

interface CreateCategoryInput {
  name: string;
}

interface UpdateCategoryInput {
  name: string;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us