We're excited to announce a new feature that many of you have been asking for: a comprehensive JSON API for FreeTodoList! This new API allows developers to programmatically access and interact with todo lists, enabling integrations with third-party applications, custom workflows, and mobile apps.
Our JSON API provides a clean, RESTful interface to access your lists and items. Simply append .json to the URL of any list to get a structured JSON representation of that list and its items. The API supports:
Update: We've just expanded our API with full CRUD support for list items! Read more about the new items endpoints.
To get a JSON representation of any list, simply add .json to the end of its URL:
https://freetodolist.com/lists/abc123.json
This returns a structured JSON object containing the list's metadata and all its items:
{
"list": {
"uid": "abc123",
"name": "Weekly Tasks",
"description": "Things to do this week",
"created_at": "2025-04-05T12:34:56Z",
"updated_at": "2025-04-07T09:12:34Z",
"url": "https://freetodolist.com/lists/abc123",
"shareable": true,
"shareable_url": "https://freetodolist.com/shared/def456",
"rss_feed_url": "https://freetodolist.com/lists/abc123/feed.rss",
"ical_feed_url": "https://freetodolist.com/lists/abc123/calendar.ics",
"stats": {
"total_items": 12,
"completed_items": 5,
"uncompleted_items": 7,
"archived_items": 3,
"overdue_items": 2
}
},
"items": [
{
"body": "Complete project proposal",
"complete": false,
"position": 1,
"created_at": "2025-04-05T13:14:15Z",
"updated_at": "2025-04-05T13:14:15Z",
"due_at": "2025-04-10T17:00:00Z",
"completed_at": null,
"archived": false
},
{
"body": "Send weekly report",
"complete": true,
"position": 2,
"created_at": "2025-04-05T13:15:30Z",
"updated_at": "2025-04-07T09:12:34Z",
"due_at": "2025-04-07T17:00:00Z",
"completed_at": "2025-04-07T09:12:34Z",
"archived": false
}
// Additional items...
]
}
For a comprehensive view of all your lists, access your dashboard in JSON format:
https://freetodolist.com/dashboard.json
This returns statistics about your overall lists and items, plus a summary of each list:
{
"stats": {
"lists_count": 5,
"archived_lists_count": 2,
"overdue_items_count": 3,
"total_items": 42,
"completed_items": 28,
"completion_percentage": 67
},
"lists": [
{
"uid": "abc123",
"name": "Weekly Tasks",
"description": "Things to do this week",
"created_at": "2025-04-05T12:34:56Z",
"updated_at": "2025-04-07T09:12:34Z",
"url": "https://freetodolist.com/lists/abc123",
"position": 1,
"shareable": true,
"shareable_url": "https://freetodolist.com/shared/def456",
"rss_feed_url": "https://freetodolist.com/lists/abc123/feed.rss",
"ical_feed_url": "https://freetodolist.com/lists/abc123/calendar.ics",
"items_count": 12,
"completed_items_count": 5,
"uncompleted_items_count": 7,
"overdue_items_count": 2
}
// Additional lists...
]
}
To get a list of all overdue items across your lists:
https://freetodolist.com/overdue_items.json
This returns a structured list of all your overdue items:
{
"count": 3,
"items": [
{
"body": "Complete project proposal",
"complete": false,
"due_at": "2025-04-08T17:00:00Z",
"days_overdue": 1,
"position": 1,
"created_at": "2025-04-05T13:14:15Z",
"updated_at": "2025-04-05T13:14:15Z",
"list": {
"uid": "abc123",
"name": "Weekly Tasks",
"url": "https://freetodolist.com/lists/abc123",
"rss_feed_url": "https://freetodolist.com/lists/abc123/feed.rss",
"ical_feed_url": "https://freetodolist.com/lists/abc123/calendar.ics"
}
}
// Additional overdue items...
]
}
The API supports various filtering and sorting options:
include_archived=true - Include archived items in the responseonly_completed=true - Only include completed itemsonly_uncompleted=true - Only include uncompleted itemssort=position_desc - Sort items by position in descending ordersort=date_asc - Sort items by due date in ascending orderExample:
https://freetodolist.com/lists/abc123.json?sort=date_asc&only_uncompleted=true
We take your data privacy seriously. Our API implementation:
Here are some ways you might use the new API:
Here's a simple Python script that demonstrates how to use our enhanced API to manage tasks:
import requests
import datetime
# API configuration
API_TOKEN = "your_api_token"
BASE_URL = "https://freetodolist.com/api/v1"
HEADERS = {
"Authorization": f"Bearer {API_TOKEN}",
"Accept": "application/json",
"Content-Type": "application/json"
}
# Get all lists
def get_lists():
response = requests.get(f"{BASE_URL}/lists", headers=HEADERS)
return response.json()["lists"]
# Get items from a specific list
def get_list_items(list_uid, only_uncompleted=False):
params = {"only_uncompleted": "true"} if only_uncompleted else {}
response = requests.get(
f"{BASE_URL}/lists/{list_uid}/items",
headers=HEADERS,
params=params
)
return response.json()["items"]
# Create a new item in a list
def create_item(list_uid, body, due_at=None, position_at_top=True):
data = {
"item": {
"body": body
},
"position_at_top": str(position_at_top).lower()
}
if due_at:
data["item"]["due_at"] = due_at.isoformat()
response = requests.post(
f"{BASE_URL}/lists/{list_uid}/items",
headers=HEADERS,
json=data
)
return response.json()["item"]
# Mark an item as complete
def complete_item(item_uid):
data = {
"item": {
"complete": True,
"completed_at": datetime.datetime.now().isoformat()
}
}
response = requests.patch(
f"{BASE_URL}/items/{item_uid}",
headers=HEADERS,
json=data
)
return response.json()["item"]
# Example usage
if __name__ == "__main__":
# Get the first list
lists = get_lists()
if not lists:
print("No lists found")
exit()
work_list = lists[0]
print(f"Working with list: {work_list['name']}")
# Get uncompleted items
uncompleted = get_list_items(work_list["uid"], only_uncompleted=True)
print(f"You have {len(uncompleted)} uncompleted items")
# Create a new task for tomorrow
tomorrow = datetime.datetime.now() + datetime.timedelta(days=1)
new_item = create_item(
work_list["uid"],
"Review API documentation",
due_at=tomorrow
)
print(f"Created new item: {new_item['body']}")
# Mark the first uncompleted item as complete (if any exist)
if uncompleted:
completed = complete_item(uncompleted[0]["uid"])
print(f"Marked as complete: {completed['body']}")
For full documentation of all available endpoints, parameters, and response formats, visit our API Documentation page.
We'd love to hear how you're using the API and what additional features would make it more useful for you. Please send us feedback with your ideas and suggestions.
Have you tried our new JSON API yet? Let us know what you're building with it!