Skip to main content

​
Base URL

All API requests should be made to: 
http://localhost:3000/api

​
Content Type

All requests and responses use JSON format. Include the following header in your requests: 
Content-Type: application/json

​
Authentication

The current version of the API does not require authentication. All endpoints are publicly accessible.
In a production environment, you should implement proper authentication and authorization mechanisms to secure your API endpoints.

​
API Endpoints

The API is organized around two main resources:
  • Tasks (/api/tasks) - Manage individual tasks with titles, descriptions, completion status, and categories
  • Task Categories (/api/taskCategories) - Organize tasks into categories

​
Business Rules

​
Unique Identifiers (UUID)

All entities use UUID v4 generated via Node.js crypto module for unique identification. IDs are automatically generated by the API and should not be provided in create requests.
Example UUID: 550e8400-e29b-41d4-a716-446655440000

​
Date Format

All timestamps follow the ISO 8601 standard: 
YYYY-MM-DDTHH:mm:ss.sssZ
Example: 2026-03-11T14:30:00.000Z

​
Input Validation

The API uses Zod for schema validation:
  • Invalid fields are ignored
  • String values are automatically trimmed (whitespace removed from start and end)
  • Type mismatches return 400 Bad Request errors

​
Task Lifecycle Management

​
Timestamps

  • createdAt: Automatically set when a task is created (read-only)
  • updatedAt: Automatically updated on every modification (read-only)
  • finishedAt: Automatically managed based on completion status (read-only)
    • Set to current timestamp when completed changes from false to true
    • Removed when completed changes from true to false
You never need to manually set timestamp fields - the API handles them automatically.

​
Default Categorization

If no categoryId is specified when creating or updating a task, the system automatically assigns the label "uncategorized".

​
Category Management

​
Referential Integrity

When categories are deleted, the API automatically maintains data integrity:
  1. All tasks linked to deleted categories are reassigned to "uncategorized"
  2. The deletion operation completes successfully
  3. No tasks are lost in the process
The special "uncategorized" value is a string literal, not a UUID. It serves as the default category for tasks without an explicit category assignment.

​
Unique Category Names

Category names must be unique and valid according to the schema validation rules.

​
Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests:

​
Success Codes

  • 200 OK - Request succeeded, response body contains data
  • 201 Created - Resource successfully created, response body contains the new resource
  • 204 No Content - Request succeeded, no response body (typically for DELETE operations)

​
Error Codes

  • 400 Bad Request - Invalid request data or validation failure
  • 404 Not Found - Requested resource does not exist
  • 500 Internal Server Error - Server-side error occurred

​
Error Response Format

Error responses include a descriptive message: 
{
  "message": "Task not found",
  "error": "Datos no validos o incompletos"
}

​
Rate Limiting

The current version does not implement rate limiting.
For production deployments, implement rate limiting to prevent abuse and ensure fair resource allocation.

​
API Versioning

The current API does not use versioning. All endpoints are accessed directly under /api.

​
Quick Start Example

Here’s a complete example of creating a task and assigning it to a category: 
# 1. Create a category
curl -X POST http://localhost:3000/api/taskCategories \
  -H "Content-Type: application/json" \
  -d '{"name":"Work"}'

# 2. Create a task with that category
curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title":"Complete API documentation",
    "description":"Write comprehensive docs",
    "categoryId":"550e8400-e29b-41d4-a716-446655440000"
  }'

# 3. Get all tasks
curl http://localhost:3000/api/tasks

​
Next Steps

Data Models

Explore the complete Task and TaskCategory schemas

Tasks API

Learn how to manage tasks

Categories API

Learn how to organize tasks with categories

Build docs developers (and LLMs) love

Get started for freeTalk to us