FreeTodoList API Reference

Build integrations with your task management workflows

Documentation

API Release Notes

Introduction

The FreeTodoList API follows REST principles and uses JSON as its data exchange format.

Base URL
https://freetodolist.com/api/v1

Authentication

All API requests require authentication using a Bearer token.

Bearer Token Authentication

API requests must include your API token in the Authorization header as a Bearer token.

1 Authorization: Bearer your_api_token

You can generate or regenerate your API token in your profile settings.

Note: Shared lists are the only resources that can be accessed without authentication, using their share token in the URL.

Rate Limiting

To ensure service stability, API requests are limited to 60 requests per minute per user. If you exceed this limit, requests will return a 429 status code until the limit resets.

Rate Limit Headers

Every API response includes headers that provide information about your current rate limit status:

1 X-RateLimit-Limit: 60
2 X-RateLimit-Remaining: 58
3 X-RateLimit-Reset: 1617981623
Header Description
X-RateLimit-Limit The maximum number of requests allowed per minute
X-RateLimit-Remaining The number of requests remaining in the current rate limit window
X-RateLimit-Reset The Unix timestamp (in seconds) when the rate limit will reset

Rate Limit Exceeded Response

When you exceed the rate limit, the API will respond with:

HTTP 429 Too Many Requests
{
  "error": "Rate limit exceeded. Try again in 45 seconds."
}

Tip: Your application should monitor these headers and adjust its request rate accordingly to avoid hitting the limit. Consider implementing backoff strategies when approaching the limit.

Lists Endpoint

GET

Get a Specific List

/api/v1/lists/:uid

Returns a specific list with its items. Archived items are excluded by default.

Response
{
  "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
    },
    // Additional items...
  ]
}

Query Parameters

Parameter Type Description
include_archived boolean Include archived items in the response
only_completed boolean Only include completed items
only_uncompleted boolean Only include uncompleted items
sort string
Sort items by:
position_desc - Position (descending)
date_asc - Due date (ascending)

Example Request

1 curl -H "Authorization: Bearer your_api_token" \
2   -H "Accept: application/json" \
3   https://freetodolist.com/lists/abc123.json?only_uncompleted=true
GET

Get All Lists

/api/v1/lists

Returns all lists belonging to the authenticated user. Archived lists are excluded by default.

Response
{
  "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",
      "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,
      "archived": false
    },
    // Additional lists...
  ]
}

Query Parameters

Parameter Type Description
include_archived boolean Include archived lists
sort string
Sort lists by:
name_asc - Name (ascending)
created_at_desc - Creation date (descending)
updated_at_asc - Last update (ascending)
items_count_desc - Number of items (descending)

Example Request

1 curl -H "Authorization: Bearer your_api_token" \
2   -H "Accept: application/json" \
3   https://freetodolist.com/lists.json?sort=updated_at_desc

Items Endpoint

GET

Get Items from a List

/api/v1/lists/:list_id/items

Returns all items from a specific list. Archived items are excluded by default.

Response
{
  "items": [
    {
      "uid": "01234567-89ab-cdef-0123-456789abcdef",
      "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,
      "list_uid": "abc123"
    },
    // Additional items...
  ]
}

Query Parameters

Parameter Type Description
include_archived boolean Include archived items in the response
only_completed boolean Only include completed items
only_uncompleted boolean Only include uncompleted items
due_before ISO8601 datetime Only include items due before this date
due_after ISO8601 datetime Only include items due after this date
sort string
Sort items by:
position_desc - Position (descending)
date_asc - Due date (ascending)
date_desc - Due date (descending)
created_asc - Creation date (ascending)
created_desc - Creation date (descending)
updated_asc - Last update (ascending)
updated_desc - Last update (descending)

Example Request

1 curl -H "Authorization: Bearer your_api_token" \
2   -H "Accept: application/json" \
3   https://freetodolist.com/api/v1/lists/abc123/items.json?only_uncompleted=true&sort=date_asc
POST

Create an Item

/api/v1/lists/:list_id/items

Creates a new item in the specified list.

Request Parameters

Parameter Type Description
item[body] string The content of the item (required)
item[complete] boolean Whether the item is completed (defaults to false)
item[due_at] ISO8601 datetime Due date for the item
item[archived] boolean Whether the item is archived (defaults to false)
position_at_top boolean Whether to add the item at the top of the list (default) or bottom
Response
{
  "item": {
    "uid": "fedcba98-7654-3210-fedc-ba9876543210",
    "body": "New item added via API",
    "complete": false,
    "position": 1,
    "created_at": "2025-04-09T14:22:15Z",
    "updated_at": "2025-04-09T14:22:15Z",
    "due_at": "2025-04-15T09:00:00Z",
    "completed_at": null,
    "archived": false,
    "list_uid": "abc123"
  },
  "message": "Item successfully created"
}

Example Request

1 curl -X POST -H "Authorization: Bearer your_api_token" \
2   -H "Content-Type: application/json" \
3   -H "Accept: application/json" \
4   -d '{"item": {"body": "New item added via API", "due_at": "2025-04-15T09:00:00Z"}}' \
5   https://freetodolist.com/api/v1/lists/abc123/items.json
GET

