4todo Documentation

⚠️ API Status: Unstable - This API is currently in development and may change at any time without notice. Breaking changes may occur in future versions.

Welcome to the 4todo API documentation. This API allows you to programmatically manage your todos and recurring tasks using the Eisenhower Matrix methodology.

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Note: You can generate API tokens from your account settings.

Base URL

https://4to.do/api/v0

Quadrant System

The Eisenhower Matrix divides tasks into four quadrants:

Code	Description	Meaning
`IU`	Important & Urgent	Do first - Critical tasks requiring immediate attention
`IN`	Important & Not Urgent	Schedule - Important tasks for long-term success
`NU`	Not Important & Urgent	Delegate - Tasks that need to be done but not by you
`NN`	Not Important & Not Urgent	Eliminate - Low-value tasks to minimize

Endpoints

Todos

Create Todo

Create a new todo item in a specific quadrant.

POST /api/v1/todos

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Todo item name (1-500 characters)
`quadrant`	string	Yes	Quadrant type: `IU`, `IN`, `NU`, or `NN`

Example Request:

{
  "name": "Complete project proposal",
  "quadrant": "IU"
}

Example Response:

{
  "message": "Todo created successfully"
}

Complete Todo

Mark a todo item as completed.

POST /api/v1/todos/:id/complete

URL Parameters:

Parameter	Description
`id`	Todo ID (TypeID format: `todo_...`)

Example Response:

{
  "message": "Todo completed successfully"
}

Note: This endpoint is idempotent - completing an already completed todo will return success without error.

Reorder Todos

Reorder todos within the same quadrant or move them between quadrants.

POST /api/v1/todos/reorder

Request Body:

Field	Type	Required	Description
`moved_todo_id`	string	Yes	ID of the todo being moved
`previous_todo_id`	string	No	ID of the todo before the new position (null if moving to first position)
`next_todo_id`	string	No	ID of the todo after the new position (null if moving to last position)
`quadrant`	string	Yes	Target quadrant: `IU`, `IN`, `NU`, or `NN`

Example Request:

{
  "moved_todo_id": "todo_01hqk8z9w3r2n1p0m4v5x7y6",
  "previous_todo_id": "todo_01hqk8z8x2q1m0n3k4u5w6x7",
  "next_todo_id": null,
  "quadrant": "IN"
}

Example Response:

{
  "message": "Todo reordered successfully"
}

Recurring Todos

Recurring todos automatically create new instances based on a schedule.

Create Recurring Todo

Create a new recurring todo with a specified frequency.

POST /api/v1/recurring-todos

Request Body:

Field	Type	Required	Description
`title`	string	Yes	Recurring todo title
`quadrant`	string	Yes	Quadrant type: `IU`, `IN`, `NU`, or `NN`
`frequency`	string	Yes	`daily`, `weekly`, or `monthly`
`weekdays`	array	Conditional	Required for weekly frequency. Array of weekday codes: `["MO", "TU", "WE", "TH", "FR", "SA", "SU"]`
`month_day`	integer	Conditional	Required for monthly frequency. Day of month (1-31)
`timezone`	string	Yes	IANA timezone identifier (e.g., `"America/New_York"`, `"Europe/London"`)

Example Request (Daily):

{
  "title": "Morning standup",
  "quadrant": "IU",
  "frequency": "daily",
  "timezone": "America/Los_Angeles"
}

Example Request (Weekly):

{
  "title": "Team meeting",
  "quadrant": "IN",
  "frequency": "weekly",
  "weekdays": ["MO", "WE", "FR"],
  "timezone": "America/New_York"
}

Example Request (Monthly):

{
  "title": "Monthly report",
  "quadrant": "IN",
  "frequency": "monthly",
  "month_day": 1,
  "timezone": "UTC"
}

Example Response:

{
  "message": "Recurring todo created successfully"
}

Get Recurring Todo

Retrieve details of a specific recurring todo.

GET /api/v1/recurring-todos/:id

URL Parameters:

Parameter	Description
`id`	Recurring todo ID

Example Response:

{
  "id": "rtodo_01hqk8z9w3r2n1p0m4v5x7y6",
  "title": "Morning standup",
  "quadrant": "IU",
  "frequency": "daily",
  "timezone": "America/Los_Angeles",
  "created_at": "2025-01-15T10:30:00Z"
}

Update Recurring Todo

Update an existing recurring todo's properties.

PUT /api/v1/recurring-todos/:id

Request Body: Same fields as create, all optional

Example Response:

{
  "message": "Recurring todo updated successfully"
}

Delete Recurring Todo

Delete a recurring todo. This will stop future instances from being created.

DELETE /api/v1/recurring-todos/:id

Example Response:

{
  "message": "Recurring todo deleted successfully"
}

Error Responses

The API uses standard HTTP status codes to indicate success or failure.

Status Codes

Code	Description
`200`	Success - Request completed successfully
`400`	Bad Request - Invalid request data or parameters
`401`	Unauthorized - Missing or invalid authentication token
`404`	Not Found - Requested resource does not exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end

Error Response Format

All error responses follow this structure:

{
  "error": "Detailed error description"
}

Example Error:

{
  "error": "Invalid quadrant type. Must be one of: IU, IN, NU, NN"
}

Best Practices

TypeID Format

All IDs in the API use TypeID format for time-sortable, globally unique identifiers:

Todo IDs: todo_01hqk8z9w3r2n1p0m4v5x7y6
User IDs: user_01hqk8z9w3r2n1p0m4v5x7y6
Recurring Todo IDs: rtodo_01hqk8z9w3r2n1p0m4v5x7y6

Timezones

Always use valid IANA timezone identifiers. Common examples:

America/New_York
America/Los_Angeles
Europe/London
Asia/Tokyo
UTC

Pagination

Currently, API responses are not paginated. This may change in future versions.

Support

For API support or to report issues:

Email: [email protected]

Last updated: 2025-10-12