4todo Documentation

API status: unstable. This API can change without notice.

Use this API to manage your todos and recurring tasks.

Authentication

Send a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Send Content-Type: application/json for requests with a body.

Create API tokens in the 4todo app settings. The app shows a token only once, when you create it. Store it securely.

Base URL

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

Quadrant System

The Eisenhower Matrix uses four quadrants.

Workspaces

GET /api/v0/todos requires a workspace ID.

Workspace IDs use the ws_ prefix.

List workspaces with GET /api/v0/workspaces.

A restricted workspace is read-only. Mutations return 402 with code: WORKSPACE_RESTRICTED.

Endpoints

Workspaces

List Workspaces

List your workspaces.

GET /api/v0/workspaces

Example Request (curl):

curl -sS \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://4to.do/api/v0/workspaces"

Example Response:

[
  {
    "id": "ws_01hqk8z9w3r2n1p0m4v5x7y6",
    "name": "Default",
    "description": "Your default workspace",
    "icon": "",
    "is_default": true,
    "sort_order": "0|",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
]

Todos

Get Todos

Get pending, non-deleted todos for one workspace.

GET /api/v0/todos

Query Parameters:

Response:

The response is an object keyed by quadrant. Each value is an array of todo objects.

Todo fields:

Recurring config fields (recurring_config):

Example Request:

GET /api/v0/todos?workspace=ws_01hqk8z9w3r2n1p0m4v5x7y6

Example Request (curl):

curl -sS \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://4to.do/api/v0/todos?workspace=ws_01hqk8z9w3r2n1p0m4v5x7y6"

Example Response:

{
  "IU": [
    {
      "id": "todo_01hqk8z9w3r2n1p0m4v5x7y6",
      "name": "Complete project proposal",
      "quadrant": "IU",
      "completed_at": null,
      "type": "regular"
    }
  ],
  "IN": [],
  "NU": [],
  "NN": []
}

Create Todo

Create a new todo item in a specific quadrant.

POST /api/v0/todos

Request Body:

You can also set the workspace query parameter. Use it when you cannot send workspace_id.

Example Request:

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

Example Request (curl):

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Complete project proposal","quadrant":"IU","workspace_id":"ws_01hqk8z9w3r2n1p0m4v5x7y6"}' \
  "https://4to.do/api/v0/todos"

Example Response:

{
  "message": "Todo created successfully"
}

Complete Todo

Mark a todo item as completed.

POST /api/v0/todos/:id/complete

URL Parameters:

Example Request (curl):

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://4to.do/api/v0/todos/todo_01hqk8z9w3r2n1p0m4v5x7y6/complete"

Example Response:

{
  "message": "Todo completed successfully"
}

This endpoint is idempotent.

Error Response (404):

{
  "error": "Todo not found"
}

Reorder Todos

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

POST /api/v0/todos/reorder

Request Body:

If moved_todo_id starts with rec_todo_, the API updates the recurring todo quadrant. It ignores previous_todo_id and next_todo_id.

Example Request:

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

Example Request (curl):

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"moved_todo_id":"todo_01hqk8z9w3r2n1p0m4v5x7y6","previous_todo_id":"todo_01hqk8z8x2q1m0n3k4u5w6x7","next_todo_id":null,"quadrant":"IN"}' \
  "https://4to.do/api/v0/todos/reorder"

Example Response:

{
  "message": "Todo reordered successfully"
}

Error Response (400):

{
  "error": "Invalid quadrant type"
}

Error Response (404):

{
  "error": "Todo not found"
}

Recurring Todos

Recurring todos automatically create new instances based on a schedule.

Get Recurring Todos

List recurring todos.

GET /api/v0/recurring-todos

Query Parameters:

Example Request (curl):

curl -sS \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://4to.do/api/v0/recurring-todos?workspace=ws_01hqk8z9w3r2n1p0m4v5x7y6"

Example Response:

[
  {
    "id": "rec_todo_01hqk8z9w3r2n1p0m4v5x7y6",
    "title": "Morning standup",
    "quadrant": "IU",
    "frequency": "daily",
    "timezone": "America/Los_Angeles",
    "start_date": "2026-01-15T10:30:00Z",
    "end_date": null,
    "rrule": "FREQ=DAILY"
  }
]

Create Recurring Todo

Create a new recurring todo with a specified frequency.

POST /api/v0/recurring-todos

Query Parameters:

Request Body:

Example Request (curl):

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Morning standup","quadrant":"IU","frequency":"daily","timezone":"America/Los_Angeles"}' \
  "https://4to.do/api/v0/recurring-todos?workspace=ws_01hqk8z9w3r2n1p0m4v5x7y6"

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/v0/recurring-todos/:id

URL Parameters:

Example Request (curl):

curl -sS \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://4to.do/api/v0/recurring-todos/rec_todo_01hqk8z9w3r2n1p0m4v5x7y6"

Example Response:

{
  "id": "rec_todo_01hqk8z9w3r2n1p0m4v5x7y6",
  "title": "Morning standup",
  "quadrant": "IU",
  "frequency": "daily",
  "timezone": "America/Los_Angeles",
  "start_date": "2026-01-15T10:30:00Z",
  "end_date": null,
  "rrule": "FREQ=DAILY"
}

Update Recurring Todo

Update an existing recurring todo's properties.

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

Request Body:

Example Request (curl):

curl -sS -X PUT \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Morning standup","quadrant":"IU","frequency":"daily","timezone":"America/Los_Angeles"}' \
  "https://4to.do/api/v0/recurring-todos/rec_todo_01hqk8z9w3r2n1p0m4v5x7y6"

Example Response:

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

Delete Recurring Todo

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

DELETE /api/v0/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

Error Response Format

Most error responses use this structure. Some legacy endpoints return only error.

{
  "error": "error_code_or_message",
  "message": "Optional human-readable message"
}

Example Error:

{
  "error": "invalid_request",
  "message": "Invalid quadrant type"
}

Token Errors

Token auth errors use 401 and JSON responses.

Possible values for error:

• missing authorization header
• invalid authorization header
• invalid_token
• invalid token
• token_expired

Example: token expired

{
  "error": "token_expired",
  "message": "Your token has expired. Please create a new token in settings."
}

Rate Limiting

/api/v0 is rate-limited.

When you exceed the limit, the API returns 429. It includes Retry-After and X-RateLimit-* headers.

Example: rate limited

{
  "error": "rate_limited",
  "message": "Too many requests"
}

Feature Gate Errors

Feature gate errors use 402 and a structured JSON response.

Possible values for code:

• FEATURE_UNAVAILABLE
• LIMIT_REACHED
• WORKSPACE_RESTRICTED

{
  "code": "FEATURE_UNAVAILABLE",
  "message": "Feature 'recurring_tasks' is not available on your current plan",
  "feature_id": "recurring_tasks",
  "plan_id": "plan_..."
}

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: rec_todo_01hqk8z9w3r2n1p0m4v5x7y6
• Workspace IDs: ws_01hqk8z9w3r2n1p0m4v5x7y6

Timezones

Always use valid IANA timezone identifiers. Common examples:

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

Recurrence Rules

The API exposes a backend rrule string. It uses a small subset of RFC 5545.

• Daily: FREQ=DAILY
• Weekly: FREQ=WEEKLY or FREQ=WEEKLY;BYDAY=MO,WE,FR
• Monthly: FREQ=MONTHLY;BYMONTHDAY=1

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: 2026-01-28