Get a Specific Item

/api/v1/items/:uid

Returns details about a specific item.

Response
{
  "item": {
    "uid": "01234567-89ab-cdef-0123-456789abcdef",
    "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,
    "list_uid": "abc123"
  }
}

Example Request

1 curl -H "Authorization: Bearer your_api_token" \
2   -H "Accept: application/json" \
3   https://freetodolist.com/api/v1/items/01234567-89ab-cdef-0123-456789abcdef.json
PATCH

Update an Item

/api/v1/items/:uid

Updates an existing item.

Request Parameters

Parameter Type Description
item[body] string The content of the item
item[complete] boolean Whether the item is completed
item[due_at] ISO8601 datetime Due date for the item
item[archived] boolean Whether the item is archived
item[completed_at] ISO8601 datetime When the item was completed
Response
{
  "item": {
    "uid": "01234567-89ab-cdef-0123-456789abcdef",
    "body": "Updated item via API",
    "complete": true,
    "position": 1,
    "created_at": "2025-04-05T13:14:15Z",
    "updated_at": "2025-04-09T14:25:10Z",
    "due_at": "2025-04-10T17:00:00Z",
    "completed_at": "2025-04-09T14:25:10Z",
    "archived": false,
    "list_uid": "abc123"
  },
  "message": "Item successfully updated"
}

Example Request

1 curl -X PATCH -H "Authorization: Bearer your_api_token" \
2   -H "Content-Type: application/json" \
3   -H "Accept: application/json" \
4   -d '{"item": {"body": "Updated item via API", "complete": true}}' \
5   https://freetodolist.com/api/v1/items/01234567-89ab-cdef-0123-456789abcdef.json
DELETE

Delete an Item

/api/v1/items/:uid

Permanently deletes an item.

Response
{
  "message": "Item successfully deleted"
}

Example Request

1 curl -X DELETE -H "Authorization: Bearer your_api_token" \
2   -H "Accept: application/json" \
3   https://freetodolist.com/api/v1/items/01234567-89ab-cdef-0123-456789abcdef.json

Dashboard Endpoint

GET

Get Dashboard Data

/api/v1/dashboard

Returns statistics about the user's lists and items, plus a summary of each list. This is useful for building dashboard widgets or overview screens.

Response
{
  "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...
  ]
}

Query Parameters

Parameter Type Description
sort string
position - Sort by position (default)
name - Sort by name
created_at - Sort by creation date
updated_at - Sort by last update
direction string Sort direction: asc or desc

Overdue Items Endpoint

GET

Get Overdue Items

/api/v1/overdue_items

Returns a list of all overdue items across all lists belonging to the authenticated user. Items from archived lists are excluded.

Response
{
  "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...
  ]
}

Example Request

1 curl -H "Authorization: Bearer your_api_token" \
2   -H "Accept: application/json" \
3   https://freetodolist.com/overdue_items.json

Note: This endpoint does not accept any additional parameters. Items are sorted by list name and then by due date.

Upcoming Due Items Endpoint

GET

Get Upcoming Due Items

/api/v1/items_due_dates

Returns a list of all upcoming due items (due today or in the future, within the next 30 days) across all lists belonging to the authenticated user. Items from archived lists are excluded.

Response
{
  "count": 5,
  "items": [
    {
      "body": "Review project documentation",
      "complete": false,
      "due_at": "2025-04-11T14:00:00Z",
      "days_until_due": 0,
      "position": 2,
      "created_at": "2025-04-09T10:12:15Z",
      "updated_at": "2025-04-09T10:12: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"
      }
    },
    {
      "body": "Schedule team meeting",
      "complete": false,
      "due_at": "2025-04-12T09:00:00Z",
      "days_until_due": 1,
      "position": 3,
      "created_at": "2025-04-09T11:22:30Z",
      "updated_at": "2025-04-09T11:22:30Z",
      "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 upcoming due items...
  ]
}

Example Request

1 curl -H "Authorization: Bearer your_api_token" \
2   -H "Accept: application/json" \
3   https://freetodolist.com/api/v1/items_due_dates.json

Note: This endpoint does not accept any additional parameters. Items are sorted by due date (ascending) and then by list name.

Shared Lists Endpoint

GET

Get a Shared List

/api/v1/shared/:token

Returns a shared list using its share token. No authentication is required for this endpoint.

Response
{
  "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
    },
    // Additional items...
  ]
}

Query Parameters

Parameter Type Description
include_archived boolean Include archived items
only_completed boolean Only include completed items
only_uncompleted boolean Only include uncompleted items
sort string
date_asc - Sort by due date (ascending)
completed - Group by completion status (completed first)
incomplete - Group by completion status (incomplete first)

Error Handling

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

Status Code Description
200 OK Request was successful
400 Bad Request Invalid request parameters
401 Unauthorized Authentication required
403 Forbidden You don't have permission to access this resource
404 Not Found Resource not found
422 Unprocessable Entity The request was well-formed but could not be processed
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error

Error Response Format

401 Unauthorized
{
  "error": "Authentication required"
}
422 Unprocessable Entity
{
  "success": false,
  "errors": ["Body can't be blank"]
}

