Getting started overview

Integrating with Todoist requires setting up a developer account, obtaining an API token, and then using this token to authenticate requests to the Todoist API. This guide outlines the necessary steps to make your first successful API call, focusing on rapid setup and execution. The Todoist API allows developers to programmatically manage tasks, projects, and other Todoist entities, supporting a range of custom integrations and automated workflows.

Before proceeding, ensure you have an active Todoist account. While Todoist offers both free and paid tiers, the core API functionality is accessible across all account types, with potential rate limits or feature availability varying based on your subscription level. For detailed information on subscription benefits, refer to the official Todoist pricing page.

Quick Reference Steps

The following table provides a high-level overview of the getting started process:

Step What to Do Where
1. Create Account Sign up for a Todoist account if you don't have one. Todoist Homepage
2. Get API Token Generate a personal API token from your Todoist settings. Todoist Integration Settings
3. Understand API Review the API documentation for endpoints and request formats. Todoist API Documentation for Developers
4. Make Request Construct and send your first authenticated API call. Your preferred HTTP client (e.g., cURL, Postman)

Create an account and get keys

To interact with the Todoist API, you first need a Todoist account. If you do not have one, you can register for free on the Todoist website. Once your account is active, you will need to generate an API token, which serves as your authentication credential for API requests.

Generating Your Todoist API Token

  1. Log In: Navigate to the Todoist login page and sign in with your credentials.
  2. Access Settings: Click on the gear icon (Settings) in the top-right corner of the Todoist web application.
  3. Go to Integrations: In the settings menu, select the "Integrations" tab.
  4. Locate API Token: Scroll down to the "Developer" section within the Integrations settings. Your personal API token will be displayed there. It is typically a long alphanumeric string.
  5. Copy Token: Copy this token securely. This token grants access to your Todoist data, so treat it like a password.

The API token is a Bearer token, which means it should be included in the Authorization header of your HTTP requests in the format Bearer YOUR_API_TOKEN. For more information on token-based authentication, refer to the OAuth 2.0 Bearer Token Usage specification.

Your first request

With your API token in hand, you can now make your first authenticated request to the Todoist API. A common starting point is to fetch a list of your active projects. This demonstrates successful authentication and interaction with a core Todoist resource.

The Todoist API is a RESTful API, primarily communicating via JSON over HTTP. The base URL for the API is https://api.todoist.com/rest/v2/.

Example: Fetching Active Projects

Let's use curl to make a simple GET request to the /projects endpoint.

curl -X GET \ 
  https://api.todoist.com/rest/v2/projects \ 
  -H "Authorization: Bearer YOUR_API_TOKEN"

Replace YOUR_API_TOKEN with the actual token you copied from your Todoist settings.

Expected Response:

A successful response will return a JSON array of your projects, similar to this (truncated for brevity):

[
  {
    "id": "2203306141",
    "name": "Work",
    "comment_count": 0,
    "order": 1,
    "color": "grey",
    "is_shared": false,
    "is_favorite": false,
    "sync_id": 0,
    "url": "https://todoist.com/app/project/2203306141"
  },
  {
    "id": "2203306142",
    "name": "Personal",
    "comment_count": 0,
    "order": 2,
    "color": "red",
    "is_shared": false,
    "is_favorite": false,
    "sync_id": 0,
    "url": "https://todoist.com/app/project/2203306142"
  }
]

If you receive a 200 OK status code and a JSON array containing your projects, your first API call was successful!

Common next steps

After successfully making your first API call, you can explore more advanced functionalities of the Todoist API. Here are some common next steps:

  • Create a Task: Use the POST /tasks endpoint to programmatically add new tasks to your projects. This is a fundamental operation for many integrations.
  • Update a Task: Modify existing tasks using the POST /tasks/{task_id} endpoint, allowing you to change due dates, priorities, or assignees.
  • Complete a Task: Mark tasks as complete using the POST /tasks/{task_id}/close endpoint.
  • Explore Webhooks: For real-time updates, investigate Todoist webhooks. Webhooks allow your application to receive notifications when specific events occur in Todoist, such as a task being created or completed. Refer to the Todoist Webhooks documentation for setup instructions.
  • OAuth Integration: If you're building an application for multiple users, consider implementing OAuth 2.0 for secure user authorization without requiring users to share their personal API tokens. The Todoist API supports the OAuth 2.0 authorization code flow.
  • Rate Limits: Familiarize yourself with the Todoist API rate limits to ensure your application behaves responsibly and avoids being throttled.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for common problems:

  • 401 Unauthorized: This is almost always due to an incorrect or missing API token.
    • Check Token: Double-check that you copied the entire API token correctly from your Todoist integration settings.
    • Bearer Prefix: Ensure the Authorization header is formatted as Bearer YOUR_API_TOKEN with a space between "Bearer" and your token.
    • Expired Token: Though less common for personal tokens, confirm your token has not been revoked or expired. Regenerate if necessary.
  • 400 Bad Request: This indicates an issue with your request body or parameters.
    • Endpoint Correctness: Verify the API endpoint URL (e.g., /projects) is exactly as specified in the Todoist API reference.
    • JSON Format: If you are sending a POST or PUT request, ensure your JSON payload is well-formed and valid. Use a JSON validator if unsure.
  • 404 Not Found: The requested resource could not be found.
    • URL Path: Confirm the entire URL, including the base URL and endpoint path, is correct.
    • Resource ID: If fetching a specific task or project, ensure the ID is valid and belongs to your account.
  • Network Issues: Ensure your internet connection is stable and that no firewalls or proxies are blocking your outgoing requests to api.todoist.com.
  • Consult Documentation: The official Todoist API documentation includes detailed error codes and explanations for specific endpoints, which is the best resource for deeper troubleshooting.