LoginSign UpGet Demo
Get accountRequest Demo
DocumentationIntegrationsTools
BlogChangelogPricingLogin
Back

Todoist API Essential Guide

Aug 11, 2024 • 6 minute read

What type of API does Todoist provide?

REST API

Todoist primarily offers a REST API. The key points about Todoist's REST API are:

  1. It provides a simple way to consume the most basic features of the Todoist API.
  2. It uses standard REST principles like HTTP methods (GET, POST, PUT, DELETE) and resource-based URLs.
  3. Authentication is done via bearer tokens in the Authorization header.
  4. The API returns data in JSON format.

Other API Options

While REST is the main API, Todoist also offers:

  1. Sync API - An older API that allows for incremental syncing of full account data. It's recommended for clients maintaining a local representation of a user's full account.
  2. Client SDKs - Todoist provides official Python and JavaScript SDKs that simplify working with the REST API.

Key Considerations

  • The REST API is the recommended choice for most external developers and common application requirements.
  • For more complex syncing scenarios or maintaining full local account data, the Sync API may be more appropriate.
  • Todoist provides detailed documentation and getting started guides for their REST API.

In summary, while Todoist offers multiple API options, their primary and recommended API is a REST API, which should meet the needs of most developers integrating with Todoist.

Does the Todoist API have webhooks?

Here is the rewritten section with only the relevant content and a clear, precise tone:

Webhooks Support

The official Todoist API does support webhooks.

Webhook Events

You can subscribe to the following types of events with Todoist webhooks:

  • Items added
  • Items updated (changes to content, description, due_date and responsible_uid)
  • Items deleted
  • Items completed
  • Items uncompleted
  • Notes added
  • Notes updated (changes to content or file_name)
  • Notes deleted
  • Projects added
  • Projects updated (changes to name)
  • Projects deleted
  • Projects archived
  • Projects unarchived
  • Projects shared
  • Projects left

Key Points

  1. Webhooks allow applications to receive real-time notifications for subscribed user events.

  2. Webhook requests are sent as HTTPS POST payloads.

  3. Webhook URLs must use HTTPS and cannot specify ports for security reasons.

  4. Webhooks are activated when a user completes the OAuth flow for an app that declares the webhook.

  5. Webhook requests include headers like User-Agent, X-Todoist-Hmac-SHA256 for verification, and X-Todoist-Delivery-ID for uniqueness.

  6. The webhook payload contains information like event_name, user_id, event_data, version, and initiator.

Best Practices

  1. Use webhooks for notifications, not as a primary data source, due to potential out-of-order or failed deliveries.

  2. Implement proper security measures, including verifying the X-Todoist-Hmac-SHA256 header.

  3. Handle potential duplicate or out-of-order webhook deliveries in your application logic.

  4. For personal use, complete the OAuth process to activate webhooks for your own account.

By utilizing Todoist's webhook functionality, developers can create real-time integrations and automate workflows based on changes in Todoist data.

Rate Limits and other limitations

The API Rate Limits of the Todoist API are as follows:

Rate Limits for REST API

  1. For each user, you can make a maximum of 1000 requests within a 15 minute period [1].

Rate Limits for Sync API

The Sync API has different limits for full and partial syncs:

  1. For each user, you can make a maximum of 1000 partial sync requests within a 15 minute period [3].

  2. For each user, you can make a maximum of 100 full sync requests within a 15 minute period [3].

Key Points to Consider

  • It's recommended to perform a full sync only on the initial request and then use incremental syncs subsequently, as this is faster and more efficient [3].

  • You can reduce the number of requests by batching up to 100 commands in each request, which will still count as one request towards the rate limit [3].

Best Practices

  1. Use incremental syncs whenever possible to minimize the number of full sync requests.

  2. Implement batching of commands to reduce the overall number of requests made to the API.

  3. Monitor your API usage to ensure you stay within the rate limits.

  4. Implement proper error handling and backoff strategies in case you hit the rate limits.

By adhering to these rate limits and following the best practices, you can ensure efficient and compliant use of the Todoist API in your applications.

Latest API Version

The most recent version of the Todoist API is REST API v2. Here are the key points:

Current API Version

  • The latest version of the Todoist API is REST API v2.