Query Parameters

The API supports various query parameters to filter and sort the results. Here's a comprehensive list of available parameters:

Parameter Type Description Example
include_archived boolean Include archived items/lists in the response ?include_archived=true
only_completed boolean Only include completed items ?only_completed=true
only_uncompleted boolean Only include uncompleted items ?only_uncompleted=true
sort string Specify sorting field and direction ?sort=date_asc
direction string Specify sort direction (used with dashboard endpoint) ?sort=name&direction=desc

Combining Parameters

You can combine multiple parameters in a single request:

1 GET /api/v1/lists/abc123?sort=date_asc&only_uncompleted=true

Security Considerations

The FreeTodoList API is designed with security in mind:

  • Internal database IDs are never exposed in API responses
  • Lists are identified by unique, non-sequential UIDs
  • Authentication is required for accessing private data
  • Requests use the same permission model as the web interface
  • Shared lists are accessed using secure, random tokens
  • All requests are validated server-side to prevent unauthorized access

Security Best Practices

  • Regularly review your application's access to the API
  • Keep your API token secure and regenerate it if compromised
  • Don't share your API token with third parties
  • Disable list sharing when it's no longer needed
  • Report any security concerns to the FreeTodoList team

Integration Examples

JavaScript Example

JavaScript
// Fetch a list with its items using API token
async function getList(uid, apiToken) {
  const response = await fetch(`https://freetodolist.com/api/v1/lists/${uid}`, {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'Authorization': `Bearer ${apiToken}`
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error ${response.status}`);
  }
  
  return await response.json();
}

// Display the list
const apiToken = 'your_api_token'; // Get this from your Profile page
getList('abc123', apiToken)
  .then(data => {
    console.log(`List: ${data.list.name}`);
    console.log(`Items: ${data.items.length}`);
    
    // Display items
    data.items.forEach(item => {
      console.log(`- ${item.complete ? '✓' : '☐'} ${item.body}`);
    });
  })
  .catch(error => console.error('Error:', error));

Python Example

Python
import requests

# API token authentication method
class ApiClient:
    def __init__(self, api_token):
        self.api_token = api_token
        self.base_url = 'https://freetodolist.com/api/v1'
        self.headers = {
            'Authorization': f'Bearer {api_token}',
            'Accept': 'application/json'
        }
    
    def get_dashboard(self):
        response = requests.get(f'{self.base_url}/dashboard', headers=self.headers)
        response.raise_for_status()  # Raise exception for HTTP errors
        return response.json()
    
    def get_overdue_items(self):
        response = requests.get(f'{self.base_url}/overdue_items', headers=self.headers)
        response.raise_for_status()
        return response.json()
    
    def get_upcoming_due_items(self):
        response = requests.get(f'{self.base_url}/items_due_dates', headers=self.headers)
        response.raise_for_status()
        return response.json()
    
    def get_list(self, list_uid):
        response = requests.get(f'{self.base_url}/lists/{list_uid}', headers=self.headers)
        response.raise_for_status()
        return response.json()

# Main function using API token authentication
def main():
    # Initialize the API client with your token
    api_token = 'your_api_token'  # Get this from your Profile page
    client = ApiClient(api_token)
    
    # Get dashboard data
    dashboard = client.get_dashboard()
    print(f"You have {dashboard['stats']['lists_count']} lists")
    print(f"Completion rate: {dashboard['stats']['completion_percentage']}%")
    
    # Get overdue items
    overdue = client.get_overdue_items()
    print(f"You have {overdue['count']} overdue items:")
    for item in overdue['items']:
        print(f"- {item['body']} (Due: {item['due_at']})")
    
    # Get upcoming due items
    upcoming = client.get_upcoming_due_items()
    print(f"You have {upcoming['count']} upcoming items due:")
    for item in upcoming['items']:
        print(f"- {item['body']} (Due: {item['due_at']})")
    
    # Get a specific list
    list_data = client.get_list('abc123')
    print(f"List: {list_data['list']['name']}")
    print(f"Items: {len(list_data['items'])}")

if __name__ == '__main__':
    main()

cURL Example

Shell
# Set your API token as an environment variable
export API_TOKEN="your_api_token"  # Replace with your API token from Profile page

# Get a list with its items
curl -H "Authorization: Bearer $API_TOKEN" -H "Accept: application/json" \
  https://freetodolist.com/api/v1/lists/abc123

# Get dashboard data
curl -H "Authorization: Bearer $API_TOKEN" -H "Accept: application/json" \
  https://freetodolist.com/api/v1/dashboard

# Get overdue items
curl -H "Authorization: Bearer $API_TOKEN" -H "Accept: application/json" \
  https://freetodolist.com/api/v1/overdue_items

# Get a shared list (no authentication required)
curl -H "Accept: application/json" \
  https://freetodolist.com/api/v1/shared/def456

Support

Send Feedback

We'd love to hear about your experience using the API and any suggestions for improvement.

Send Feedback

API Blog Post

Read our announcement blog post for additional information and use cases.

Read Blog Post
Home New List Templates Login