Key Points

  • The REST API v2 is the recommended API for external developers.
  • It offers a simpler approach to read and write data on the Todoist web service compared to the older Sync API.
  • The REST API uses a familiar RESTful approach that should be easy for developers with API experience.

Client SDKs

  • Todoist provides official Python and JavaScript SDKs to simplify working with the API.
  • The JavaScript SDK is available as the todoist-api-typescript package on npm.
  • The Python SDK is available as the todoist-api-python package on PyPI.

API Documentation

  • The full documentation for the REST API v2 is available at https://developer.todoist.com/rest/v2/.
  • It includes details on all available endpoints and parameters for various Todoist entity types.

Best Practices

  • For most common application requirements, the REST API v2 is recommended over the older Sync API.
  • Developers should refer to the "Getting Started" tutorial in the API documentation to learn about common flows and basic concepts.
  • When implementing authentication for other users, developers should follow the guidelines in the Authorization guide.

By using the latest REST API v2, developers can take advantage of the most up-to-date features and improvements in the Todoist API.

How to get a Todoist developer account and API Keys?

1. Create a Todoist account

If you don't already have one, sign up for a free Todoist account at https://todoist.com.

2. Access the App Management Console

Go to the Todoist App Management Console at https://developer.todoist.com/appconsole.html.

3. Create a new app

In the App Management Console:

  • Click on "Create a new app"
  • Fill out the required information for your app, including:
    • App name
    • App description
    • App website
    • OAuth redirect URL (if using OAuth)

4. Get your API credentials

Once your app is created, you'll receive:

  • Client ID
  • Client Secret (for OAuth)
  • Your personal API token

5. Set up OAuth (optional)

If you want to access other users' data, you'll need to implement OAuth:

  • Configure a valid OAuth redirect URL in your app settings
  • Use the OAuth flow to obtain user-authorized API tokens

6. Start developing

You can now start using the Todoist API:

  • Use the REST API for simple read/write operations
  • Use the Sync API for more complex syncing scenarios
  • Refer to the API documentation for endpoints and parameters

What can you do with the Todoist API?

Based on the search results provided, here is a list of the main data models you can interact with using the Todoist API, along with key points about what is possible for each:

Projects

  • Create new projects
  • Update project details (e.g. name)
  • Delete projects
  • Archive and unarchive projects
  • Move projects in the hierarchy (change parent project)
  • Reorder projects
  • Share projects with collaborators

Tasks (Items)

  • Add new tasks
  • Update task details (content, description, due date, etc.)
  • Delete tasks
  • Complete and uncomplete tasks
  • Move tasks between projects or change parent task
  • Reorder tasks
  • Archive and unarchive tasks

Sections

  • Add sections to projects
  • There is a limit on the maximum number of sections per project (e.g. 20 for free plans)

Labels

  • Create and manage labels
  • There is a limit on the maximum number of labels (e.g. 500 for free plans)

Filters

  • Create and manage filters
  • There is a limit on the maximum number of filters (e.g. 3 for free plans)

Comments

  • Add comments to tasks

Reminders

  • Add reminders to tasks
  • There are limits on the number of time-based and location-based reminders

Notes

  • Add notes to tasks
  • Update note content
  • Delete notes

User Data

  • Retrieve user information and settings
  • Update user settings

Activity Log

  • Retrieve logged events for various actions (task additions, updates, completions, etc.)

Collaborators

  • Manage project collaborators
  • There is a limit on the maximum number of collaborators per project (e.g. 5 for free plans)

Attachments/Uploads

  • Upload files to tasks (with size limits)

Key points to consider:

  • The API offers both REST and Sync endpoints, with the Sync API designed for efficient data syncing
  • There are limits on various features depending on the user's plan (e.g. number of projects, tasks, labels, etc.)
  • The API supports batching requests to reduce network calls
  • Authentication is required using a user token
  • Some operations support bulk actions (e.g. moving multiple items at once)

Ship integrations on autopilot

Get Demo
Resources
DocumentationIntegrationsAPI Integration GuidesBlogChangelogPricingSupport
Legal
Terms of ServicePrivacy PolicyGoogle API
© 2024 Playbook Software Inc.